Ferramentas do OpenAPI

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

Limitações:

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

Esquema de exemplo:

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 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 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 possíveis 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 de permissões disponíveis para a conta de serviço do CX Agent Studio.
  2. Implemente os VPC Service Controls: Use os VPC Service Controls para definir um perímetro de serviço em torno dos serviços sensíveis. Isso permite controlar o acesso a serviços como as funções do Cloud Run e evitar chamadas indesejadas da conta de serviço do CX Agent Studio.
  3. Siga o princípio do privilégio mínimo:garanta que a conta de serviço do CX Agent Studio receba apenas os papéis e 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 aceitas 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 no cabeçalho HTTP de autorização quando o CX Agent Studio chama uma API externa.

Se as funções e os serviços do Cloud Run estiverem no mesmo projeto que o agente, você não precisará de permissões extras 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 em qualquer API do Google que ofereça suporte a elas. Forneça o endereço de e-mail da sua conta de serviço.

Crie uma conta de serviço se ainda não tiver feito isso, create a service account.

Como as contas de serviço são principais, elas podem acessar recursos no seu projeto concedendo 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, será necessário configurar o OAuth para o serviço.

Chave de API

É possível configurar a autenticação de chave de API fornecendo 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 Secret Manager versão do secret.

Autenticação do Secret Manager

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

  1. Crie seu secret se ainda não tiver um.
  2. Conceda ao agente de serviço do Pacote de engajamento do cliente o papel 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 seu 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.