Gerenciamento de estado para agentes de dados

Ao criar com a API Análises de conversação, o gerenciamento de estado é uma consideração arquitetônica fundamental. Você gerencia o estado da conversa da API e, para aplicativos que usam o Kit de Desenvolvimento de Agente (ADK), o estado da sessão da estrutura.

Modos de estado da API

O método chat na API Análises de conversação oferece suporte a parâmetros de contexto mutuamente exclusivos que determinam como o estado da conversa é processado.

Use a tabela a seguir para comparar esses modos:

Modo Estado Histórico de conversas Agente Parâmetro Descrição
Conversar com uma referência de conversa Com estado Gerenciado pela API Sim ConversationReference Continua uma conversa com estado fazendo referência a uma conversa e ao agente associado. Google Cloud armazena e gerencia o histórico de conversas. Você envia apenas a nova mensagem para cada turno.
Conversar com uma referência de agente de dados Sem estado Gerenciado pelo aplicativo Sim DataAgentContext Envia uma mensagem sem estado que faz referência a um agente de dados salvo para contexto. O aplicativo precisa gerenciar e fornecer o histórico completo da conversa com cada solicitação.
Conversar com contexto inline Sem estado Gerenciado pelo aplicativo Não InlineContext Envia uma mensagem sem estado que fornece todo o contexto diretamente na solicitação. Esse modo não usa um agente de dados salvo. O aplicativo precisa gerenciar e fornecer o histórico completo da conversa.

Estado da sessão do ADK

Se você usar a estrutura do ADK para orquestração, o ADK vai fornecer uma camada de gerenciamento de estado que opera de maneira independente do estado da API Análises de conversação. Entender as duas camadas é essencial para criar sistemas multiagentes que funcionem corretamente.

O ADK usa convenções de prefixo de chave para controlar o escopo e o ciclo de vida das variáveis de estado. Use a tabela a seguir para avaliar esses escopos:

Prefixo da chave Escopo Ciclo de vida Visível para Exemplos
(sem prefixo) Sessão Somente a sessão atual Todos os agentes na sessão Tópico da conversa atual ou os resultados da última consulta
user: Usuário Em todas as sessões do mesmo usuário Todos os agentes e sessões do usuário especificado Preferências do usuário, IDs de agentes de dados salvos ou configurações de idioma
app: Aplicativo Em todas as sessões de todos os usuários Todos os agentes e todos os usuários Configuração global do aplicativo, IDs de agentes de dados compartilhados ou flags de recursos
temp: Invocação Somente a invocação atual O agente atual na invocação ativa Dados de resposta intermediários, como blocos de streaming ou cálculos em andamento

Para mais informações sobre como compartilhar o estado em sistemas multiagentes, consulte a documentação do ADK.

Como o estado da API e o estado do ADK interagem

Quando você usa a API Análises de conversação com a estrutura do ADK, as camadas de estado funcionam de maneira independente:

  • Estado da API: se o aplicativo usar referências de conversa (modo com estado), a API vai gerenciar o histórico de conversas. Se o aplicativo usar o contexto do agente de dados ou o contexto inline (modos sem estado), a API vai permanecer sem estado para cada chamada.
  • Estado da sessão do ADK: a estrutura do ADK mantém a própria sessão, eventos e variáveis de estado, independentemente do modo usado pela API Análises de conversação.

Por exemplo, quando você usa as ferramentas ask_data_insights ou ask_data_agent no ADK, cada chamada é independente e sem estado no nível da API, mesmo que o ADK mantenha o contexto da sessão mais amplo. A demonstração de streaming do ADK ilustra o padrão recomendado para essa interação: um subagente de dados grava dados de resposta analisados no estado temp:, que os agentes downstream leem na mesma invocação.

A seguir