Agentes

Um agente do Dialogflow CX é um agente virtual que processa as conversas simultâneas com seus usuários finais. Ele é um módulo de processamento de linguagem natural que entende as nuances da fala humana. O Dialogflow CX converte textos ou áudios de uma conversa com o usuário final em dados estruturados que seus aplicativos e serviços podem entender. Você projeta e cria um agente do Dialogflow CX para atender aos tipos de conversa solicitadas pelo seu sistema.

Um agente do Dialogflow CX é semelhante a um atendente humano de call center. O agente pode ser treinado para lidar com os cenários comuns de conversas, e o treinamento não precisa ser muito detalhado.

Criar um agente

Observação: é possível criar vários agentes do Dialogflow CX para um projeto na nuvem do Google Cloud.

Para criar um agente, siga estas etapas:

Console

1. Abra o console do Dialogflow CX.
2. Criar ou escolher um projeto
3. Clique em Criar agente.
4. Selecione Gerar automaticamente para criar um agente de repositório de dados ou Crie o seu para criar outros tipos de agentes.
5. Preencha o formulário para as configurações básicas do agente.
   1. Você pode escolher qualquer nome de exibição.
   2. Selecione um local. Se quiser mudar as configurações de localização avançadas, clique no botão Editar.
   3. Selecione o fuso horário.
   4. Selecione o idioma padrão do agente. Não é possível mudar o idioma padrão de um agente depois que ele é criado.
6. Clique em Salvar.

API

Se você ainda não tiver configurado as configurações de localização do projeto, faça isso com o console antes de criar agentes com a API. Não é possível definir as configurações de localização com a API.

Para criar um agente, consulte o método create para o tipo Agent. Acessar a referência da API Agent

Selecione um protocolo e uma versão para a referência do agente:

Protocolo	V3	V3beta1
REST	Recurso do agente	Recurso do agente
RPC (remote procedure call)	Interface do agente	Interface do agente
C++	AgentsClient (em inglês)	Indisponível
C#	AgentsClient (em inglês)	Indisponível
Go	AgentsClient (em inglês)	Indisponível
Java	AgentsClient (em inglês)	AgentsClient (em inglês)
Node.js	AgentsClient (em inglês)	AgentsClient (em inglês)
PHP	Indisponível	Indisponível
Python	AgentsClient (em inglês)	AgentsClient (em inglês)
Ruby	Indisponível	Indisponível

Fechar

Dados do agente

Os agentes do Dialogflow CX servem como contêineres de nível superior para configurações e dados de agentes virtuais. Os seguintes dados estão associados a agentes:

• Intents
• Tipos de entidade
• Webhooks
• Fluxos
• Pages
• Grupos de rotas

Para mais informações sobre como os dados são aplicados em vários níveis, consulte os níveis de aplicação de dados.

Endpoint inteligente

Se o endpoint inteligente estiver ativado para o agente, você poderá personalizar o comportamento do endpoint inteligente para um parâmetro numérico da seguinte maneira:

1. Defina Número mínimo de dígitos para sugerir ao smart endpointer que aguarde até que todos os dígitos sejam coletados.
2. Defina Corrigir transcrições para melhorar o reconhecimento de fala de dígitos corrigindo erros comuns de transcrição de dígitos. Isso só é compatível com solicitações que especificam um código de idioma en ou en-*.
3. Defina Tempo limite de espera para especificar o tempo adicional. O Dialogflow CX vai aguardar que o usuário forneça mais informações.

A API Speech-to-Text (STT) converte áudio em texto usando aprendizado de máquina, permitindo que você integre o reconhecimento de fala aos seus aplicativos.

Os modelos de STT compatíveis incluem qualquer modelo longo, por exemplo, phone_call. Apenas o idioma en-US é compatível.

Observação: se você estiver usando o modelo curto, isso vai ativar o endpoint de fala na nuvem.

