Documentazione dell'infrastruttura Oracle Cloud

Linee guida dello strumento di chiamata degli endpoint API per gli agenti AI generativa

Definire uno strumento di chiamata agli endpoint API negli agenti AI generativa per l'interazione e la chiamata di interfacce di programmazione delle applicazioni esterne (API) e API OCI.

Le informazioni fornite in questo argomento presuppongono che tu abbia familiarità con le reti cloud virtuali (VCN), le subnet e le regole di sicurezza OCI, come distribuire le applicazioni sulle istanze di computazione OCI e le nozioni di base dell'utilizzo dell'interfaccia di programmazione dell'applicazione REpresentational State Transfer (API REST).

Ecco una panoramica su come iniziare:

  1. Creare uno schema OpenAPI che definisca i formati di richiesta e risposta e le operazioni disponibili. Includere l'intestazione x-requires-approval nello schema, se necessario.
  2. Configurare un metodo di autenticazione. A seconda del tipo di autenticazione utilizzato, creare un segreto vault per le credenziali che è necessario fornire.
  3. Impostare le risorse di rete OCI. È necessaria una rete cloud virtuale (VCN).
  4. Esaminare i criteri IAM e aggiungere quelli necessari. ad esempio Networking e Vault.

Schema API

La struttura e il funzionamento delle operazioni API devono essere definiti in uno schema OpenAPI scritto in JSON o YAML.

Quando si utilizza la console per creare uno strumento di chiamata dell'endpoint API negli agenti AI generativa, è possibile caricare lo schema manualmente copiandolo e incollandolo in una casella di testo oppure selezionare lo schema caricato nello storage degli oggetti.

Le dimensioni massime dei file e le versioni supportate sono:

  • Versioni:
    • OpenAPI: 3.0 e versioni successive
    • JSON: schema JSON standard come definito in RFC 8259
    • YAML: versione 1.2 e successive
  • Dimensione massima file:
    • Inline pasting: 1.000.000 caratteri
    • File nello storage degli oggetti: 20 MB
Esempio di schema API in 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."
          }
        }
      }
    }
  }
}
Esempio di schema API in 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."

Approvazione Human-in-the-Loop

Per le operazioni API che potrebbero modificare uno stato, si consiglia di includere l'intestazione x-requires-approval nello schema per indicare che un'azione strumento richiede l'approvazione HITL (Human-in-the-loop). Il coinvolgimento degli esseri umani nelle operazioni critiche è generalmente consigliato per i seguenti tipi di operazioni perché potrebbero causare modifiche non giustificate:

  • POST
  • PUT
  • PATCH
  • DELETE

Esempio di inclusione di x-requires-approval in uno schema 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'inclusione dell'intestazione x-requires-approval segnala agli agenti AI generativa che è necessario richiedere una conferma a un operatore prima di eseguire l'endpoint API nella chiamata dello strumento agente.

Quando l'intestazione di approvazione è inclusa nello schema, l'intestazione:

  • Attiva l'azione richiesta HumanApprovalRequiredAction nel passo della traiettoria
  • Previene gli effetti collaterali indesiderati senza supervisione umana
  • Consente l'utilizzo sicuro di strumenti che eseguono operazioni di scrittura, aggiornamento o eliminazione.

Autenticazione

In Agenti AI generativa, è possibile configurare uno strumento di chiamata endpoint API per utilizzare l'autenticazione o non utilizzare l'autenticazione quando si effettua una richiesta di esecuzione di un'operazione API.

Per informazioni sui meccanismi di autenticazione supportati e sui task dei prerequisiti da eseguire per un tipo di autenticazione, vedere le sezioni riportate di seguito.

Autenticazione chiave API

Per gli endpoint API pubblici e privati che richiedono una chiave API.

Una chiave API è un identificativo univoco ottenuto dalla piattaforma del provider API. Quando un client, ad esempio un'applicazione o un servizio, effettua una richiesta all'API, la chiave API viene utilizzata per autenticare il client.

