Orientar o comportamento do agente com contexto criado

Esta página descreve como fornecer o melhor contexto criado para seus agentes de dados da API Conversational Analytics escrevendo comandos eficazes com instruções do sistema e, para algumas fontes de dados, fornecendo contexto estruturado adicionalmente. Embora o contexto criado seja opcional, um contexto bem estruturado pode melhorar a acurácia e a relevância das respostas fornecidas pela API.

O que é contexto criado?

O contexto criado é uma orientação que os desenvolvedores podem fornecer para moldar o comportamento de um agente de dados e refinar as respostas da API. Essas orientações incluem instruções do sistema de formato livre e, para algumas fontes de dados, campos de contexto estruturados com informações como descrições de tabelas e exemplos de consultas. Para responder a perguntas, o agente combina esse contexto criado com informações de fontes de dados (como tabelas do BigQuery, análises detalhadas do Looker e fontes de dados do Looker Studio) e com o histórico de conversas (para conversas em várias etapas).

Ao fornecer orientações claras por meio de campos contextuais estruturados e instruções do sistema de formato livre, você pode melhorar a capacidade do agente de interpretar as perguntas dos usuários e gerar respostas úteis e precisas. Um contexto bem definido é especialmente útil se você estiver se conectando a dados, como tabelas do BigQuery. Por exemplo, é possível usar o contexto criado para fornecer os seguintes tipos de orientação a um agente:

Lógica específica da empresa: defina um cliente "fiel" como aquele que fez mais de cinco compras em um determinado período.
Formatação da resposta: resuma todas as respostas do seu agente de dados em 20 palavras ou menos para economizar tempo dos usuários.
Apresentação de dados: formate todos os números de acordo com o guia de estilo da empresa.

Fornecer contexto criado

As informações específicas que você pode fornecer dependem da sua fonte de dados. Para dados do BigQuery e dados do Looker, é possível definir o contexto estruturado e as instruções do sistema. Para melhores resultados, primeiro forneça contexto ao agente usando os campos estruturados disponíveis. Em seguida, você pode fornecer orientações complementares definindo instruções do sistema.

Você fornece contexto estruturado em campos da API para detalhes como descrições de tabelas e exemplos de consultas. Você fornece instruções do sistema como uma string formatada em YAML usando o parâmetro system_instruction.

Depois de definir o contexto criado, você pode fornecê-lo à API em uma das seguintes chamadas:

Criar um agente de dados persistente: inclua o contexto criado no objeto published_context no corpo da solicitação para configurar um comportamento do agente que persista em várias conversas. Para mais informações, consulte Criar um agente de dados (HTTP) ou Configurar o contexto para chat com ou sem estado (SDK do Python).
Envio de uma solicitação sem estado: forneça o contexto criado no objeto inline_context em uma solicitação de chat para definir o comportamento do agente para essa chamada de API específica. Para mais informações, consulte Criar uma conversa sem estado com várias interações (HTTP) ou Enviar uma solicitação de chat sem estado com contexto inline (SDK do Python).
Enviar uma solicitação de dados de consulta: para fontes de dados de banco de dados, forneça o ID do conjunto de contexto do contexto criado no objeto agent_context_reference na solicitação de dados de consulta. Para mais informações, consulte Definir o contexto do agente de dados para fontes de dados de banco de dados.

Prática recomendada para criar agentes: use o controle de versões para o contexto criado

Use os campos stagingContext, publishedContext e lastPublishedContext para controlar as versões de contexto ao criar agentes com a API Conversational Analytics. O caso de uso a seguir ilustra como usar esses campos para criar uma versão de teste e de produção do contexto do agente.

Suponha que você use um agente com o campo publishedContext, mas precise fazer uma atualização nele (por exemplo, mudar todos os gráficos de azul para verde).

Para fazer e testar as mudanças antes de publicar, siga estas etapas:

Faça as mudanças no agente no campo stagingContext e teste o agente com as mudanças.
Quando as mudanças estiverem prontas, atualize o campo publishedContext com as mudanças de stagingContext.
Se necessário, você pode reverter para o agente antigo atualizando publishedContext para lastPublishedContext.