Un agente può connettersi a un'API esterna utilizzando uno strumento OpenAPI fornendo lo schema OpenAPI. L'agente chiamerà l'API per tuo conto.
Limitazioni:
- Ogni strumento OpenAPI può avere una sola operazione o funzione.
Schema di esempio:
openapi: 3.0.0
info:
title: Simple Pets API
version: 1.0.0
servers:
- url: 'https://api.pet-service-example.com/v1'
paths:
/pets/{petId}:
get:
summary: Return a pet by ID.
operationId: getPet
parameters:
- in: path
name: petId
required: true
description: Pet id
schema:
type: integer
responses:
200:
description: OK
/pets:
get:
summary: List all pets
operationId: listPets
parameters:
- name: petName
in: query
required: false
description: Pet name
schema:
type: string
- name: label
in: query
description: Pet label
style: form
explode: true
required: false
schema:
type: array
items:
type: string
- name: X-OWNER
in: header
description: Optional pet owner provided in the HTTP header
required: false
schema:
type: string
- name: X-SESSION
in: header
description: session id
required: true
schema:
type: string
x-ces-session-context: $context.session_id
responses:
'200':
description: An array of pets
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Pet'
post:
summary: Create a new pet
operationId: createPet
requestBody:
description: Pet to add to the store
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
responses:
'201':
description: Pet created
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
components:
schemas:
Pet:
type: object
required:
- id
- name
properties:
id:
type: integer
format: int64
name:
type: string
owner:
type: string
label:
type: array
items:
type: string
Inserimento di variabili di contesto della sessione
Puoi inserire variabili dal contesto della sessione, come l'ID sessione, nelle tue richieste OpenAPI.
Utilizza il campo di estensione x-ces-session-context all'interno della definizione del parametro.
Il valore deve essere il percorso della variabile all'interno dell'oggetto context.
Per saperne di più, consulta Variabili di contesto della sessione.
Ad esempio:
parameters:
- name: X-SESSION
in: header
description: session id
required: true
schema:
type: string
# This extension injects the session ID
x-ces-session-context: $context.session_id
Considerazioni sulla sicurezza
Quando configuri gli strumenti OpenAPI, è importante capire come vengono gestite le autorizzazioni:
- Identità di esecuzione dello strumento: le azioni eseguite dallo strumento OpenAPI vengono eseguite utilizzando le autorizzazioni concesse al account di servizio CX Agent Studio, non le autorizzazioni dirette dell'utente finale che interagisce con l'agente.
- Rischio di accesso transitivo: ciò significa che se il account di servizio di CX Agent Studio dispone delle autorizzazioni per richiamare Cloud Run Functions, lo strumento può potenzialmente chiamare qualsiasi funzione accessibile da quel account di servizio, anche se l'utente finale non dispone dell'accesso diretto.
Per mitigare i potenziali rischi associati a questo comportamento:
- Utilizza progetti dedicati: ti consigliamo vivamente di eseguire il deployment delle applicazioni degli agenti in un progetto dedicato, separato da altre risorse critiche o funzioni sensibili. Questo isolamento limita l'ambito delle autorizzazioni disponibili per il account di servizio di CX Agent Studio.
- Implementa i Controlli di servizio VPC: utilizza i Controlli di servizio VPC per definire un perimetro di servizio intorno ai tuoi servizi sensibili. In questo modo puoi controllare l'accesso a servizi come Cloud Run Functions e impedire chiamate indesiderate dal account di servizio CX Agent Studio.
- Segui il principio del privilegio minimo: assicurati che al account di servizio di CX Agent Studio vengano concessi solo i ruoli e le autorizzazioni di Identity and Access Management minimi necessari per la funzionalità prevista.
Autenticazione API
Quando chiami un'API esterna, sono supportate le seguenti opzioni di autenticazione:
Token ID dell'agente di servizio
CX Agent Studio può generare un token ID utilizzando l'agente di servizio di Customer Engagement Suite (nel formato: service-{PROJECT_NUMBER}@gcp-sa-ces.iam.gserviceaccount.com). Il token viene aggiunto nell'intestazione HTTP di autorizzazione quando CX Agent Studio chiama un'API esterna.
Se Cloud Run Functions e i servizi Cloud Run si trovano nello stesso progetto dell'agente, non sono necessarie autorizzazioni IAM aggiuntive per chiamarli. Se si trovano in progetti diversi, è possibile utilizzare un token ID per accedere a Cloud Run Functions e ai servizi Cloud Run dopo aver concesso i ruoli roles/cloudfunctions.invoker e roles/run.invoker all'indirizzo dell'agente di servizio.
Autenticazione del service account
I service account possono essere utilizzati per autenticare le richieste degli strumenti a qualsiasi API di Google che li supporta. Fornisci l'indirizzo email del tuo account di servizio.
Se non l'hai ancora fatto, crea un service account.
Poiché i service account sono entità, possono accedere alle risorse del tuo progetto concedendo loro un ruolo, proprio come faresti per qualsiasi altra entità.
L'indirizzo email del account di servizio verrà utilizzato per generare un token di accesso che verrà inviato nell'intestazione Authorization della richiesta dello strumento.
L'utente che configura lo strumento per l'utilizzo dei service account deve disporre delle seguenti autorizzazioni:
roles/iam.serviceAccountUser
Affinché Dialogflow CX possa generare token, l'agente di servizio Customer Engagement Suite deve disporre delle seguenti autorizzazioni:
roles/iam.serviceAccountTokenCreator
Il account di servizio deve inoltre disporre delle autorizzazioni per accedere al servizio che ospita lo strumento.
OAuth
Fornisci le informazioni OAuth per il servizio che stai utilizzando.
Se utilizzi OAuth per un servizio Google, devi configurare OAuth per il servizio.
Chiave API
Puoi configurare l'autenticazione con chiave API fornendo il nome della chiave, la posizione della richiesta (intestazione o stringa di query) e la chiave API in modo che CX Agent Studio passi la chiave API nella richiesta. Fornisci la chiave API utilizzando la versione del secret di Secret Manager.
Autenticazione di Secret Manager
Puoi archiviare le credenziali come secret utilizzando Secret Manager. Ecco i passaggi necessari per autenticare lo strumento utilizzando i secret:
- Se non ne hai già uno, crea il tuo secret.
- Concedi a Customer Engagement Suite Service Agent il ruolo Secret Manager Secret Accessor (
roles/secretmanager.secretAccessor) sul nuovo secret. - Copia la credenziale negli appunti.
- Aggiungi una nuova versione del secret al tuo secret. Incolla la credenziale come valore del secret.
- Ometti qualsiasi carattere di nuova riga alla fine.
- Copia il nome della versione del secret che hai appena aggiunto. Il formato del nome è
projects/{project_id}/secrets/{secret_id}/versions/{version_id}. Utilizza questa versione del secret per la configurazione dello strumento.
Token di connessione
Puoi configurare l'autenticazione con token di connessione per passare un token di connessione archiviato in una variabile di contesto della sessione nell'intestazione Authorization della richiesta dello strumento OpenAPI. Questa opzione è utile quando l'agente deve passare un token raccolto dall'utente finale a un'altra API.
Specifica la variabile di contesto della sessione nel seguente formato:
$context.variables.VARIABLE_NAME, dove
VARIABLE_NAME è il nome della variabile che
memorizza il token di connessione.