Negli agenti AI generativa, l'autenticazione della chiave API è supportata dai tipi riportati di seguito.

  • Intestazione: passare la chiave API nell'intestazione di una richiesta HTTP.

    I parametri dell'intestazione API sono coppie chiave-valore incluse in una richiesta o risposta HTTP per fornire metadati aggiuntivi sulla richiesta o sulla risposta.

  • Parametro query: passare la chiave API direttamente nell'URL come parametro di query.

    I parametri di query sono un set definito di parametri (coppie chiave-valore) collegati alla fine di un URL utilizzato per fornire informazioni aggiuntive a un server Web durante l'esecuzione delle richieste.

Creare un segreto nel vault OCI per memorizzare la chiave API. Se è necessaria assistenza per la creazione di un segreto, vedere Creazione di un segreto nella documentazione del servizio Vault.

Quando configuri uno strumento di chiamata dell'endpoint API con l'autenticazione della chiave API, specifichi la posizione della chiave (intestazione o parametro di query), il nome della chiave e il segreto del vault con la chiave API.

Vedere anche Criteri per segreto vault.

Autenticazione Basic

Per richiamare gli endpoint API pubblici e privati utilizzando un nome utente e una password.

L'autenticazione di base utilizza le credenziali del nome utente e della password nel seguente formato richiesto:

<your-username>:<your-password>

Creare un segreto nel vault OCI per memorizzare le credenziali nel formato richiesto. Se è necessaria assistenza per la creazione di un segreto, vedere Creazione di un segreto nella documentazione del servizio Vault.

Quando si configura uno strumento di chiamata endpoint API con autenticazione di base, si fornisce il segreto vault.

Vedere anche Criteri per segreto vault.

Autenticazione Bearer

Per richiamare gli endpoint API privati utilizzando un token bearer.

Un token bearer è un token di accesso utilizzato nell'autenticazione OAuth 2.0 per autorizzare o concedere l'accesso alle risorse protette. L'autenticazione Bearer è un metodo di autenticazione in cui il client invia un token bearer come parte della richiesta nell'intestazione di autorizzazione, che viene convalidata per autenticare la richiesta. Si consiglia di utilizzare token di lunga durata come le chiavi API.

Creare un segreto nel vault OCI per memorizzare il token. Se è necessaria assistenza per la creazione di un segreto, vedere Creazione di un segreto nella documentazione del servizio Vault.

Quando configuri uno strumento di chiamata dell'endpoint API con autenticazione bearer, fornisci il segreto del vault.

Vedere anche Criteri per segreto vault.

Autenticazione IDCS

Per richiamare gli endpoint API privati utilizzando le credenziali client dell'applicazione riservata di Oracle Identity Cloud Service (IDCS).

Un'applicazione riservata è progettata per autenticare e autorizzare in modo sicuro le applicazioni client utilizzando OAuth 2.0. Le credenziali client sono l'ID client e il segreto client di un'applicazione riservata registrata per un'applicazione client.

Utilizzare OCI IAM con i domini di Identity per creare un'applicazione riservata. Tenere presente che è necessario disporre del ruolo Amministratore dominio di Identity o Amministratore applicazione per creare applicazioni riservate in un dominio di Identity.

Per creare un'applicazione riservata, procedere come segue.

  1. Aprire il menu di navigazione e selezionare Identità e sicurezza. In Identità selezionare Domini.
  2. Dalla lista di domini in un compartimento, selezionare il dominio in cui si desidera creare l'applicazione riservata.
  3. Creare e attivare un'applicazione riservata.

    Per la configurazione OAuth, selezionare Configurazione client e utilizzare le credenziali client.

    Se hai bisogno di assistenza, consulta la sezione relativa alla creazione di un'applicazione riservata nella documentazione di OCI IAM with Identity Domains.

  4. Copiare i valori dell'ID client e del segreto client generati nell'applicazione riservata. Conservare i valori in un luogo sicuro.
  5. In OCI Vault creare un segreto per memorizzare il segreto client dell'applicazione riservata. È necessario fornire il segreto vault quando si configura uno strumento di chiamata dell'endpoint API con l'autenticazione IDCS.
    Nota

    Le chiamate tra più aree dalla tenancy del servizio agente non sono supportate. Ad esempio, se lo strumento di chiamata dell'endpoint API configurato con l'autenticazione IDCS si trova nell'area A, non è necessario selezionare un vault con l'area B master.

    Se è necessaria assistenza per la creazione di un segreto, vedere Creazione di un segreto nella documentazione del servizio Vault.

    Vedere anche Criteri per segreto vault.

