---
title: "Test an agent"
method: POST
path: "/v1/agents/{agentId}/test"
tags: ["Agents"]
---

# Test an agent

`POST /v1/agents/{agentId}/test`

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.

## Path parameters

- `agentId` string, required

## Request body

- AgentTestRequest — Run the agent and return what it would say. Nothing is delivered to anyone, no execution is recorded, and nothing is charged.
  - `message` string, required — What to say to the agent.
  - `history` object[] — Prior turns, oldest first, to exercise multi-turn behaviour without persisting a thread. Trimmed to the agent's context window.
    - `role` 'user' | 'assistant', required
    - `content` string, required
  - `useKnowledgeBase` boolean — Set false to skip retrieval and isolate prompt behaviour from the knowledge base.
  - `executeTools` boolean — 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`.

## Response `200`

The agent's reply.

- AgentTestResponse
  - `success` boolean, required
  - `text` string, nullable, required — What the agent would reply.
  - `error` string, nullable, required
  - `inputTokens` integer, required
  - `outputTokens` integer, required
  - `latencyMs` integer, required
  - `knowledgeChunksUsed` integer, required — Knowledge-base chunks retrieved for this message. Zero means the answer was not grounded in your documents.
  - `executedToolCalls` object[] — 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.
    - `name` string, required
    - `ok` boolean, required
    - `error` string, nullable
  - `warnings` string[], 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.

## Other responses

- `400` — message is required.
- `401` — Unauthorized.
- `404` — Sender or agent not found.

---

[API](https://skmtc.net/zavudev/apis/zavu-unified-messaging-layer-api.md) · [All operations](https://skmtc.net/zavudev/apis/zavu-unified-messaging-layer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zavudev/zavu-unified-messaging-layer-api/revisions/4dacdff2adf8/schema)