Com essas ferramentas, é possível conectar apps de agentes a sistemas externos. Esses sistemas podem aumentar o conhecimento dos apps de agentes e capacitá-los para executar tarefas complexas com eficiência.
É possível usar ferramentas integradas ou criar ferramentas personalizadas para atender aos seus requisitos.
Limitações
Considere as seguintes limitações:
- Crie um repositório de dados (ou conecte um repositório atual) ao criar uma ferramenta de repositório de dados para um app agente.
- Apps com armazenamentos de dados em partes e não divididos não são compatíveis.
Ferramentas integradas
As ferramentas integradas são hospedadas pelo Google. É possível ativar essas ferramentas em apps de agentes sem precisar de configuração manual.
As ferramentas integradas com suporte são:
Code Interpreter: uma ferramenta própria do Google que combina os recursos de geração e execução de código e permite que o usuário realize várias tarefas, como análise e visualização de dados, processamento de texto, solução de equações ou problemas de otimização.
O app do agente é otimizado para determinar como e quando essas ferramentas precisam ser invocadas, mas você pode fornecer mais exemplos de acordo com seus casos de uso.
Os exemplos precisam ter o seguinte esquema:
{
"toolUse": {
"tool": "projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/tools/df-code-interpreter-tool",
"action": "generate_and_execute",
"inputParameters": [
{
"name": "generate_and_execute input",
"value": "4 + 4"
}
],
"outputParameters": [
{
"name": "generate_and_execute output",
"value": {
"output_files": [
{
"name": "",
"contents": ""
}
],
"execution_result": "8",
"execution_error": "",
"generated_code": "GENERATED_CODE"
}
}
]
}
}
Ferramentas OpenAPI
Para se conectar a uma API externa usando uma ferramenta OpenAPI, o app agente pode fornecer o esquema OpenAPI. Por padrão, o app do agente chamará a API em seu nome. Como alternativa, execute as ferramentas da OpenAPI no lado do cliente.
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: Dialogflow session id
required: false
schema:
$ref: "@dialogflow/sessionId"
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
Opcionalmente, use a referência de esquema interna @dialogflow/sessionId como o tipo de esquema de parâmetro.
Com esse tipo de esquema de parâmetro, o ID da sessão do Dialogflow para a conversa atual é fornecido como um valor de parâmetro.
Exemplo:
- name: X-SESSION
in: header
description: Dialogflow session id
required: false
schema:
$ref: "@dialogflow/sessionId"
Limitações da ferramenta OpenAPI
Considere as seguintes limitações:
- Os tipos de parâmetros aceitos são
path,queryeheader. O tipo de parâmetrocookieainda não é compatível. - Os parâmetros definidos pelo esquema da OpenAPI são compatíveis com os seguintes tipos de dados:
string,number,integer,booleanearray. O tipoobjectainda não é compatível. - No momento, não é possível especificar parâmetros de consulta no editor de exemplo do console.
- O corpo da solicitação e da resposta precisa estar vazio ou em JSON.
Autenticação da API da ferramenta OpenAPI
As opções de autenticação a seguir são compatíveis ao chamar uma API externa:
- Autenticação do agente de serviço do Dialogflow
- O Dialogflow pode gerar um token de ID ou token de acesso usando o Agente de serviço do Dialogflow (em inglês). O token é adicionado ao cabeçalho HTTP de autorização quando o Dialogflow chama uma API externa.
- Um token de ID pode ser usado para acessar os serviços do Cloud Functions e do Cloud Run depois de conceder os papéis roles/cloudfunctions.invoker e roles/run.invoker a service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com. Se os serviços do Cloud Functions e do Cloud Run estiverem no mesmo projeto de recursos, você não precisará de outra permissão do IAM para chamá-los.
- É possível usar um token de acesso para acessar outras APIs do Google Cloud depois de conceder os papéis necessários a service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com.
- Chave de API
- É possível configurar a autenticação da 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 Dialogflow a transmita na solicitação.
- OAuth
- O fluxo de credenciais do cliente OAuth é compatível com a autenticação de servidor para servidor. O ID do cliente, a chave secreta do cliente e o endpoint do token do provedor OAuth precisam ser configurados no Dialogflow. O Dialogflow troca um token de acesso OAuth e o transmite no cabeçalho Auth da solicitação.
- Para outros fluxos do OAuth, é necessário usar a ferramenta de funções para fazer a integração com sua própria UI de login e trocar o token.
- Autenticação TLS mútua
- Consulte a documentação Autenticação TLS mútua.
- Certificado de CA personalizado
- Consulte a documentação Certificados de CA personalizados.
Ferramentas de repositório de dados
As ferramentas de repositório de dados podem ser usadas por um app agente para responder às perguntas do usuário final nos seus armazenamentos de dados. É possível configurar um repositório de dados de cada tipo por ferramenta, e a ferramenta consultará cada um desses armazenamentos para encontrar respostas. Por padrão, o app do agente chamará a ferramenta de repositório de dados em seu nome. Outra opção é executar ferramentas de repositório de dados no lado do cliente.
O tipo de repositório de dados pode ser um dos seguintes:
PUBLIC_WEB: um repositório de dados com conteúdo público da Web.UNSTRUCTURED: um repositório de dados que contém dados particulares não estruturados.STRUCTURED: um repositório de dados que contém dados estruturados (por exemplo, perguntas frequentes).
O exemplo a seguir mostra como referenciar um repositório de dados:
"dataStoreConnections": [
{
"dataStoreType": "PUBLIC_WEB",
"dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
},
{
"dataStoreType": "UNSTRUCTURED",
"dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
},
{
"dataStoreType": "STRUCTURED",
"dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
}
]
As respostas da ferramenta de repositório de dados também podem conter snippets sobre a origem do conteúdo que foi usada para gerar a resposta. O app do agente pode fornecer mais instruções sobre como proceder com a resposta dos repositórios de dados ou como responder quando não houver resposta.
Para substituir uma resposta, adicione uma entrada de Perguntas frequentes para uma pergunta específica.
Os exemplos podem ser usados para melhorar ainda mais o comportamento do app do agente. O exemplo precisa ter os seguintes esquemas:
{
"toolUse": {
"tool": "projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/tools/TOOL_ID",
"action": "TOOL_DISPLAY_NAME",
"inputParameters": [
{
"name": "TOOL_DISPLAY_NAME input",
"value": {
"query": "QUERY"
}
}
],
"outputParameters": [
{
"name": "TOOL_DISPLAY_NAME output",
"value": {
"answer": "ANSWER",
"snippets": [
{
"title": "TITLE",
"text": "TEXT_FROM_DATASTORE",
"uri": "URI_OF_DATASTORE"
}
]
}
}
]
}
}
Criar um repositório de dados
Para criar um repositório de dados e conectá-lo ao seu app, use o link Tools no painel de navegação à esquerda do console. Siga as instruções para criar um repositório de dados.
Parâmetros de consulta adicionais
Ao criar exemplos de ferramenta de repositório de dados, dois parâmetros opcionais estão
disponíveis, junto com a string query obrigatória: uma string filter
e um objeto estruturado userMetadata.
O parâmetro filter permite filtrar as consultas de pesquisa dos seus dados estruturados ou não estruturados com metadados. Essa string precisa seguir a sintaxe da expressão de filtro compatível.
Recomendamos vários exemplos para instruir o LLM do agente sobre como
preencher esse parâmetro. No caso de uma string de filtro inválida, o filtro será ignorado ao realizar a consulta de pesquisa.
Este é um exemplo de string filter para refinar os resultados da pesquisa com base na localização:
"filter": "country: ANY(\"Canada\")"
O parâmetro userMetadata fornece informações sobre o usuário final. Qualquer
par de chave-valor pode ser preenchido nesse parâmetro. Esses metadados são transmitidos à ferramenta de repositório de dados para informar melhor os resultados da pesquisa e a resposta da ferramenta. É recomendável fornecer vários exemplos para instruir o
LLM do agente sobre como preencher esse parâmetro.
Este é um exemplo de valor de parâmetro userMetadata para refinar os resultados da pesquisa relevantes para um usuário específico:
"userMetadata": {
"favoriteColor": "blue",
...
}
Se você encontrar que algumas respostas durante o teste não atendem às suas expectativas, as personalizações abaixo estão disponíveis na página "Ferramenta" de uma ferramenta de repositório de dados:
Confiança de embasamento
Para cada resposta gerada do conteúdo dos repositórios de dados conectados, o agente avalia um nível de confiança, que mede a confiança de que todas as informações na resposta são compatíveis com as informações nos armazenamentos de dados. Você pode personalizar quais respostas permitir, selecionando o nível de confiança mais baixo que você quer. Somente as respostas com um nível de confiança igual ou maior que esse serão mostradas.
Há cinco níveis de confiança para escolher: VERY_LOW, LOW, MEDIUM, HIGH e VERY_HIGH.
Configuração do resumo
É possível selecionar o modelo generativo usado por um agente de repositório de dados para a solicitação generativa de resumo. Se nenhum for selecionado, uma opção de modelo padrão será usada. A tabela a seguir contém as opções disponíveis:
| Identificador do modelo | Suporte a idiomas |
|---|---|
| text-bison@001 | Disponível em todos os idiomas compatíveis. |
| text-bison@002 | Disponível em todos os idiomas compatíveis. |
| text-bison@001 sintonizado (conversa) | No momento, apenas o inglês é compatível. |
| texto-bison@001 ajustado (informativo) | No momento, apenas o inglês é compatível. |
| gêmeo-pro | Disponível em todos os idiomas compatíveis. |
Você também pode fornecer seu próprio comando para a chamada de resumo do LLM.
O comando é um modelo de texto que pode conter marcadores de posição predefinidos. Os marcadores de posição serão substituídos pelos valores apropriados no momento da execução, e o texto final será enviado ao LLM.
Os marcadores de posição são os seguintes:
$original-query: o texto da consulta do usuário.$rewritten-query: o agente usa um módulo de regravação para reescrever a consulta do usuário original em um formato mais preciso.$sources: o agente usa o Enterprise Search para procurar origens com base na consulta do usuário. As origens encontradas são renderizadas em um formato específico:[1] title of first source content of first source [2] title of second source content of first source$conversation: o histórico de conversas é renderizado no seguinte formato:Human: user's first query AI: answer to user's first query Human: user's second query AI: answer to user's second query
Um prompt personalizado precisa instruir o LLM a retornar "NOT_ENOUGH_INFORMATION" quando não puder fornecer uma resposta. O agente transformará essa constante em uma mensagem fácil de usar para o usuário.
Frases banidas (configuração no nível do agente)
Você tem a opção de definir frases específicas que não devem ser permitidas. Eles são configurados no nível do agente e utilizados pelos LLMs do agente e pelas ferramentas de repositório de dados. Se a resposta gerada ou partes do comando do LLM, como as entradas do usuário, contiverem qualquer uma das frases banidas na íntegra, essa resposta não será mostrada.
Ferramentas de funções
Se você tiver uma funcionalidade acessível pelo código do cliente, mas não acessível pelas ferramentas da OpenAPI, será possível usar as ferramentas de função. As ferramentas de funções são sempre executadas no lado do cliente, não pelo app do agente.
O processo é o seguinte:
- O código do cliente envia uma solicitação de detecção de intent.
- O app do agente detecta que uma ferramenta de função é necessária, e a resposta de detecção de intent contém o nome da ferramenta com argumentos de entrada. Essa sessão é pausada até que outra solicitação de detecção de intent seja recebida com o resultado da ferramenta.
- Seu código de cliente chama a ferramenta.
- O código do cliente envia outra solicitação de detecção de intent que fornece o resultado da ferramenta como argumentos de saída.
O exemplo abaixo mostra o esquema de entrada e saída de uma ferramenta de funções:
{
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, for example, San Francisco, CA"
}
},
"required": [
"location"
]
}
{
"type": "object",
"properties": {
"temperature": {
"type": "number",
"description": "The temperature"
}
}
}
O exemplo a seguir mostra a solicitação e a resposta de intent de detecção inicial usando REST:
HTTP method and URL:
POST https://REGION_ID-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent
{
"queryInput": {
"text": {
"text": "what is the weather in Mountain View"
},
"languageCode": "en"
}
}
{
"queryResult": {
"text": "what is the weather in Mountain View",
"languageCode": "en",
"responseMessages": [
{
"source": "VIRTUAL_AGENT",
"toolCall": {
"tool": "<tool-resource-name>",
"action": "get-weather-tool",
"inputParameters": {
"location": "Mountain View"
}
}
}
]
}
}
O exemplo a seguir mostra a segunda solicitação de detecção de intent, que fornece o resultado da ferramenta:
{
"queryInput": {
"toolCallResult": {
"tool": "<tool-resource-name>",
"action": "get-weather-tool",
"outputParameters": {
"temperature": 28.0
}
},
"languageCode": "en"
}
}
Execução do lado do cliente
Assim como as ferramentas de função, as ferramentas da OpenAPI e do repositório de dados podem ser executadas no lado do cliente aplicando uma substituição de API ao interagir com a sessão.
Exemplo:
DetectIntentRequest {
...
query_params {
playbook_state_override {
playbook_execution_mode: ALWAYS_CLIENT_EXECUTION
}
}
...
}
O processo é o seguinte:
- O código do cliente envia uma solicitação de detecção de intent que especifica a execução do cliente.
- O app do agente detecta que uma ferramenta é necessária, e a resposta de detecção de intent contém o nome da ferramenta com argumentos de entrada. Essa sessão é pausada até que outra solicitação de detecção de intent seja recebida com o resultado da ferramenta.
- Seu código de cliente chama a ferramenta.
- O código do cliente envia outra solicitação de detecção de intent que fornece o resultado da ferramenta como argumentos de saída.