Documentation Oracle Cloud Infrastructure

Instructions relatives aux outils d'appel d'adresse d'API pour les agents d'IA générative

Définissez un outil d'appel d'adresse d'API dans les agents d'IA générative pour interagir avec les API et les API OCI et les appeler.

Les informations fournies dans cette rubrique partent du principe que vous connaissez les réseaux cloud virtuels OCI, les sous-réseaux et les règles de sécurité, comment déployer des applications sur des instances de calcul OCI et les principes de base de l'utilisation de l'interface de programmation d'application REST (REpresentational State Transfer Application Programming Interface).

Voici un aperçu de la prise en main :

  1. Créez un schéma OpenAPI qui définit les formats de demande et de réponse et les opérations disponibles. Incluez l'en-tête x-requires-approval dans le schéma, si nécessaire.
  2. Configurez une méthode d'authentification. Selon le type d'authentification que vous utilisez, créez une clé secrète de coffre pour les informations d'identification que vous devez fournir.
  3. Configurez les ressources réseau OCI. Un réseau cloud virtuel (VCN) est requis.
  4. Passez en revue les stratégies IAM et ajoutez celles requises. Par exemple, Networking et Vault.

Schéma d'API

La structure et le comportement des opérations d'API doivent être définis dans un schéma OpenAPI écrit au format JSON ou YAML.

Lorsque vous utilisez la console pour créer un outil d'appel d'adresse d'API dans les agents d'IA générative, vous pouvez télécharger le schéma manuellement en le copiant et en le collant dans une zone de texte, ou vous pouvez sélectionner le schéma qui a été téléchargé vers Object Storage.

La taille de fichier maximale et les versions prises en charge sont les suivantes :

  • Versions :
    • OpenAPI : versions 3.0 et ultérieures
    • JSON : schéma JSON standard tel que défini dans la RFC 8259
    • YAML : version 1.2 et ultérieure
  • Taille maximale de fichier :
    • Collage en ligne : 1 000 000 caractères
    • Fichier dans Object Storage : 20 Mo
Exemple de schéma d'API dans JSON
{
  "openapi": "3.0.0",
  "info": {
    "title": "Object Storage API",
    "version": "1.0.0",
    "description": "API to create an Object Storage bucket in Oracle Cloud."
  },
  "servers": [
    {
      "url": "https://objectstorage.<region>.oraclecloud.com"
    }
  ],
  "paths": {
    "/n/yourNamespace/b": {
      "post": {
        "summary": "Create a Bucket",
        "operationId": "createBucket",
        "parameters": [
          {
            "name": "namespaceName",
            "in": "path",
            "required": true,
            "description": "The Object Storage namespace used for the request.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "bucket_name": {
                    "type": "string",
                    "description": "The name of the bucket to create."
                  },
                  "compartment_ocid": {
                    "type": "string",
                    "description": "The OCID of the compartment where the bucket will be created."
                  },
                  "storage_tier": {
                    "type": "string",
                    "enum": [
                      "Standard",
                      "Archive"
                    ],
                    "description": "The storage tier for the bucket."
                  }
                },
                "required": [
                  "bucket_name",
                  "compartment_ocid"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bucket created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bucket_name": {
                      "type": "string"
                    },
                    "namespace": {
                      "type": "string"
                    },
                    "time_created": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input."
          },
          "500": {
            "description": "Internal server error."
          }
        }
      }
    }
  }
}
Exemple de schéma d'API dans YAML
openapi: "3.0.0"
info:
	title: "Object Storage API"
	version: "1.0.0"
	description: "API to create an Object Storage bucket in Oracle Cloud."

servers:
	- url: "https://objectstorage.<region>.oraclecloud.com"

paths:
	/n/yourNamespace/b:
		post:
			summary: "Create a Bucket"
			operationId: "createBucket"
			parameters:
				- name: namespaceName
					in: path
					required: true
					description: "The Object Storage namespace used for the request."
					schema:
						type: string
			requestBody:
				required: true
				content:
					application/json:
						schema:
							type: object
							properties:
								bucket_name:
									type: string
									description: "The name of the bucket to create."
								compartment_ocid:
									type: string
									description: "The OCID of the compartment where the bucket will be created."
								storage_tier:
									type: string
									enum:
										- Standard
										- Archive
									description: "The storage tier for the bucket."
							required:
								- bucket_name
								- compartment_ocid
							additionalProperties: false
			responses:
				"200":
					description: "Bucket created successfully."
					content:
						application/json:
							schema:
								type: object
								properties:
									bucket_name:
										type: string
									namespace:
										type: string
									time_created:
										type: string
										format: date-time
				"400":
					description: "Invalid input."
				"500":
					description: "Internal server error."

