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 do 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 do 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.

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 do 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 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 serviços sensíveis. 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 do privilégio mínimo:garanta que a conta de serviço do CX Agent Studio tenha 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 da Customer Engagement Suite. O token é adicionado ao 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 do 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 funções e 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. Informe o endereço de e-mail da sua conta de serviço.

Se você ainda não tiver feito isso, crie uma conta de serviço.

Como as contas de serviço são principais, elas podem acessar recursos no seu projeto ao conceder a ela 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 da Customer Engagement Suite 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 na solicitação. Forneça sua chave de API usando a versão secreta 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 chaves secretas:

  1. Crie seu secret se você ainda não tiver um.
  2. Conceda ao agente de serviço do Customer Engagement Suite o papel de Acessador de secrets do Secret Manager (roles/secretmanager.secretAccessor) no novo secret.
  3. Copie a 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 secreta para a configuração da ferramenta.