Documentation sur Oracle Cloud Infrastructure

Directives de l'outil d'appel de point d'extrémité d'API pour les agents d'IA générative

Définissez un outil d'appel de point d'extrémité d'API dans les agents d'IA générative pour interagir et appeler des interfaces de programmation d'application externes (API) et des API OCI.

Les informations fournies dans cette rubrique supposent que vous connaissez les réseaux en nuage virtuels (VCN), les sous-réseaux et les règles de sécurité OCI, la façon de déployer des applications sur des instances de calcul OCI et les principes fondamentaux de l'utilisation de l'interface de programmation d'application REpresentational State Transfer (API REST).

Voici un aperçu de la façon de commencer :

  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 chambre forte pour les données d'identification que vous devez fournir.
  3. Configurer les ressources de réseau OCI. Un réseau en nuage virtuel (VCN) est requis.
  4. Passer en revue les politiques IAM et ajouter celles requises. Par exemple, Réseau et chambre forte.

Schéma d'API

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

Lorsque vous utilisez la console pour créer un outil d'appel de point d'extrémité d'API dans les agents d'IA générative, vous pouvez 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é chargé dans le stockage d'objets.

La taille maximale des fichiers et les versions prises en charge sont les suivantes :

  • prises en charge :
    • OpenAPI : 3.0 et versions ultérieures
    • JSON : Schéma JSON standard défini dans la norme RFC 8259
    • YAML : version 1.2 et ultérieure
  • Taille maximale des fichiers :
    • Collage en ligne : 1 000 000 caractères
    • Fichier dans le stockage d'objets : 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 en boucle

Pour les opérations d'API qui peuvent modifier un état, nous 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 des humains dans des opérations critiques est généralement recommandée pour les types d'opérations suivants, car ils peuvent potentiellement provoquer des modifications non justifiées :

  • POST
  • PUT
  • PATCH
  • DELETE

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

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

L'en-tête x-requires-approval indique aux agents d'intelligence artificielle générative qu'une confirmation doit être demandée à un humain avant d'exécuter le point d'extrémité d'API dans l'appel de l'outil de l'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
  • Prévient les effets secondaires involontaires sans surveillance humaine
  • Permet une utilisation sécurisée des outils qui effectuent des opérations d'écriture, de mise à jour ou de suppression.

Authentification

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

Consultez les sections suivantes pour plus d'informations sur les mécanismes d'authentification pris en charge et les tâches préalables à effectuer pour un type d'authentification.

Authentification par clé d'API

Pour les points d'extrémité d'API publics et privés qui nécessitent une clé d'API.

Une clé d'API est un identificateur unique obtenu à partir de la plate-forme du fournisseur d'API. Lorsqu'un client tel qu'une application ou un service fait 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 pour fournir des métadonnées supplémentaires sur la demande ou la réponse.

  • Paramètre d'interrogation : Transmettez la clé d'API directement dans l'URL en tant que paramètre d'interrogation.

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

Créez une clé secrète dans le service de chambre forte OCI pour stocker la clé d'API. Si vous avez besoin d'aide pour créer une clé secrète, voir Création d'une clé secrète dans la documentation du service de chambre forte.

Lorsque vous configurez un outil d'appel de point d'extrémité d'API avec authentification par clé d'API, vous spécifiez l'emplacement de la clé (en-tête ou paramètre d'interrogation), le nom de la clé et la clé secrète de chambre forte qui contient la clé d'API.

Voir aussi Politiques pour la clé secrète de la chambre forte.

Authentification de base

Pour appeler des points d'extrémité d'API publics et privés à l'aide d'un nom d'utilisateur et d'un mot de passe.

L'authentification de base utilise vos données d'identification de nom d'utilisateur et de mot de passe dans le format requis suivant :

<your-username>:<your-password>

Créez une clé secrète dans le service de chambre forte OCI pour stocker les données d'identification dans le format requis. Si vous avez besoin d'aide pour créer une clé secrète, voir Création d'une clé secrète dans la documentation du service de chambre forte.

Lorsque vous configurez un outil d'appel de point d'extrémité d'API avec l'authentification de base, vous fournissez la clé secrète de chambre forte.

Voir aussi Politiques pour la clé secrète de la chambre forte.

Authentification du porteur

Pour appeler des points d'extrémité d'API privés à l'aide d'un jeton de porteur.

Un jeton de porteur 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 où le client envoie un jeton au porteur dans le cadre de la demande dans l'en-tête Autorisation, qui est validée pour authentifier la demande. Nous recommandons d'utiliser des jetons de longue durée tels que des clés d'API.

Créez une clé secrète dans le service de chambre forte OCI pour stocker le jeton. Si vous avez besoin d'aide pour créer une clé secrète, voir Création d'une clé secrète dans la documentation du service de chambre forte.

Lorsque vous configurez un outil d'appel de point d'extrémité d'API avec authentification au porteur, vous fournissez la clé secrète de la chambre forte.

Voir aussi Politiques pour la clé secrète de la chambre forte.

Authentification IDCS

Pour appeler des points d'extrémité d'API privés à l'aide des données d'identification de client d'application confidentielle Oracle Identity Cloud Service (IDCS).

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

