Ferramentas do OpenAPI e do Integration Connectors

Você pode usar os recursos do Agent Assist com APIs e fontes de dados externas.O Google Cloud fornece ferramentas do OpenAPI e do Integration Connectors para facilitar as integrações do Agent Assist.

Ferramentas OpenAPI

As ferramentas OpenAPI permitem a conexão entre os recursos do Agent Assist e APIs externas. Essa conexão permite que os recursos do Agent Assist leiam e gravem informações de várias fontes. Para criar uma ferramenta OpenAPI, forneça um esquema OpenAPI que descreva as APIs externas a que você quer se conectar.

Ferramenta Integration Connectors

Use os Integration Connectors para se conectar Google Cloud a várias fontes de dados. Com as ferramentas de conector, os recursos do Agent Assist podem usar os Integration Connectors para ler e gravar essas fontes de dados.

Antes de começar

Para configurar o ambiente e criar ferramentas do OpenAPI e do Integration Connectors, insira o ID do projeto e a região e execute o seguinte código.

CLOUDSDK_CORE_PROJECT=YOUR_PROJECT_ID
REGION=YOUR_REGION
API_VERSION=v2beta1
API_ENDPOINT=https://${REGION}-dialogflow.googleapis.com/${API_VERSION}

function gcurl () {
        curl -H "Authorization: Bearer "$(gcloud auth print-access-token) -H "X-Goog-User-Project: ${CLOUDSDK_CORE_PROJECT}" -H "Content-Type: application/json; charset=utf-8" "$@"
}

Criar uma ferramenta OpenAPI

Para usar uma ferramenta da OpenAPI, primeiro solicite a criação dela e salve o nome do recurso.

Etapa 1: solicitar a criação da ferramenta

Siga estas etapas para pedir a criação de uma ferramenta do OpenAPI.

  1. Personalize o código da seguinte forma:
    1. Em um único projeto, use um valor de tool_key exclusivo entre todas as suas ferramentas.
    2. Insira seu próprio esquema da OpenAPI no campo open_api_spec.text_schema.

  2. Execute o seguinte código personalizado. 

    $ cat > create-tool-request.json << EOF
{
  "tool_key": "UNIQUE_KEY",
  "description": "TOOL_DESCRIPTION",
  "display_name": "TOOL_DISPLAY_NAME",
  "open_api_spec": {
    "text_schema": "Your-Schema"
  }
}
EOF
    


    $ gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/tools -d @create-tool-request.json | tee create-tool-response.json

Se a solicitação for bem-sucedida, a API vai retornar a ferramenta recém-criada, que contém o nome do recurso, conforme mostrado no exemplo a seguir.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/tools/Tool-ID",
  "toolKey": "UNIQUE_KEY",
  "description": "TOOL_DESCRIPTION",
  "createTime": "2025-06-02T18:11:38.999174724Z",
  "updateTime": "2025-06-02T18:11:38.999174724Z",
  "displayName": "TOOL_DISPLAY_NAME",
  "openApiSpec": {
    "textSchema": "Your-Schema"
  }
}

Etapa 2: salvar o nome do recurso da ferramenta

Salve o nome do recurso da ferramenta em uma variável de ambiente para uso posterior. Confira a seguir um exemplo de modelo para a variável de ambiente de recurso da ferramenta.

TOOL_RESOURCE=$(cat create-tool-response.json | jq .name | tr -d '"')

Coach de IA com uma ferramenta OpenAPI

Você pode usar uma ferramenta da OpenAPI com o recurso Coach de IA para acessar mais informações de fora do Google Cloud. Essas informações externas podem ser usadas para gerar sugestões que ajudam os atendentes da central de atendimento.

Etapa 1: criar um gerador

O exemplo a seguir cria um gerador com a variável de ambiente de recurso da ferramenta.

$ cat > create-generator-request.json << _EOF_
{"agent_coaching_context":{"instructions":[{"agent_action":"help customer by using the tool to find information from library of congress","condition":"The customer asks about library of congress","description":"agent coaching test","display_name":"Search for information"}],"overarching_guidance":"Help customer with questions"},"description":"prober-generate-suggestions-with-agent-coaching-generator","inference_parameter":{"max_output_tokens":256,"temperature":0},"tools":["${TOOL_RESOURCE}"],"trigger_event":"CUSTOMER_MESSAGE"}
_EOF_

$ gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/generators -d @create-generator-request.json | tee create-generator-response.json

_EOF_

$ gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/generators -d @create-generator-request.json | tee create-generator-response.json

