Ferramentas do OpenAPI

Um agente pode se conectar a uma API externa usando uma ferramenta OpenAPI ao fornecer o esquema OpenAPI. O agente vai chamar a API em seu nome.

Limitações:

  • Cada ferramenta OpenAPI só pode ter uma operação ou função.

Exemplo de esquema:

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

Como injetar variáveis de contexto de sessão

É possível injetar variáveis do contexto da sessão, como o ID da sessão, nas solicitações da OpenAPI. Use o campo de extensão x-ces-session-context na definição do parâmetro. O valor precisa ser o caminho para a variável no objeto context. Para mais informações, consulte Variáveis de contexto de sessão.

Exemplo:

      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

Considerações sobre segurança

Ao configurar ferramentas da OpenAPI, é importante entender como as permissões são processadas:

  • Identidade de execução da ferramenta: as ações realizadas pela ferramenta OpenAPI são executadas usando as permissões concedidas à conta de serviço do CX Agent Studio, não as permissões diretas do usuário final que interage com o agente.
  • Risco de acesso transitivo: isso significa que, se a conta de serviço do CX Agent Studio tiver permissões para invocar funções do Cloud Run, a ferramenta poderá chamar qualquer função acessível por essa conta de serviço, mesmo que o usuário final não tenha acesso direto.

Para reduzir os riscos associados a esse comportamento:

  1. Use projetos dedicados: recomendamos implantar aplicativos de agente em um projeto dedicado, separado de outros recursos críticos ou funções sensíveis. Esse isolamento limita o escopo das permissões disponíveis para a conta de serviço do CX Agent Studio.
  2. Implemente o VPC Service Controls: use o VPC Service Controls para definir um perímetro de serviço em torno dos seus serviços confidenciais. Isso permite controlar o acesso a serviços como o Cloud Run functions e evitar chamadas indesejadas da conta de serviço do CX Agent Studio.
  3. Siga o princípio de privilégio mínimo: garanta que a conta de serviço do CX Agent Studio receba apenas os papéis e as permissões mínimos necessários do Identity and Access Management para a funcionalidade pretendida.

Autenticação da API

As seguintes opções de autenticação são compatíveis ao chamar uma API externa:

Token de ID do agente de serviço

O CX Agent Studio pode gerar um token de ID usando o agente de serviço do Pacote de engajamento do cliente (no formato: service-{PROJECT_NUMBER}@gcp-sa-ces.iam.gserviceaccount.com). O token é adicionado ao cabeçalho HTTP de autorização quando o CX Agent Studio chama uma API externa.

Se o Cloud Run functions e os serviços do Cloud Run estiverem no mesmo projeto que o agente, não será necessário ter outras permissões do IAM para chamá-los. Se eles estiverem em projetos diferentes, um token de ID poderá ser usado para acessar as funções do Cloud Run e os serviços do Cloud Run depois que você conceder os papéis roles/cloudfunctions.invoker e roles/run.invoker ao endereço do agente de serviço.

Autenticação da conta de serviço

As contas de serviço podem ser usadas para autenticar solicitações de ferramentas para qualquer API do Google que seja compatível. Informe o endereço de e-mail da sua conta de serviço.

Crie uma conta de serviço, caso ainda não tenha feito isso.

Como as contas de serviço são principais, elas podem acessar recursos no seu projeto concedendo a elas um papel, assim como você faria para qualquer outro principal. O e-mail da conta de serviço será usado para gerar um token de acesso, que será enviado no cabeçalho Authorization da solicitação da ferramenta.

O usuário que está configurando a ferramenta para usar contas de serviço precisa ter as seguintes permissões:

  • roles/iam.serviceAccountUser

Para que o Dialogflow CX gere tokens, o agente de serviço do Pacote de engajamento do cliente precisa ter as seguintes permissões:

  • roles/iam.serviceAccountTokenCreator

A conta de serviço também precisa ter permissões para acessar o serviço que hospeda a ferramenta.

OAuth

Forneça as informações do OAuth para o serviço que você está usando.

Se você estiver usando o OAuth para um serviço do Google, precisará configurar o OAuth para o serviço.

Chave de API

Para configurar a autenticação de chave de API, informe o nome da chave, o local da solicitação (cabeçalho ou string de consulta) e a chave de API para que o CX Agent Studio transmita a chave de API na solicitação. Forneça sua chave de API usando a versão do secret do Secret Manager.

Autenticação do Secret Manager

É possível armazenar credenciais como secrets usando o Secret Manager. Estas são as etapas necessárias para autenticar sua ferramenta usando secrets:

  1. Crie o secret, caso ainda não tenha um.
  2. Conceda ao Agente de serviço do Pacote de engajamento do cliente o papel de Acessador de secrets do Secret Manager (roles/secretmanager.secretAccessor) no novo secret.
  3. Copie sua credencial para a área de transferência.
  4. Adicione uma nova versão do secret ao secret. Cole sua credencial como o valor do secret.
    • Omita qualquer caractere de nova linha no final.
  5. Copie o nome da versão do secret que você acabou de adicionar. O formato do nome é projects/{project_id}/secrets/{secret_id}/versions/{version_id}. Use essa versão do secret para a configuração da ferramenta.

Token do portador

É possível configurar a autenticação do token do portador para transmitir um token do portador armazenado em uma variável de contexto de sessão no cabeçalho Authorization da solicitação da ferramenta OpenAPI. Essa opção é útil quando o agente precisa transmitir um token coletado do usuário final para outra API.

Especifique a variável de contexto da sessão no seguinte formato: $context.variables.VARIABLE_NAME, em que VARIABLE_NAME é o nome da variável que armazena o token do portador.