Approbation humaine en boucle

Pour les opérations d'API susceptibles de modifier un état, nous vous recommandons d'inclure l'en-tête x-requires-approval dans le schéma pour indiquer qu'une action d'outil nécessite une approbation HITL (Human-in-the-loop). L'implication d'êtres humains dans des opérations critiques est généralement recommandée pour les types d'opérations suivants, car ils peuvent entraîner des changements injustifiés :

  • POST
  • PUT
  • PATCH
  • DELETE

Exemple d'inclusion de x-requires-approval dans un schéma AI YAML :

parameters:
  - in: header
    name: x-requires-approval
    required: false
    schema:
      type: string
    description: 
      Indicates that this operation requires human approval before execution.

L'inclusion de l'en-tête x-requires-approval indique aux agents d'IA générative qu'une confirmation doit être demandée à un humain avant d'exécuter l'adresse d'API dans l'appel de l'outil d'agent.

Lorsque l'en-tête d'approbation est inclus dans le schéma, l'en-tête :

  • Déclenche l'action requise HumanApprovalRequiredAction dans l'étape de trajectoire
  • Empêche les effets indésirables involontaires sans surveillance humaine
  • Permet une utilisation sûre des outils qui effectuent des opérations d'écriture, de mise à jour ou de suppression.

Authentification

Dans les agents d'IA génératifs, un outil d'appel d'adresse d'API peut être configuré pour utiliser l'authentification ou ne pas l'utiliser lors de l'exécution d'une demande d'exécution d'une opération d'API.

Reportez-vous aux sections suivantes pour plus d'informations sur les mécanismes d'authentification pris en charge et les tâches prérequises que vous devez effectuer pour un type d'authentification.

Authentification par clé d'API

Pour les adresses d'API publiques et privées qui nécessitent une clé d'API.

Une clé d'API est un identifiant unique obtenu à partir de la plate-forme du fournisseur d'API. Lorsqu'un client tel qu'une application ou un service envoie une demande à l'API, la clé d'API est utilisée pour authentifier le client.

Dans les agents d'IA générative, l'authentification par clé d'API est prise en charge par les types suivants :

  • En-tête : transmettez la clé d'API dans l'en-tête d'une demande HTTP.

    Les paramètres d'en-tête d'API sont des paires clé-valeur incluses dans une demande ou une réponse HTTP afin de fournir des métadonnées supplémentaires sur la demande ou la réponse.

  • Paramètre de requête : transmettez la clé d'API directement dans l'URL en tant que paramètre de requête.

    Les paramètres de requête sont un ensemble défini de paramètres (paires clé-valeur) attachés à la fin d'une URL utilisée pour fournir des informations supplémentaires à un serveur Web lors de demandes.

Créez une clé secrète dans OCI Vault pour stocker la clé d'API. Si vous avez besoin d'aide pour créer une clé secrète, reportez-vous à Création d'une clé secrète dans la documentation du service Vault.

Lorsque vous configurez un outil d'appel d'adresse d'API avec l'authentification de clé d'API, vous indiquez l'emplacement de la clé (en-tête ou paramètre de requête), le nom de la clé et la clé secrète de coffre contenant la clé d'API.

Reportez-vous également à Stratégies pour la clé secrète de coffre.

Authentification de référence

Pour appeler des adresses d'API publiques et privées à l'aide d'un nom utilisateur et d'un mot de passe.

L'authentification de base utilise vos identifiants de nom utilisateur et de mot de passe au format requis suivant :

<your-username>:<your-password>

Créez une clé secrète dans OCI Vault pour stocker les informations d'identification au format requis. Si vous avez besoin d'aide pour créer une clé secrète, reportez-vous à Création d'une clé secrète dans la documentation du service Vault.