Autenticazione principal risorsa OCI

Solo per chiamare le API OCI come lo storage degli oggetti e la rete.

Un principal risorsa consente ai servizi di eseguire l'autenticazione in modo sicuro con le risorse dei servizi OCI e OCI senza richiedere credenziali esplicite. I criteri IAM OCI vengono utilizzati per autenticare l'accesso. Ad esempio:

// 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'}

I criteri IAM scritti dipendono dalle API del servizio OCI che si sta chiamando e dal fatto che si stia utilizzando un gruppo dinamico. Vedere Policy per i servizi OCI.

Risorse di rete

Quando crei uno strumento di chiamata agli endpoint API negli agenti AI generativa, devi selezionare una rete cloud virtuale (VCN) e una subnet.

Indipendentemente dal fatto che l'URL di destinazione sia privato o pubblico, tutte le richieste effettuate dagli strumenti di chiamata dell'endpoint API vengono instradate attraverso la subnet. Sono incluse le chiamate REST a provider di terze parti, i servizi interni ospitati nella tua VCN e le API pubbliche OCI.

Impostare le risorse di rete necessarie in OCI.

VCN e subnet

  • È necessaria una rete cloud virtuale (VCN).

  • Puoi avere una subnet privata o pubblica. Si consiglia una subnet privata.

  • Una subnet privata richiede un gateway NAT.

  • Una subnet pubblica richiede un gateway Internet. A seconda dell'impostazione dell'ambiente, una subnet pubblica potrebbe richiedere un gateway Internet e un gateway NAT.

    Per chiamare le API pubbliche senza autenticazione, assicurarsi che la subnet pubblica sia impostata per un gateway NAT con tutto il traffico delle porte abilitato per l'uscita.

Gateway API per DNS privato

È possibile creare un gateway API per il traffico verso le applicazioni su istanze private.

Selezionare il tipo Privato quando si crea il gateway API per un DNS privato.

Nella subnet privata, assicurarsi che siano disponibili queste due regole di uscita:

  • La porta 443 viene utilizzata dal gateway API per la comunicazione.
  • Porta in cui è ospitata l'applicazione privata. Il gateway API invia una richiesta a questa porta (ad esempio, 9090).

Quando si utilizza l'autenticazione IDCS con endpoint privati, assicurarsi di sostituire l'URL di base con l'URL del servizio gateway API nello schema OpenAPI. Il gateway API deve puntare all'istanza in esecuzione in una subnet privata.

Impostazione della rete privata
VCN:

  • Creare una VCN nell'area e nel compartimento desiderati.

  • Specificare il blocco CIDR per la VCN (ad esempio, 10.0.0.0/16).

  • Puoi scegliere di abilitare la risoluzione DNS per la VCN.

Subnet privata:

  • Creare una subnet privata nella VCN creata, selezionando lo stesso compartimento della VCN.

  • Specificare il blocco CIDR per la subnet (ad esempio, 10.0.1.0/24).

  • È possibile scegliere di abilitare la risoluzione DNS per la subnet.

Istanza di computazione privata:

  • Nello stesso compartimento della VCN e della subnet creare un'istanza di computazione privata, selezionando la VCN e la subnet privata create dall'utente.

  • Se si desidera accedere all'istanza tramite SSH, fornire la chiave pubblica SSH.

Regole in uscita:

  • Consenti connessioni in uscita ai servizi richiesti (ad esempio, storage degli oggetti, API esterne, se necessario).

  • Aprire la porta TCP 443 per HTTPS.

Regole in entrata:

  • Consenti traffico in entrata solo dagli intervalli IP della piattaforma OCI.

  • Limitare l'accesso alle porte necessarie (in genere TCP 443).

Regola UDP in entrata:

  • Aggiungere una regola di entrata per la porta UDP 53.

    Aggiungere la regola UDP alla lista di sicurezza predefinita del servizio agente e alle subnet VCN del cliente per consentire il reindirizzamento e la risoluzione del DNS.

