chat_with_agent
Send a message to an AI agent and receive its full synchronous response, including session ID, tools used, and execution details. Reuse the session ID to maintain conversation context.
Instructions
Envia uma mensagem a um agente e recebe a resposta completa (síncrono — sem streaming progressivo). O agente usa todas as tools configuradas (api_config, MCP externo).
Resposta inclui: response (texto), session_id (manter para contexto), tools_used (nomes), tool_calls (detalhes com name, duration_ms, success), execution_time_ms, model_used, execution_id (correlação com get_execution_diagnostics). outcome nomeia o desfecho real do turno (COMPLETED, LENGTH, CANCELLED, PAUSED, BUDGET_EXCEEDED, QUOTA_EXCEEDED, SESSION_BUSY, TIMEOUT ou ERROR); success só é true para COMPLETED e LENGTH (resposta cortada pelo teto de saída, mas entregue) — não confie só em success===true sem checar outcome se precisar distinguir bloqueio de sucesso pleno. outcome TIMEOUT com resposta = a chamada ao modelo passou do tempo; vem com timed_out: true e timeout_clock (first_signal = o provedor não começou a responder; idle = parou no meio; call = a chamada sem stream passou do teto). A resposta é a mensagem de falha do turno e o motivo fica na execução (get_execution_diagnostics). Turno que estoura o deadline do runtime retorna erro TURN_TIMEOUT com execution_id, session_id, timed_out: true e timeout_clock: turn — a execução fica registrada e a sessão pode ser retomada. Consumidor sob controle da plataforma (denylist do tenant, engajamento encerrado ou sessão suspensa) devolve { gated: true, gate, gate_action, response } SEM executar o agente — response é a mensagem fixa configurada, não saída do modelo.
IMPORTANTE: use o session_id retornado nas próximas mensagens para manter o contexto da conversa — ou, em integrações, session_from (a sessão é derivada de campos e você não precisa guardar id).
Integrações (só key admin/owner; em editor/member os campos voltam em ignored_fields): context = dados do sistema de origem que o agente LÊ (vão junto da mensagem, nunca no system prompt); bindings = argumentos AUTORITATIVOS das tools (defaults_from_context / ${context.x}; nunca vão ao modelo nem ficam gravados); session_from = nomes de campos de context/bindings que definem a conversa (mesmo hash do webhook session_strategy derive). A resposta traz accepted_fields e ignored_fields.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | Dados do sistema de origem que o agente lê (ex.: userName). Plano, só escalares, até 2000 caracteres. Vai junto da mensagem do usuário, nunca no system prompt. Chave com nome de segredo é redigida. Só key admin/owner. | |
| message | Yes | Mensagem para enviar ao agente | |
| agent_id | Yes | UUID do agente | |
| bindings | No | Argumentos autoritativos das tools (defaults_from_context / ${context.x}), ex.: idSolicitante. Nunca vão ao modelo nem ficam gravados. Só key admin/owner. | |
| metadata | No | Dados opacos de correlação (ex.: trace_id). Nunca vão ao modelo; gravados (redigidos) em agent_executions.metadata — consultáveis por trace_id. Objeto plano de escalares, até 20 chaves e 4 KB. | |
| session_id | No | ID da sessão retornado por uma chamada anterior. Envie para manter contexto. Omita na primeira mensagem. | |
| consumer_key | No | Identidade do consumidor final em nome de quem a mensagem é enviada (ex.: id do usuário no seu sistema, telefone só-dígitos). Escopa memória e controle de engajamento por pessoa. Sem ela, integrações com key admin/owner rodam SEM memória (falha fechada, doc 38 D5). Keys de papel member já identificam a pessoa e NÃO podem falar por outra. Key de papel editor: o campo é IGNORADO. Sob admin/owner a identidade é DECLARADA: reusar o session_id de OUTRA pessoa é recusado com code CONFLICT (omita o session_id para abrir uma conversa nova); uma conversa que ainda não tem identidade é ADOTADA pela primeira declaração e fica travada nela. | |
| session_from | No | Nomes de campos de context/bindings que definem a conversa (ex.: ["hashFornecedor"]). A sessão é criada na 1ª vez e reaproveitada — mesmo hash do webhook (session_strategy derive). Não combine com session_id. Só key admin/owner. |