O tempo limite do Dialogflow CX é um período de carência que permite ao usuário adicionar algo à transcrição de STT antes que o tempo limite de fala seja acionado. Quando o tempo limite de fala é acionado, o Dialogflow CX inicia o fulfillment de intent (por exemplo, feedback natural, resposta do agente virtual, execução de webhook + resposta do agente virtual).

O Dialogflow CX usa heurísticas para especificar qual tempo limite precisa ser escolhido com base na transcrição. Por exemplo, ele pode escolher um tempo limite muito curto se a intenção foi correspondida com sucesso. Se a intent não for correspondida, o tempo limite poderá ser aumentado para permitir que o usuário diga algo mais e tente novamente a correspondência de intent.

Agora, os projetos podem aproveitar as seguintes melhorias na STT:

• Endpointing mais rápido:a análise em tempo real usa o streaming de transcrição de áudio para distinguir entre uma pausa natural e a conclusão de uma declaração enquanto o stream de STT permanece aberto. Se o usuário terminar de falar, o Dialogflow CX vai encerrar o fluxo antes para dar uma resposta mais rápida.
• Coleta de dígitos otimizada:o Dialogflow CX usa heurísticas nas transcrições finais de STT para verificar se todos os dígitos esperados foram capturados. Ele também corrige automaticamente erros comuns de transcrição (por exemplo, resolvendo "to"/"too" como "2", "for" como "4" ou "ate"/"weight" como "8").
• Feedback de conversa natural:se o usuário pausar no meio da fala, o Dialogflow CX poderá estender dinamicamente o tempo limite da STT para evitar interrupções prematuras ou inserir dicas naturais de backchanneling (por exemplo, "hum hum", "ahã") para confirmar que o agente virtual ainda está ouvindo.

Exportar e restaurar um agente

Aviso: não vamos mais exportar credenciais de valor bruto para ferramentas e webhooks da OpenAPI a partir de 15 de agosto de 2025. Migre para armazenar suas credenciais no Secret Manager. Para instruções, consulte as documentações de Webhook e Ferramenta.

É possível exportar um agente para um arquivo e restaurar um agente com esse arquivo.

Uma exportação de agente inclui todos os dados do agente, exceto:

• Versões de fluxo: somente os fluxos de rascunho são exportados para um arquivo.
• Ambientes: os ambientes personalizados não são exportados para um arquivo.

Uma restauração de agente substitui todos os dados do agente de destino (incluindo todas as versões de fluxo), exceto o seguinte:

• Ambientes: todos os ambientes personalizados permanecem inalterados no agente de destino. As versões de fluxo referenciadas por ambientes personalizados no agente de destino vão continuar existindo enquanto os ambientes associados existirem. No entanto, essas versões de fluxo desatualizadas não são listadas nem podem ser selecionadas pelo agente.
• Apps de agentes da Vertex AI: A associação a um app de agentes da Vertex AI permanece inalterada no agente de destino (ou seja, o valor de engine em GenAppBuilderSettings). Isso significa que os agentes do repositório de dados só podem ser restaurados em outros agentes de repositório de dados porque o agente resultante também precisa ter uma associação com um app de agentes da Vertex AI.

• Repositórios de dados de agentes da Vertex AI: todas as referências a repositórios de dados serão substituídas no agente de destino, de acordo com as seguintes regras:

  • Se o agente de destino não estiver associado a um app, não será possível restaurar um agente com referências de repositório de dados. A tentativa de fazer isso resulta em uma mensagem de erro. Para corrigir isso, você pode criar um novo agente de repositório de dados do zero. Como alternativa, você pode transformar seu agente atual em um agente de repositório de dados adicionando um gerenciador de estado a ele. Nesse caso, você vai receber orientações sobre como adicionar um app associado ao seu agente.
  • Se o agente de destino estiver associado a um app, todas as referências do repositório de dados serão atualizadas após a restauração: o ID do projeto e o local do Google Cloud serão atualizados para corresponder ao app do agente de destino. O ID da coleção e o ID do repositório de dados vão permanecer inalterados. Isso significa que você precisa adicionar repositórios de dados para todos os IDs com tipos correspondentes ao app do agente de destino antes da operação de restauração.

  Exemplo: se o agente de origem se referir a um repositório de dados chamado projects/123/locations/eu-west2/collections/default_collection/dataStores/myDataStore1 e o app do agente de destino se chamar projects/321/locations/us-east1/collections/default_collections/engines/app123, a referência resultante do repositório de dados no agente de destino será: projects/321/locations/us-east1/collections/default_collection/dataStores/myDataStore1