Lorsque vous configurez un outil d'appel d'adresse d'API avec une authentification de base, vous fournissez la clé secrète du coffre.

Reportez-vous également à Stratégies pour la clé secrète de coffre.

Authentification du porteur

Pour appeler des adresses d'API privées à l'aide d'un jeton Bearer.

Un jeton de support est un jeton d'accès utilisé dans l'authentification OAuth 2.0 pour autoriser ou accorder l'accès aux ressources protégées. L'authentification au porteur est une méthode d'authentification dans laquelle le client envoie un jeton au porteur dans le cadre de la demande dans l'en-tête d'autorisation, qui est validée pour authentifier la demande. Nous vous recommandons d'utiliser des jetons de longue durée tels que des clés d'API.

Créez une clé secrète dans OCI Vault pour stocker le jeton. Si vous avez besoin d'aide pour créer une clé secrète, reportez-vous à Création d'une clé secrète dans la documentation du service Vault.

Lorsque vous configurez un outil d'appel d'adresse d'API avec une authentification au porteur, vous fournissez la clé secrète du coffre.

Reportez-vous également à Stratégies pour la clé secrète de coffre.

Authentification IDCS

Pour appeler des adresses d'API privées à l'aide des informations d'identification de client d'application confidentielles Oracle Identity Cloud Service (IDCS).

Une application confidentielle est conçue pour authentifier et autoriser en toute sécurité les applications client à l'aide de OAuth 2.0. Les informations d'identification client sont l'ID client et la clé secrète client d'une application confidentielle enregistrée pour une application client.

Utilisez OCI IAM avec des domaines d'identité pour créer une application confidentielle. Vous devez disposer du rôle d'administrateur de domaine d'identité ou d'administrateur d'application pour créer des applications confidentielles dans un domaine d'identité.

Pour créer une application confidentielle, procédez comme suit :

  1. Ouvrez le menu de navigation et sélectionnez Identité et sécurité. Sous Identité, sélectionnez Domaines.
  2. Dans la liste des domaines d'un compartiment, sélectionnez le domaine dans lequel créer l'application confidentielle.
  3. Créez et activez une application confidentielle.

    Pour la configuration OAuth, sélectionnez Configuration client et utilisez les informations d'identification client.

    Si vous avez besoin d'aide, reportez-vous à Création d'une application confidentielle dans la documentation d'OCI IAM avec des domaines d'identité.

  4. Copiez les valeurs d'ID client et de clé secrète client générées dans l'application confidentielle. Stockez les valeurs dans un endroit sûr.
  5. Dans OCI Vault, créez une clé secrète pour stocker la clé secrète client de l'application confidentielle. Vous devez fournir la clé secrète de coffre lorsque vous configurez un outil d'appel d'adresse d'API avec l'authentification IDCS.
    Remarque

    Les appels inter-région de la location de service d'agent ne sont pas pris en charge. Par exemple, si l'outil d'appel d'adresse d'API configuré avec l'authentification IDCS se trouve dans la région A, vous ne devez pas sélectionner de coffre avec la région maître B.

    Si vous avez besoin d'aide pour créer une clé secrète, reportez-vous à Création d'une clé secrète dans la documentation du service Vault.

    Reportez-vous également à Stratégies pour la clé secrète de coffre.

Authentification de principal de ressource OCI

Uniquement pour l'appel d'API OCI telles qu'Object Storage et Networking.

Un principal de ressource permet aux services de s'authentifier en toute sécurité avec les ressources de service OCI et OCI sans avoir besoin d'informations d'identification explicites. Les stratégies OCI IAM sont utilisées pour authentifier l'accès. Par exemple :

// To enable Object Storage access in all compartments in the tenancy
allow any-user to manage object-family in tenancy where any {request.principal.type='genaiagent'}

Les stratégies IAM que vous écrivez dépendent des API de service OCI que vous appelez et du fait que vous utilisiez un groupe dynamique. Reportez-vous à Stratégies pour les services OCI.

Ressources réseau

Lorsque vous créez un outil d'appel d'adresse d'API dans les agents d'IA générative, vous devez sélectionner un réseau cloud virtuel (VCN) et un sous-réseau.