Você vai receber uma resposta semelhante ao exemplo a seguir de um gerador de coach de IA.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/generators/Generator-ID",
  "description": "example-generator",
  "inferenceParameter": {
    "maxOutputTokens": 256,
    "temperature": 0
  },
  "triggerEvent": "CUSTOMER_MESSAGE",
  "createTime": "2025-06-02T18:30:51.021461728Z",
  "updateTime": "2025-06-02T18:30:51.021461728Z",
  "agentCoachingContext": {
    "instructions": [
      {
        "displayName": "Search for information",
        "condition": "The customer asks about library of congress",
        "agentAction": "help customer by using the tool to find information from library of congress"
      }
    ],
    "version": "1.5",
    "overarchingGuidance": "Help customer with questions"
  },
  "tools": [
    "projects/Your-Project-ID/locations/Your-Region/tools/Tool-ID"
  ]
}

Salvar o nome do recurso do gerador

Salve como uma variável de ambiente para uso posterior, como no exemplo a seguir.

GENERATOR_RESOURCE=$(cat create-generator-response.json | jq .name | tr -d '"')

Etapa 2: criar um perfil de conversa

Execute o código a seguir para criar um perfil de conversa.

$ cat > create-conversation-profile-request.json << _EOF_
{"displayName":"prober-generate-suggestions-with-agent-coaching-generator","humanAgentAssistantConfig":{"humanAgentSuggestionConfig":{"generators":["${GENERATOR_RESOURCE}"]}}}
_EOF_

$ gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/conversationProfiles -d @create-conversation-profile-request.json | tee create-conversation-profile-response.json

Você vai receber uma resposta como esta.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/conversationProfiles/Conversation-Profile-ID",
  "displayName": "prober-generate-suggestions-with-agent-coaching-generator",
  "humanAgentAssistantConfig": {
    "humanAgentSuggestionConfig": {
      "generators": [
        "projects/Your-Project-ID/locations/Your-Region/generators/Generator-ID"
      ]
    }
  },
  "languageCode": "en-US",
  "createTime": "2025-06-02T18:40:39.940318Z",
  "updateTime": "2025-06-02T18:40:39.940318Z",
  "projectNumber": "${project_number}"
}

Salvar o nome do recurso do perfil de conversa

Salve esse nome como uma variável de ambiente, como no exemplo a seguir.

CONVERSATION_PROFILE_RESOURCE=$(cat create-conversation-profile-response.json | jq .name | tr -d '"')

Etapa 3: criar uma conversa

Execute o código a seguir para criar uma conversa.

$ cat > create-conversation-request.json << _EOF_
{"conversationProfile":"${CONVERSATION_PROFILE_RESOURCE}"}
_EOF_

$ gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/conversations -d @create-conversation-request.json | tee create-conversation-response.json

Você vai receber uma resposta como esta.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/conversations/Conversation-ID",
  "lifecycleState": "IN_PROGRESS",
  "conversationProfile": "projects/Your-Project-ID/locations/Your-Region/conversationProfiles/Conversation-Profile-ID",
  "startTime": "2025-06-02T18:43:40.818123Z",
  "conversationStage": "HUMAN_ASSIST_STAGE",
  "source": "ONE_PLATFORM_API",
  "initialConversationProfile": {
    "name": "projects/Your-Project-ID/locations/Your-Region/conversationProfiles/Conversation-Profile-ID",
    "displayName": "prober-generate-suggestions-with-agent-coaching-generator",
    "humanAgentAssistantConfig": {
      "humanAgentSuggestionConfig": {
        "generators": [
          "projects/Your-Project-ID/locations/Your-Region/generators/Generator-ID"
        ]
      }
    },
    "languageCode": "en-US"
  },
  "projectNumber": "${project_number}",
  "initialGeneratorContexts": {
    "projects/Your-Project-ID/locations/Your-Region/generators/Generator-ID": {
      "generatorType": "AGENT_COACHING",
      "generatorVersion": "1.5"
    }
  }
}

Salvar o nome do recurso de conversa

Salve esse nome como uma variável de ambiente para uso posterior. Sua variável precisa ter o seguinte formato:

CONVERSATION_RESOURCE=$(cat create-conversation-response.json | jq .name | tr -d '"')

Etapa 4: criar um usuário final

Execute o código a seguir para criar um usuário final.

$ cat > create-end-user-request.json << _EOF_
{"role":"END_USER"}
_EOF_

$ gcurl -X POST ${API_ENDPOINT}/${CONVERSATION_RESOURCE}/participants -d @create-end-user-request.json | tee create-end-user-response.json

Você vai receber uma resposta como esta.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/conversations/Conversation-ID/participants/End-User-Participant-ID",
  "role": "END_USER"
}

Salvar o nome do recurso do usuário final

Salve o nome do recurso do usuário final como uma variável de ambiente, como a seguinte. 

END_USER_RESOURCE=$(cat create-end-user-response.json | jq .name | tr -d '"')

Etapa 5: criar um agente humano

Execute o código a seguir para criar um agente humano.

$ cat > create-human-agent-request.json << _EOF_
{"role":"HUMAN_AGENT"}
_EOF_

