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, ad esempio l'ID sessione, nelle 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 ulteriori informazioni, 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 l'account di servizio CX Agent Studio ha le autorizzazioni per richiamare le funzioni Cloud Run, lo strumento può potenzialmente chiamare qualsiasi funzione accessibile da quell'account di servizio, anche se l'utente finale non ha accesso diretto.

Per mitigare i potenziali rischi associati a questo comportamento:

  1. Utilizza progetti dedicati: ti consigliamo vivamente di eseguire il deployment delle applicazioni agent 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 CX Agent Studio.
  2. Implementa i Controlli di servizio VPC: utilizza i Controlli di servizio VPC per definire un perimetro di servizio attorno ai servizi sensibili. In questo modo puoi controllare l'accesso a servizi come le funzioni Cloud Run e impedire chiamate indesiderate dal account di servizio CX Agent Studio.
  3. Segui il principio del privilegio minimo: assicurati che al account di servizio 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 service agent

CX Agent Studio può generare un token ID utilizzando il service agent 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 le funzioni Cloud Run e i servizi Cloud Run si trovano nello stesso progetto dell'agente, non hai bisogno di autorizzazioni IAM aggiuntive per chiamarli. Se si trovano in progetti diversi, puoi utilizzare un token ID per accedere alle funzioni Cloud Run e ai servizi Cloud Run dopo aver concesso i ruoli roles/cloudfunctions.invoker e roles/run.invoker all'indirizzo del service agent.

Autenticazione del service agent

I service account possono essere utilizzati per autenticare le richieste degli strumenti a qualsiasi API di Google che le supporti. Fornisci l'indirizzo email del tuo account di servizio.

Se non l'hai ancora fatto, crea un service account.

Poiché i service agent 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 utilizzare i service agent deve disporre delle seguenti autorizzazioni:

  • roles/iam.serviceAccountUser

Affinché Dialogflow CX generi i token, il service agent 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 la passi 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. Di seguito sono riportati i passaggi necessari per autenticare lo strumento utilizzando i secret:

  1. Crea il secret se non ne hai già uno.
  2. Concedi a Customer Engagement Suite Service Agent il ruolo Funzione di accesso ai secret di Secret Manager (roles/secretmanager.secretAccessor) sul nuovo secret.
  3. Copia le credenziali negli appunti.
  4. Aggiungi una nuova versione del secret al secret. Incolla le credenziali come valore del secret.
    • Ometti eventuali caratteri 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.