Que l'URL cible soit privée ou publique, toutes les demandes effectuées par les outils d'appel d'adresse d'API transitent par le sous-réseau. Cela inclut les appels REST vers des fournisseurs tiers, les services internes hébergés dans votre VCN et les API publiques OCI.

Configurez les ressources réseau dont vous avez besoin dans OCI.

VCN et sous-réseau

  • Un réseau cloud virtuel (VCN) est requis.

  • Vous pouvez disposer d'un sous-réseau privé ou public. Un sous-réseau privé est recommandé.

  • Un sous-réseau privé nécessite une passerelle NAT.

  • Un sous-réseau public requiert une passerelle Internet. Selon la configuration de votre environnement, un sous-réseau public peut nécessiter une passerelle Internet et une passerelle NAT.

    Pour appeler des API publiques sans authentification, assurez-vous que le sous-réseau public est configuré pour une passerelle NAT avec tout le trafic de port activé pour la sortie.

API Gateway pour le DNS privé

Une passerelle d'API peut être créée pour le trafic vers des applications sur des instances privées.

Sélectionnez le type Privé lorsque vous créez la passerelle d'API pour un DNS privé.

Dans le sous-réseau privé, assurez-vous que les deux règles sortantes suivantes sont disponibles :

  • Le port 443 est utilisé par la passerelle d'API pour la communication.
  • Port où l'application privée est hébergée. La passerelle d'API envoie une demande à ce port (par exemple, 9090).

Lorsque vous utilisez l'authentification IDCS avec des adresses privées, veillez à remplacer l'URL de base par l'URL de service API Gateway dans le schéma OpenAPI. La passerelle d'API doit pointer vers l'instance en cours d'exécution dans un sous-réseau privé.

Configuration de réseau privé
VCN :

  • Créez un VCN dans la région et le compartiment de votre choix.

  • Indiquez le bloc CIDR pour le VCN (par exemple, 10.0.0.0/16).

  • Vous pouvez choisir d'activer la résolution DNS pour le VCN.

Sous-réseau privé:

  • Créez un sous-réseau privé dans le VCN que vous avez créé en sélectionnant le même compartiment que le VCN.

  • Indiquez le bloc CIDR pour le sous-réseau (par exemple, 10.0.1.0/24).

  • Vous pouvez choisir d'activer la résolution DNS pour le sous-réseau.

Instance de calcul privée :

  • Dans le même compartiment que le VCN et le sous-réseau, créez une instance Compute privée, en sélectionnant le VCN et le sous-réseau privé que vous avez créés.

  • Si vous voulez accéder à l'instance par SSH, fournissez votre clé publique SSH.

Règles sortantes :

  • Autoriser les connexions sortantes aux services requis (par exemple, Object Storage, API externes, si nécessaire).

  • Ouvrez le port TCP 443 pour HTTPS.

Règles entrantes :

  • Autoriser le trafic entrant uniquement à partir des plages d'adresses IP de la plate-forme OCI.

  • Limitez-vous aux ports nécessaires (généralement TCP 443).

Règle UDP entrante :

  • Ajoutez une règle entrante pour le port UDP 53.

    Ajoutez la règle UDP à la liste de sécurité par défaut du service d'agent et de vos sous-réseaux VCN (clients) pour autoriser la redirection et la résolution DNS.

Configuration du réseau public

Configurez des restrictions entrantes et sortantes similaires, mais exposées à Internet. Utilisez des listes de contrôle d'accès (ACL) strictes.

Résolution DNS

Pour faciliter la résolution DNS pour les applications privées :

  • Autorisez le port UDP 53 sur vos listes de pare-feu/sécurité pour le trafic DNS.

  • Configurez des règles/transferts DNS pour diriger le trafic vers vos adresses d'application privées.

  • Assurez-vous que le port UDP entrant 53 est ouvert à la fois dans le service d'agent et dans vos listes de sécurité de sous-réseau VCN (client).

Assurez-vous que la plate-forme OCI peut résoudre les noms de domaine associés à vos applications privées.

Documentation de référence réseau

Si vous avez besoin d'aide, reportez-vous à la documentation de service suivante :

Stratégies IAM

Veillez à accorder aux utilisateurs l'accès à toutes les ressources des agents d'IA générative, comme décrit dans Ajout de stratégies pour pouvoir utiliser le service.

