How agents work

An agent on Zavu is one object that answers on every channel. The same prompt, model, knowledge base and skills serve a WhatsApp message and a phone call. There are two ways to get one, and they produce the same thing:

In code — declare it with defineAgent in a Zavu Function and deploy. The code is the source of truth.
In the dashboard or over the API — create and configure it directly.

This page follows the code-first path end to end, because it is the one with moving parts you cannot see.

The pieces

Two things live in Zavu Cloud that are easy to conflate:

Your Function is your TypeScript, running in its own isolated runtime. It holds your tool handlers — the code that talks to your systems.
The Agent is the configuration a conversation runs against: the prompt, the model, which channels trigger it, its knowledge bases, and pointers to your tools.

npx zavudev deploy publishes the first and derives the second from it.

What a deploy actually does

The step worth understanding is the manifest. After publishing, Zavu asks your function what it declared, and reconciles reality to match it. That is what makes the code the source of truth:

A defineAgent you added becomes a new agent.
A field you changed is updated.
A defineAgent you deleted deletes the agent.

Read the lines above the ✓. npx zavudev deploy prints warnings before the success line, and exits non-zero when your declarations were not synced at all. They cover the cases where a green deploy did not do what it looks like — tools attached to an agent whose channels will never call them, or a second agent landing on a sender that already has one.

A message arrives

A call arrives

Voice adds speech in and out around the same agent, and one important difference: on a call the model is offered your tools. The caller can interrupt while the agent is speaking (barge-in) and the agent stops to listen. It can also transfer to a human, or end the call.

Where tools run

Everywhere.

Channel	Are tools offered to the model?
Voice	Yes
A flow’s `tool` step	Yes
Text (WhatsApp, SMS, Telegram, email)	Yes

A text agent asked to look something up calls the tool and answers with what it returned. The model may chain up to five tool rounds in a single reply, and you are billed for the tokens the whole loop uses. Flows are still worth reaching for, but for a different reason than they used to be: a flow runs the steps you wrote, in the order you wrote them. Use one when the sequence has to be deterministic rather than decided by the model. Two things this does not cover, both of which npx zavudev agents test will tell you about:

A dry run never executes a tool, because doing so would fire real webhooks from a test box. It reports which tools it withheld, so an answer that looks like a lookup is never mistaken for one.
An agent is only reachable on the channels its sender actually has. An agent whose sender has none, or none of the ones the agent triggers on, answers every dry run and no real message.

What you can verify, and when

Most of the loop is free and instant. The last step is not.

Step	Cost	What it proves
`tsc`	free	Your code is valid against the runtime’s types
`fn invoke --tool`	free	A handler does what you think, in isolation
`agents list`	free	The deploy created what you meant
`agents test`	free	The prompt, model and retrieval produce the right answer
A real message or call	billed	Everything else, including tool calling on voice

agents test runs the text path. It exercises the prompt, the model and the knowledge base, and it reports what it could not prove — a disabled agent, tools its channels will not call, flows it did not evaluate. Treat those warnings as part of the result.

Agents and senders

A sender is the identity a conversation happens on: a phone number, a WhatsApp account, an email address. An agent can answer on several senders. A sender answers with at most one agent — connecting one that is already in use is rejected, naming the agent that holds it.

npx zavudev agents list
npx zavudev agents senders connect --agent <agentId> --sender <senderId>

An agent can also exist with no sender at all while you build it. It will not receive anything until you connect one and enable it.

Addressing an agent

Everything that hangs off an agent (its tools, flows and knowledge bases) is reachable two ways:

/v1/senders/{senderId}/agent/tools     through the sender that answers with it
/v1/agents/{agentId}/tools             through the agent itself

They are the same resource. Use the second when the agent has no sender yet, which is the state POST /v1/agents creates and the one you assemble an agent in. The first is convenient when you are already holding a sender id.

# Build an agent before it answers anywhere
AGENT=$(curl -s -X POST https://api.zavu.dev/v1/agents \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -d '{"name":"Ada","provider":"zavu","model":"openai/gpt-4o-mini","systemPrompt":"..."}' \
  | jq -r .agent.id)

curl -X POST https://api.zavu.dev/v1/agents/$AGENT/tools -d '{...}'
curl -X POST https://api.zavu.dev/v1/agents/$AGENT/knowledge-bases -d '{...}'

# Then connect a sender and enable it
curl -X POST https://api.zavu.dev/v1/agents/$AGENT/senders -d "{\"senderId\":\"$SENDER_ID\"}"
curl -X PATCH https://api.zavu.dev/v1/agents/$AGENT -d '{"enabled":true}'

Where to go next

Functions quickstart

Write and deploy your first agent in code.

Factory agents

Start from a production agent instead of a blank file.

Voice agents

Answer and place phone calls.

Agent setup

Create and configure an agent without writing code.

Getting Started

Build agents

Send & receive

Operate

Developer tools

How agents work

The pieces

What a deploy actually does

A message arrives

A call arrives

Where tools run

What you can verify, and when

Agents and senders

Addressing an agent

Where to go next

Functions quickstart

Factory agents

Voice agents

Agent setup

​The pieces

​What a deploy actually does

​A message arrives

​A call arrives

​Where tools run

​What you can verify, and when

​Agents and senders

​Addressing an agent

​Where to go next

Functions quickstart

Factory agents

Voice agents

Agent setup

The pieces

What a deploy actually does

A message arrives

A call arrives

Where tools run

What you can verify, and when

Agents and senders

Addressing an agent

Where to go next