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

POST

agents

{agentId}

test

Test an agent

curl --request POST \
  --url https://api.zavu.dev/v1/agents/{agentId}/test \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "Where is order ORD-12345?",
  "history": [
    {
      "content": "<string>"
    }
  ],
  "useKnowledgeBase": true
}
'

import requests

url = "https://api.zavu.dev/v1/agents/{agentId}/test"

payload = {
    "message": "Where is order ORD-12345?",
    "history": [{ "content": "<string>" }],
    "useKnowledgeBase": True
}
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
  })
};

fetch('https://api.zavu.dev/v1/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/v1/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
  ]),
  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/v1/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}")

	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/v1/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}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.zavu.dev/v1/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}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "text": "<string>",
  "error": "<string>",
  "inputTokens": 123,
  "outputTokens": 123,
  "latencyMs": 123,
  "knowledgeChunksUsed": 123,
  "warnings": [
    "<string>"
  ]
}

{
  "code": "invalid_request",
  "message": "Phone number is invalid",
  "details": {}
}

{
  "code": "invalid_request",
  "message": "Phone number is invalid",
  "details": {}
}

{
  "code": "invalid_request",
  "message": "Phone number is invalid",
  "details": {}
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

agentId

string

required

Agent ID.

Body

application/json

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.

Example:

"Where is order ORD-12345?"

history

object[]

Prior turns, oldest first, to exercise multi-turn behaviour without persisting a thread. Trimmed to the agent's context window.

Show child attributes

useKnowledgeBase

boolean

default:true

Set false to skip retrieval and isolate prompt behaviour from the knowledge base.

Response

The agent's reply.

success

boolean

required

text

string | null

required

What the agent would reply.

error

string | null

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.

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.

⌘I

Test an agent

curl --request POST \
  --url https://api.zavu.dev/v1/agents/{agentId}/test \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "Where is order ORD-12345?",
  "history": [
    {
      "content": "<string>"
    }
  ],
  "useKnowledgeBase": true
}
'

import requests

url = "https://api.zavu.dev/v1/agents/{agentId}/test"

payload = {
    "message": "Where is order ORD-12345?",
    "history": [{ "content": "<string>" }],
    "useKnowledgeBase": True
}
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
  })
};

fetch('https://api.zavu.dev/v1/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/v1/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
  ]),
  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/v1/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}")

	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/v1/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}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.zavu.dev/v1/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}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "text": "<string>",
  "error": "<string>",
  "inputTokens": 123,
  "outputTokens": 123,
  "latencyMs": 123,
  "knowledgeChunksUsed": 123,
  "warnings": [
    "<string>"
  ]
}

{
  "code": "invalid_request",
  "message": "Phone number is invalid",
  "details": {}
}

{
  "code": "invalid_request",
  "message": "Phone number is invalid",
  "details": {}
}

{
  "code": "invalid_request",
  "message": "Phone number is invalid",
  "details": {}
}