Impostazione rete pubblica

Impostare restrizioni di entrata ed uscita simili, ma esposte a Internet. Utilizzare liste di controllo dell' accesso (ACL, Access Control list) rigorose.

Risoluzione DNS

Per facilitare la risoluzione DNS per le applicazioni private, effettuare le operazioni riportate di seguito.

  • Consenti la porta UDP 53 nelle liste di firewall/sicurezza per il traffico DNS.

  • Configura l'inoltro/regole DNS per indirizzare il traffico agli endpoint dell'applicazione privata.

  • Assicurarsi che la porta UDP in entrata 53 sia aperta sia nel servizio agente che nelle liste di sicurezza della subnet VCN del cliente.

Assicurati che la piattaforma OCI sia in grado di risolvere i nomi di dominio associati alle tue applicazioni private.

Documentazione di riferimento per la rete

Per assistenza, consultare la documentazione del servizio riportata di seguito.

Criteri IAM

Assicurarsi di concedere agli utenti l'accesso a tutte le risorse degli agenti di intelligenza artificiale generativa come descritto in Aggiunta di criteri prima di poter utilizzare il servizio.

Rivedere anche le sezioni seguenti e scrivere i criteri necessari.

Criteri per la rete

Il criterio per il tipo di risorsa aggregato virtual-network-family è obbligatorio.

È possibile utilizzare i criteri riportati di seguito per abilitare l'accesso alla rete in tutti i compartimenti della tenancy o limitare l'accesso a un compartimento specifico. 

// 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>
Criteri per i servizi OCI

Quando crei uno strumento di chiamata dell'endpoint API e configuri lo strumento per utilizzare l'autenticazione del principal risorsa OCI, devi aggiungere criteri per concedere le autorizzazioni appropriate per accedere alle operazioni API del servizio OCI che desideri che l'agente chiami.

Riferimento: Riferimento ai criteri del servizio dettagliato in IAM con i domini di Identity

I criteri IAM OCI di cui hai bisogno dipendono dalle API del servizio OCI che stai chiamando e dal fatto che stai utilizzando un gruppo dinamico.

Usa gruppo dinamico

  1. Creare un gruppo dinamico e aggiungere la regola della corrispondenza seguente.

    ALL {resource.type='genaiagent'}

    Per assistenza, vedere Creazione di un gruppo dinamico.

  2. Aggiungere un criterio per fornire al gruppo dinamico il livello di accesso appropriato a un tipo di risorsa. Ad esempio, per chiamare le API del servizio di storage degli oggetti, è possibile utilizzare manage object-family o read objects.

    • Con il dominio di Identity predefinito è possibile utilizzare i criteri riportati di seguito.

      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

    • Utilizzare i criteri seguenti con un dominio di Identity non predefinito, fornendo il nome di dominio Oracle Identity Cloud Service (IDCS) e il nome del gruppo dinamico: 

      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

Senza utilizzare il gruppo dinamico

Aggiungere un criterio per fornire il livello di accesso appropriato a un tipo di risorsa. Ad esempio, per chiamare le API del servizio di storage degli oggetti, è possibile utilizzare manage object-family o read objects.

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

Criteri per il segreto vault

Il metodo di autenticazione utilizzato potrebbe richiedere di fornire una credenziale memorizzata in un segreto vault OCI.

Il criterio IAM per accedere ai segreti del vault dipende dal fatto che si stia utilizzando un gruppo dinamico.

Usa gruppo dinamico

  1. Creare un gruppo dinamico e aggiungere la regola della corrispondenza seguente.

    ALL {resource.type='genaiagent'}

    Per assistenza, vedere Creazione di un gruppo dinamico.

  2. Con il dominio di Identity predefinito è possibile utilizzare i criteri riportati di seguito.

    • 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

    • Utilizzare i criteri seguenti con un dominio di Identity non predefinito, fornendo il nome di dominio Oracle Identity Cloud Service (IDCS) e il nome del gruppo dinamico: 

      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

Senza utilizzare il gruppo dinamico

È possibile utilizzare il seguente criterio.

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