Strumenti OpenAPI

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:

  1. 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.
  2. 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.
  3. 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:

  1. Se non ne hai già uno, crea il tuo secret.
  2. Concedi a Customer Engagement Suite Service Agent il ruolo Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) sul nuovo secret.
  3. Copia la credenziale negli appunti.
  4. Aggiungi una nuova versione del secret al tuo secret. Incolla la credenziale come valore del secret.
    • Ometti qualsiasi carattere di nuova riga alla fine.
  5. 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.