$ gcurl -X POST ${API_ENDPOINT}/${CONVERSATION_RESOURCE}/participants -d @create-human-agent-request.json | tee create-human-agent-response.json

Você vai receber uma resposta como esta.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/conversations/Conversation-IDHuman-Agent-Participant-ID",
  "role": "HUMAN_AGENT"
}

Salvar o nome do recurso do agente humano

Salve o nome do recurso do agente humano como uma variável de ambiente, como a seguinte.

HUMAN_AGENT_RESOURCE=$(cat create-human-agent-response.json | jq .name | tr -d '"')

Etapa 6: enviar texto para o coach de IA

Execute o código a seguir para enviar texto ao coach de IA com o método AnalyzeContent.

cat > analyze-content-1-request.json << _EOF_
{"text_input":{"languageCode":"en-US","text":"Can you search library of congress for the latest trends"}}
_EOF_

gcurl -X POST "${API_ENDPOINT}/${END_USER_RESOURCE}:analyzeContent" -d @analyze-content-1-request.json | tee analyze-content-1-response.json

Etapa 7: verificar a chamada de função

Execute o código a seguir para verificar a chamada de ferramenta.

cat analyze-content-1-response.json| jq ".humanAgentSuggestionResults[0].generateSuggestionsResponse.generatorSuggestionAnswers[0].generatorSuggestion.toolCallInfo"

Você vai receber uma resposta como esta.

[
  {
    "toolCall": {
      "tool": "projects/Your-Project-ID/locations/Your-Region/tools/Tool-ID",
      "action": "search",
      "inputParameters": {
        "q": "latest trends",
        "fo": "json",
        "tool_description": "A generic search endpoint that might be available across various LoC APIs. The structure of the results will vary.\n",
        "at": "trending_content"
      },
      "createTime": "2025-06-02T18:56:53.882479179Z"
    },
    "toolCallResult": {
      "tool": "projects/Your-Project-ID/locations/Your-Region/tools/MjM0NTU3NDk2MTM5NTAwNzQ4OQ",
      "action": "search",
      "content": ""}]}",
      "createTime": "2025-06-02T18:56:54.289367086Z"
    }
  }
]

Etapa 8: (opcional) excluir recursos

Para excluir os recursos criados nas etapas anteriores, execute o seguinte código.

Perfil de conversa

gcurl -X DELETE ${API_ENDPOINT}/${CONVERSATION_PROFILE_RESOURCE}

Gerador

gcurl -X DELETE ${API_ENDPOINT}/${GENERATOR_RESOURCE}

Ferramenta OpenAPI

gcurl -X DELETE ${API_ENDPOINT}/${TOOL_RESOURCE}

Criar uma ferramenta do Integration Connectors

É possível configurar os Integration Connectors usando o console do Google Cloud . Siga estas etapas para criar uma ferramenta do Integration Connectors do Agent Assist com base em um conector do BigQuery.

Etapa 1: criar uma ferramenta de conector do BigQuery

Antes de criar uma ferramenta do Integration Connectors, acesse o Google Cloud console e crie um Integration Connectors do BigQuery.

Etapa 2: solicitar a criação da ferramenta Integration Connectors

Execute o código a seguir para solicitar a criação de uma ferramenta. Para o campo connector_spec.name, use o nome do recurso do seu conector do BigQuery.

cat > create-connector-tool-request.json << _EOF_
{
  "tool_key": "order_tool",
  "description": "order bigquery connector tool",
  "display_name": "order bigquery connector tool",
  "connector_spec": {
    "name": "projects/Your-Project-ID/locations/Your-Region/connections/Your-Connector-ID",
    "actions": [
                             {
                               "entityOperation": {
                                 "entityId": "Orders",
                                 "operation": "LIST"
                               }
                             }, {
                               "entityOperation": {
                                 "entityId": "Orders",
                                 "operation": "GET"
                               }
                             }
                           ]
  }
}
_EOF_


gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/tools -d @create-connector-tool-request.json | tee create-connector-tool-response.json

Você vai receber uma resposta semelhante a esta.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/tools/Tool-ID",
  "toolKey": "order_tool",
  "description": "order bigquery connector tool",
  "createTime": "2025-06-03T19:29:55.896178942Z",
  "updateTime": "2025-06-03T19:29:55.896178942Z",
  "connectorSpec": {
    "name": "projects/Your-Project-ID/locations/Your-Region/connections/order-bigquery-connector",
    "actions": [
      {
        "entityOperation": {
          "entityId": "Orders",
          "operation": "LIST"
        }
      },
      {
        "entityOperation": {
          "entityId": "Orders",
          "operation": "GET"
        }
      }
    ]
  },
  "displayName": "order bigquery connector tool"
}

A seguir

Para uma lista completa das ferramentas do Integration Connectors compatíveis com o Assistente de IA, consulte a lista de ferramentas do conector do Dialogflow.