Como estruturo as instruções para o agente consultar um documento antes de responder?

O padrão recomendado usa três situações dentro do estado, para você ter controle fino de cada momento da consulta. Um exemplo genérico: o usuário pergunta o endereço da loja, e o endereço está num documento do agente.

Situação 1 — disparar a consulta. Na descrição, o cenário sem informação: "o usuário perguntou sobre endereço e ainda não há trechos recuperados do documento". Em Ferramentas, informe o documento a consultar (consult_document com o nome do documento). Em Gestão de Estados, use should_transition_before_response: true com o lookahead_state desejado. Em Resposta ao Usuário, instrua a deixar a mensagem em branco — nada será enviado nessa execução; ela vira apenas um registro interno no histórico.

Situação 2 — responder com a informação encontrada. Na descrição, o cenário com informação suficiente: "o usuário perguntou sobre endereço e os trechos recuperados do documento contêm o endereço explícito". Sem ferramentas (o documento já foi consultado). Em Resposta ao Usuário, a instrução de elaboração — por exemplo: "liste os endereços recuperados e pergunte se pode ajudar em algo mais".

Situação 3 — informação insuficiente. Na descrição, escreva com clareza o seu critério do que é insuficiente: "os trechos recuperados não trazem endereço, ou trazem endereço de outra unidade". Em Resposta ao Usuário, o que fazer nesse caso — por exemplo, dizer que não localizou a informação e oferecer o contato do atendimento.

A regra do estado: se o lookahead_state da Situação 1 aponta para o mesmo estado, as três situações moram juntas nele. Se aponta para outro estado, as Situações 2 e 3 precisam morar no estado de destino — é lá que o agente vai estar quando for elaborar a resposta com os trechos recuperados.

Por que não comprimir tudo numa situação só? Funciona: se você definir na mesma situação a consulta ao documento e uma instrução de resposta, a plataforma prioriza a consulta e retém a primeira mensagem como interna — o usuário só vê a resposta elaborada depois. Mas você perde o controle do critério de suficiência (Situações 2 e 3) e o histórico ganha uma mensagem interna elaborada à toa. Separando, a mensagem interna vem em branco e cada cenário tem a sua instrução exata.