Test an agent

POST

Run the agent's prompt, model and knowledge base against a message and return the reply instead of delivering it. Nothing is delivered and no execution is recorded.

Billed like a live reply. On an agent with the zavu provider the run is charged to your balance at the same price per token, and refused with 402 insufficient_balance at a balance of zero; on a bring-your-own-key agent it costs your provider. cost on the response is what it charged. Runs are rate limited per project (429).

Tools. By default the model is offered the agent's enabled tools but none is run: if it picks one, the reply stops there and plannedToolCalls says which, with what arguments. Set executeTools to run them. That reaches your real handlers, with whatever they cost and change; read executedToolCalls.

Authorization

Authorizationheaderrequired
Bearer YOUR_API_KEY. Create a key in the dashboard.

Path parameters

agentIdstringrequired
Agent ID.

Body

application/json

messagestringrequired
What to say to the agent.
historyobject[]
Prior turns, oldest first, to exercise multi-turn behaviour without persisting a thread. Trimmed to the agent's context window.
2 properties
- rolestringrequired
  One ofuserassistant
- contentstringrequired
useKnowledgeBaseboolean
Set false to skip retrieval and isolate prompt behaviour from the knowledge base.
Defaulttrue
executeToolsboolean
Run the tools the agent calls instead of reporting the choice and stopping.
Off by default because a tool handler talks to the outside world: a rehearsal that charges a card is not a rehearsal. Turn it on to exercise the loop that actually matters — the model picks a tool, the handler answers, the model replies with the result — without sending a message to anyone. What ran comes back in executedToolCalls.
Defaultfalse

Responses

200The agent's reply. Nothing was delivered.

successbooleanrequired
textstringrequirednullable
What the agent would reply.
errorstringrequirednullable
inputTokensintegerrequired
outputTokensintegerrequired
latencyMsintegerrequired
knowledgeChunksUsedintegerrequired
Knowledge-base chunks retrieved for this message. Zero means the answer was not grounded in your documents.
executedToolCallsobject[]
Tools that actually ran, in order, when the request set executeTools. Empty on a normal dry run, where nothing is executed. An entry with ok: false means the agent saw an error and answered around it, which is what a customer would have received.
3 properties
- namestringrequired
- okbooleanrequired
- errorstringnullable
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 offered to the model but not run: if the agent picks one, the reply stops at that choice (see plannedToolCalls). Pass executeTools to run them.
- Tools that ran for real, when executeTools was set, and any that failed.
- 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, and memory tools (remember, recall, save_record), which have no contact to write about on a test run.
costnumberrequired
USD charged to your balance for this run, rounded to 6 decimals. 0 on a bring-your-own-key agent. When the balance covers only part of a run, that part is charged and the next run is refused with 402.
plannedToolCallsobject[]required
Tools the model chose to call, with the arguments it chose, on a run without executeTools. Nothing was executed: the reply stops at the choice. Empty when it answered without reaching for a tool, and on a run that executed tools (see executedToolCalls).
2 properties
- namestringrequired
- argumentsstringrequired
  The arguments as a JSON string.

400`message` is required, or the message and history exceed 64 KB.

codestringrequired
messagestringrequired
detailsobject
Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.
1 properties
- errorsobject[]
  3 properties
  - pathobject[]required
  - messagestringrequired
  - codestring

401Unauthorized.

codestringrequired
messagestringrequired
detailsobject
Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.
1 properties
- errorsobject[]
  3 properties
  - pathobject[]required
  - messagestringrequired
  - codestring

402The agent runs on a Zavu model and the balance is at or below zero.

codestringrequired
messagestringrequired
detailsobject
Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.
1 properties
- errorsobject[]
  3 properties
  - pathobject[]required
  - messagestringrequired
  - codestring

404Agent not found, or it belongs to another project.

codestringrequired
messagestringrequired
detailsobject
Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.
1 properties
- errorsobject[]
  3 properties
  - pathobject[]required
  - messagestringrequired
  - codestring

429Too many test runs for this project. Retry after the number of seconds in the message.

codestringrequired
messagestringrequired
detailsobject
Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.
1 properties
- errorsobject[]
  3 properties
  - pathobject[]required
  - messagestringrequired
  - codestring


curl -X POST "https://api.zavu.dev/v2/agents/agent_abc123/test" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "Where is order ORD-12345?"
}'


{
  "success": true,
  "text": "string",
  "error": "string",
  "inputTokens": 1,
  "outputTokens": 1,
  "latencyMs": 1,
  "knowledgeChunksUsed": 1,
  "executedToolCalls": [
    {
      "name": "string",
      "ok": true,
      "error": "string"
    }
  ],
  "warnings": [
    "string"
  ],
  "cost": 1,
  "plannedToolCalls": [
    {
      "name": "string",
      "arguments": "string"
    }
  ]
}