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 delle variabili di contesto della sessione

Puoi inserire variabili dal contesto della sessione, come 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.

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 di 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 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 agent in un progetto dedicato, separato da altre risorse critiche o funzioni sensibili. Questo isolamento limita l'ambito delle autorizzazioni disponibili per l'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 intorno ai tuoi servizi sensibili. In questo modo puoi controllare l'accesso a servizi come Cloud Run Functions e impedire chiamate indesiderate dalaccount di servizioo CX Agent Studio.
  3. Segui il principio del privilegio minimo: assicurati che all'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 l'agente di servizio di Customer Engagement Suite. 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 ulteriori autorizzazioni IAM 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 del service agent.

Autenticazione del service account

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

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

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'email del account di servizio verrà utilizzata 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 account deve disporre delle seguenti autorizzazioni:

  • roles/iam.serviceAccountUser

Affinché Dialogflow CX generi token, l'agente di servizio di Customer Engagement Suite deve disporre delle seguenti autorizzazioni:

  • roles/iam.serviceAccountTokenCreator

L'account di servizio deve disporre anche 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 della 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 trasmetta 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. Crea il tuo segreto se non ne hai già uno.
  2. Concedi al service agent Customer Engagement Suite il ruolo Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) sul nuovo secret.
  3. Copia le credenziali 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.