Observação: na API e no conteúdo dos dados exportados, um app de agentes da Vertex AI é chamado de mecanismo do GenAppBuilder. Por exemplo, em um pacote JSON exportado, você pode encontrar o nome do mecanismo no arquivo agent.json, na chave genAppBuilderSettings.engine.

Ao exportar, você pode selecionar o formato do arquivo. Se você estiver usando o controle de versão de origem para os dados do seu agente, exporte no formato JSON. Quando você restaura um agente, o Dialogflow CX determina automaticamente o formato do arquivo.

Para exportar ou restaurar um agente:

Console

1. Abra o console do Dialogflow CX.
2. Escolha o projeto para o agente.
3. Selecione a opção de menu para um agente na lista.
4. Clique no botão Exportar ou Restaurar.
5. Siga as instruções para concluir.

Observação: para restaurar um agente de repositório de dados, verifique se o agente de destino foi criado como um agente de repositório de dados.

API

Veja os métodos export e restore para o tipo Agent. Acessar a referência da API Agent

Selecione um protocolo e uma versão para a referência do agente:

Protocolo	V3	V3beta1
REST	Recurso do agente	Recurso do agente
RPC (remote procedure call)	Interface do agente	Interface do agente
C++	AgentsClient (em inglês)	Indisponível
C#	AgentsClient (em inglês)	Indisponível
Go	AgentsClient (em inglês)	Indisponível
Java	AgentsClient (em inglês)	AgentsClient (em inglês)
Node.js	AgentsClient (em inglês)	AgentsClient (em inglês)
PHP	Indisponível	Indisponível
Python	AgentsClient (em inglês)	AgentsClient (em inglês)
Ruby	Indisponível	Indisponível

Fechar

Se o tamanho do agente exceder o limite máximo, use a opção do Cloud Storage para exportar e restaurar o agente.

Se você usa o GitHub, consulte também o guia de exportação/restauração do GitHub.

Excluir um agente

Atenção: não é possível desfazer a ação de excluir um agente. Exporte-o para manter um backup, caso seja necessário.

Para excluir um agente, é preciso ter um papel que forneça acesso total ou acesso para edição. Para mais informações, consulte o Guia de controle de acesso.

Para excluir um agente:

Console

1. Abra o console do Dialogflow CX.
2. Escolha o projeto para o agente.
3. Selecione a opção de menu para um agente na lista.
4. Clique no botão .
5. Confirme a exclusão na caixa de diálogo.

API

Veja o método delete para o tipo Agent. Acessar a referência da API Agent

Selecione um protocolo e uma versão para a referência do agente:

Protocolo	V3	V3beta1
REST	Recurso do agente	Recurso do agente
RPC (remote procedure call)	Interface do agente	Interface do agente
C++	AgentsClient (em inglês)	Indisponível
C#	AgentsClient (em inglês)	Indisponível
Go	AgentsClient (em inglês)	Indisponível
Java	AgentsClient (em inglês)	AgentsClient (em inglês)
Node.js	AgentsClient (em inglês)	AgentsClient (em inglês)
PHP	Indisponível	Indisponível
Python	AgentsClient (em inglês)	AgentsClient (em inglês)
Ruby	Indisponível	Indisponível

Fechar

Se você excluir seu projeto, todos os agentes e dados do Dialogflow CX associados a ele serão excluídos imediatamente.