Você pode usar os recursos do Assistente de agente com APIs e fontes de dados externas.O Google Cloud fornece ferramentas do OpenAPI e do Integration Connectors para facilitar as integrações do Assistente de agente.
Ferramentas da OpenAPI
As ferramentas OpenAPI permitem a conexão entre os recursos do Assistente do agente e as APIs externas. Essa conexão permite que os recursos do Assistente do agente 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 conectores de integração para se conectar Google Cloud a várias fontes de dados. Com as ferramentas de conector, os recursos do Assistente de agente 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.
- Personalize o código da seguinte forma:
- Em um único projeto, use um valor de
tool_keyexclusivo entre todas as suas ferramentas. - Insira seu próprio esquema da OpenAPI no campo
open_api_spec.text_schema.
- Em um único projeto, use um valor de
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 do call center.
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 função.
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 Conectores de integração usando o console do Google Cloud . Siga estas etapas para criar uma ferramenta de conectores de integração do Assistente de IA 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.