Sign in

v54

latestOpenAPI 3.0.3raw.githubusercontent.com2026-08-06178189573.7 KB
Agents

Test an agent

Run the agent's prompt, model and knowledge base against a message and return the reply instead of delivering it. Writes nothing and charges nothing, so it is safe to call repeatedly while iterating on a prompt.

Note that a dry run never executes tools — running them would cause real side effects. Live conversations on every channel do call them. When the agent has enabled tools, that gap is reported in warnings rather than silently producing an answer that looks like a tool call happened.

post/v1/agents/{agentId}/test

Path parameters

agentIdstring required

Agent ID.

Request body

messagestring required

What to say to the agent.

useKnowledgeBaseboolean

Set false to skip retrieval and isolate prompt behaviour from the knowledge base.

Example request

{
  "message": "Where is order ORD-12345?"
}

Response

The agent's reply.

successboolean required
textstring nullable required

What the agent would reply.

errorstring nullable required
inputTokensinteger required
outputTokensinteger required
latencyMsinteger required
knowledgeChunksUsedinteger required

Knowledge-base chunks retrieved for this message. Zero means the answer was not grounded in your documents.

warningsstring[] required

Things that are true of this agent but that a dry run cannot prove. Surfaced so a passing dry run is never mistaken for proof that the agent works live.

  • The agent being disabled.
  • Enabled tools that were not offered to the model here — the model never saw them, so a reply that looks like a lookup was invented. Live conversations on every channel do offer them; running them here would cause real side effects.
  • An agent whose sender has none of the channels it triggers on, which answers every dry run and no real message.
  • Contact metadata that exists on a real conversation but not here.