Consultez également les sections suivantes et écrivez les stratégies dont vous avez besoin.

Stratégies pour le réseau

La stratégie pour le type agrégé de ressource virtual-network-family est requise.

Vous pouvez utiliser les stratégies suivantes pour activer l'accès à Networking dans tous les compartiments de la location ou pour restreindre l'accès à un compartiment spécifique. 

// To enable access to all compartments in the tenancy
allow group <group-name> to manage virtual-network-family in tenancy 

// To enable access to a specific compartment in the tenancy
allow group <group-name> to manage virtual-network-family in compartment <compartment-name>
Stratégies pour les services OCI

Lorsque vous créez un outil d'appel d'adresse d'API et que vous configurez l'outil pour utiliser l'authentification de principal de ressource OCI, vous devez ajouter des stratégies afin d'accorder les droits d'accès appropriés aux opérations d'API du service OCI que l'agent doit appeler.

Référence : référence de stratégie de service détaillée dans IAM avec des domaines d'identité

Les stratégies OCI IAM dont vous avez besoin dépendent des API de service OCI que vous appelez et de l'utilisation d'un groupe dynamique.

Utiliser le groupe dynamique

  1. Créez un groupe dynamique et ajoutez la règle suivante de mise en correspondance.

    ALL {resource.type='genaiagent'}

    Si vous avez besoin d'aide, reportez-vous à Création d'un groupe dynamique.

  2. Ajoutez une stratégie pour donner au groupe dynamique le niveau d'accès approprié à un type de ressource. Par exemple, pour appeler les API du service Object Storage, vous pouvez utiliser manage object-family ou read objects.

    • Les stratégies suivantes peuvent être utilisées avec le domaine d'identité par défaut :

      allow dynamic-group <dynamic-group-name> 
to <verb> <resource type> in compartment <compartment-name>

allow dynamic-group <dynamic-group-name> 
to <verb> <resource type> in tenancy

    • Utilisez les stratégies suivantes avec un domaine d'identité non par défaut, en indiquant le nom de domaine Oracle Identity Cloud Service (IDCS) et le nom de groupe dynamique : 

      allow dynamic-group '<idcs-domain-name>/<dynamic-group-name>' 
to <verb> <resource type> in compartment <compartment-name>

allow dynamic-group '<idcs-domain-name>/<dynamic-group-name>' 
to <verb> <resource type> in tenancy

Sans groupe dynamique

Ajoutez une stratégie pour accorder le niveau d'accès approprié à un type de ressource. Par exemple, pour appeler les API du service Object Storage, vous pouvez utiliser manage object-family ou read objects.

allow any-user to <verb> <resource type> in tenancy where any {request.principal.type='genaiagent'}

Stratégies pour la clé secrète de coffre

La méthode d'authentification que vous utilisez peut nécessiter que vous fournissiez des informations d'identification stockées dans une clé secrète OCI Vault.

La stratégie IAM permettant d'accéder aux clés secrètes de coffre dépend du fait que vous utilisez un groupe dynamique ou non.

Utiliser le groupe dynamique

  1. Créez un groupe dynamique et ajoutez la règle suivante de mise en correspondance.

    ALL {resource.type='genaiagent'}

    Si vous avez besoin d'aide, reportez-vous à Création d'un groupe dynamique.

  2. Les stratégies suivantes peuvent être utilisées avec le domaine d'identité par défaut :

    • allow dynamic-group <dynamic-group-name> 
to read secret-family in compartment <compartment-name>

allow dynamic-group <dynamic-group-name> 
to read secret-family in tenancy

    • Utilisez les stratégies suivantes avec un domaine d'identité non par défaut, en indiquant le nom de domaine Oracle Identity Cloud Service (IDCS) et le nom de groupe dynamique : 

      allow dynamic-group '<idcs-domain-name>/<dynamic-group-name>' 
to read secret-family in compartment <compartment-name>

allow dynamic-group '<idcs-domain-name>/<dynamic-group-name>' 
to read secret-family in tenancy

Sans groupe dynamique

La stratégie suivante peut être utilisée.

allow any-user to read secret-family in tenancy where any {request.principal.type='genaiagent'}