Skip to content
DashboardGet API key

Test an agent

View .md
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 — and read executedToolCalls.

Test-mode keys are billed the same way, and executeTools with one still reaches your real handlers and writes real memory: a test run is not sandboxed by the key's mode.

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.
  • 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. 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.

400message is required, or the message and history exceed 64 KB.
  • codestringrequired
  • messagestringrequired
  • detailsobject
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject
402The agent runs on a Zavu model and the balance is at or below zero.
  • codestringrequired
  • messagestringrequired
  • detailsobject
404Sender or agent not found.
  • codestringrequired
  • messagestringrequired
  • detailsobject
429Too many test runs for this project. Retry after the number of seconds in the message.
  • codestringrequired
  • messagestringrequired
  • detailsobject