Utiliser OCI IAM avec des domaines d'identité pour créer une application confidentielle. Notez que 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 :

  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 vous voulez créer l'application confidentielle.
  3. Créer et activer une application confidentielle.

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

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

  4. Copiez l'ID client et les valeurs de clé secrète client générées dans l'application confidentielle. Stocker les valeurs dans un endroit sûr.
  5. Dans le service de chambre forte OCI, 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 la chambre forte lorsque vous configurez un outil d'appel de point d'extrémité d'API avec authentification IDCS.
    Note

    Les appels inter-région de la location du service d'agent ne sont pas pris en charge. Par exemple, si l'outil d'appel de point d'extrémité d'API configuré avec l'authentification IDCS se trouve dans la région A, vous ne devez pas sélectionner une chambre forte avec la région principale B.

    Si vous avez besoin d'aide pour créer une clé secrète, voir Création d'une clé secrète dans la documentation du service de chambre forte.

    Voir aussi Politiques pour la clé secrète de la chambre forte.

authentification du principal de ressource OCI

Uniquement pour appeler les API OCI telles que le stockage d'objets et le réseau.

Un principal de ressource permet aux services de s'authentifier en toute sécurité avec les ressources du service OCI et OCI sans nécessiter de données d'identification explicites. Les politiques de l'OCI IAM sont utilisées pour authentifier l'accès. 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 politiques IAM que vous écrivez dépendent des API de service OCI que vous appelez et de l'utilisation ou non d'un groupe dynamique. Voir Politiques pour les services OCI.

Ressources de réseau

Lorsque vous créez un outil d'appel de point d'extrémité d'API dans les agents d'IA générative, vous devez sélectionner un réseau en nuage 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 de point d'extrémité d'API transitent par votre sous-réseau. Cela inclut les appels REST aux fournisseurs tiers, les services internes hébergés dans votre réseau VCN et les API publiques OCI.

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

VCN et sous-réseau

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

  • Vous pouvez avoir 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 nécessite 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 le trafic sortant.

Passerelle d'API pour 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 ces deux règles sortantes 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 points d'extrémité privés, veillez à remplacer l'URL de base par l'URL du service de passerelle d'API dans le schéma OpenAPI. La passerelle d'API doit pointer vers l'instance s'exécutant dans un sous-réseau privé.

Configuration du réseau privé
VCN :

  • Créez un VCN dans la région et le compartiment voulus.

  • Spécifiez 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.

  • Spécifiez 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 de calcul 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, Stockage d'objets, API externes, si nécessaire).

  • Ouvrez le port TCP 443 pour HTTPS.

Règles entrantes :

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

  • Restreindre aux ports nécessaires (généralement TCP 443).

Règle UDP entrante :

  • Ajoutez une règle de trafic entrant 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 permettre la redirection et la résolution DNS.

Configuration du réseau public

Configurez des restrictions de trafic entrant et sortant similaires, mais exposées à Internet. utilisation de listes de contrôle d'accès strictes;

Résolution de DNS

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

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

  • Configurer le transfert/règles DNS pour diriger le trafic vers les points d'extrémité de vos applications 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 sur le réseau

Si vous avez besoin d'aide, consultez la documentation suivante :

Politiques GIA

Assurez-vous d'accorder aux utilisateurs l'accès à toutes les ressources des agents d'IA générative, comme décrit sous Ajout de politiques avant de pouvoir utiliser le service.

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

Politiques pour le service de réseau

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

Vous pouvez utiliser les politiques suivantes pour activer l'accès au service de réseau dans tous les compartiments de la location ou 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>
Politiques pour les services OCI

Lorsque vous créez un outil d'appel de point d'extrémité d'API et que vous configurez l'outil pour utiliser l'authentification du principal de ressource OCI, vous devez ajouter des politiques pour accorder les autorisations appropriées pour accéder aux opérations d'API du service OCI que l'agent doit appeler.

Référence : Informations de référence détaillées sur les politiques de service dans le service IAM avec domaines d'identité

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

Utiliser un groupe dynamique

  1. Créer un groupe dynamique et ajouter la règle de correspondance suivante.

    ALL {resource.type='genaiagent'}

    Si vous avez besoin d'aide, voir Création d'un groupe dynamique.

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

    • Les politiques 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 politiques suivantes avec un domaine d'identité pas par défaut, en fournissant 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 utiliser de groupe dynamique

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

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

Politiques pour la clé secrète de chambre forte

La méthode d'authentification que vous utilisez peut nécessiter que vous fournissiez des données d'identification stockées dans une clé secrète du service de chambre forte OCI.

La politique IAM permettant d'accéder aux clés secrètes de chambre forte dépend de l'utilisation ou non d'un groupe dynamique.

Utiliser un groupe dynamique

  1. Créer un groupe dynamique et ajouter la règle de correspondance suivante.

    ALL {resource.type='genaiagent'}

    Si vous avez besoin d'aide, voir Création d'un groupe dynamique.

  2. Les politiques 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 politiques suivantes avec un domaine d'identité pas par défaut, en fournissant 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 utiliser de groupe dynamique

La politique suivante peut être utilisée.

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