Test an agent
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.
curl --request POST \
--url https://api.zavu.dev/v2/agents/{agentId}/test \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"message": "Where is order ORD-12345?",
"history": [
{
"content": "<string>"
}
],
"useKnowledgeBase": true,
"executeTools": false
}
'import requests
url = "https://api.zavu.dev/v2/agents/{agentId}/test"
payload = {
"message": "Where is order ORD-12345?",
"history": [{ "content": "<string>" }],
"useKnowledgeBase": True,
"executeTools": False
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
message: 'Where is order ORD-12345?',
history: [{content: '<string>'}],
useKnowledgeBase: true,
executeTools: false
})
};
fetch('https://api.zavu.dev/v2/agents/{agentId}/test', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.zavu.dev/v2/agents/{agentId}/test",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'message' => 'Where is order ORD-12345?',
'history' => [
[
'content' => '<string>'
]
],
'useKnowledgeBase' => true,
'executeTools' => false
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.zavu.dev/v2/agents/{agentId}/test"
payload := strings.NewReader("{\n \"message\": \"Where is order ORD-12345?\",\n \"history\": [\n {\n \"content\": \"<string>\"\n }\n ],\n \"useKnowledgeBase\": true,\n \"executeTools\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.zavu.dev/v2/agents/{agentId}/test")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"message\": \"Where is order ORD-12345?\",\n \"history\": [\n {\n \"content\": \"<string>\"\n }\n ],\n \"useKnowledgeBase\": true,\n \"executeTools\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.zavu.dev/v2/agents/{agentId}/test")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"message\": \"Where is order ORD-12345?\",\n \"history\": [\n {\n \"content\": \"<string>\"\n }\n ],\n \"useKnowledgeBase\": true,\n \"executeTools\": false\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"text": "<string>",
"error": "<string>",
"inputTokens": 123,
"outputTokens": 123,
"latencyMs": 123,
"knowledgeChunksUsed": 123,
"warnings": [
"<string>"
],
"cost": 123,
"plannedToolCalls": [
{
"name": "<string>",
"arguments": "<string>"
}
],
"executedToolCalls": [
{
"name": "<string>",
"ok": true,
"error": "<string>"
}
]
}{
"code": "invalid_request",
"message": "<string>",
"details": {
"errors": [
{
"path": [
"<string>"
],
"message": "<string>",
"code": "<string>"
}
]
}
}{
"code": "invalid_request",
"message": "<string>",
"details": {
"errors": [
{
"path": [
"<string>"
],
"message": "<string>",
"code": "<string>"
}
]
}
}{
"code": "invalid_request",
"message": "<string>",
"details": {
"errors": [
{
"path": [
"<string>"
],
"message": "<string>",
"code": "<string>"
}
]
}
}{
"code": "invalid_request",
"message": "<string>",
"details": {
"errors": [
{
"path": [
"<string>"
],
"message": "<string>",
"code": "<string>"
}
]
}
}{
"code": "invalid_request",
"message": "<string>",
"details": {
"errors": [
{
"path": [
"<string>"
],
"message": "<string>",
"code": "<string>"
}
]
}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Agent ID.
Body
Run the agent and return what it would say. Nothing is delivered to anyone and no execution is recorded.
A run is billed like a live reply: on an agent with the zavu provider it 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, not Zavu. cost on the response is what this run charged.
What to say to the agent.
"Where is order ORD-12345?"
Prior turns, oldest first, to exercise multi-turn behaviour without persisting a thread. Trimmed to the agent's context window.
Show child attributes
Show child attributes
Set false to skip retrieval and isolate prompt behaviour from the knowledge base.
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
The agent's reply. Nothing was delivered.
What the agent would reply.
Knowledge-base chunks retrieved for this message. Zero means the answer was not grounded in your documents.
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). PassexecuteToolsto run them. - Tools that ran for real, when
executeToolswas 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.
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.
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).
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
curl --request POST \
--url https://api.zavu.dev/v2/agents/{agentId}/test \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"message": "Where is order ORD-12345?",
"history": [
{
"content": "<string>"
}
],
"useKnowledgeBase": true,
"executeTools": false
}
'import requests
url = "https://api.zavu.dev/v2/agents/{agentId}/test"
payload = {
"message": "Where is order ORD-12345?",
"history": [{ "content": "<string>" }],
"useKnowledgeBase": True,
"executeTools": False
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
message: 'Where is order ORD-12345?',
history: [{content: '<string>'}],
useKnowledgeBase: true,
executeTools: false
})
};
fetch('https://api.zavu.dev/v2/agents/{agentId}/test', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.zavu.dev/v2/agents/{agentId}/test",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'message' => 'Where is order ORD-12345?',
'history' => [
[
'content' => '<string>'
]
],
'useKnowledgeBase' => true,
'executeTools' => false
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.zavu.dev/v2/agents/{agentId}/test"
payload := strings.NewReader("{\n \"message\": \"Where is order ORD-12345?\",\n \"history\": [\n {\n \"content\": \"<string>\"\n }\n ],\n \"useKnowledgeBase\": true,\n \"executeTools\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.zavu.dev/v2/agents/{agentId}/test")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"message\": \"Where is order ORD-12345?\",\n \"history\": [\n {\n \"content\": \"<string>\"\n }\n ],\n \"useKnowledgeBase\": true,\n \"executeTools\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.zavu.dev/v2/agents/{agentId}/test")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"message\": \"Where is order ORD-12345?\",\n \"history\": [\n {\n \"content\": \"<string>\"\n }\n ],\n \"useKnowledgeBase\": true,\n \"executeTools\": false\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"text": "<string>",
"error": "<string>",
"inputTokens": 123,
"outputTokens": 123,
"latencyMs": 123,
"knowledgeChunksUsed": 123,
"warnings": [
"<string>"
],
"cost": 123,
"plannedToolCalls": [
{
"name": "<string>",
"arguments": "<string>"
}
],
"executedToolCalls": [
{
"name": "<string>",
"ok": true,
"error": "<string>"
}
]
}{
"code": "invalid_request",
"message": "<string>",
"details": {
"errors": [
{
"path": [
"<string>"
],
"message": "<string>",
"code": "<string>"
}
]
}
}{
"code": "invalid_request",
"message": "<string>",
"details": {
"errors": [
{
"path": [
"<string>"
],
"message": "<string>",
"code": "<string>"
}
]
}
}{
"code": "invalid_request",
"message": "<string>",
"details": {
"errors": [
{
"path": [
"<string>"
],
"message": "<string>",
"code": "<string>"
}
]
}
}{
"code": "invalid_request",
"message": "<string>",
"details": {
"errors": [
{
"path": [
"<string>"
],
"message": "<string>",
"code": "<string>"
}
]
}
}{
"code": "invalid_request",
"message": "<string>",
"details": {
"errors": [
{
"path": [
"<string>"
],
"message": "<string>",
"code": "<string>"
}
]
}
}