Sign in

v51

latestOpenAPI 3.0.3raw.githubusercontent.com2026-08-02172186551.1 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 this exercises the text path, which does not offer tools to the model. When the agent has enabled tools, that 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: the agent being disabled, enabled tools that its channels will never call (the text path does not offer tools to the model), and contact metadata that exists on a real conversation but not here. Surfaced so a passing dry run is never mistaken for proof that the agent works live.