Quickstart
We’ll build a restaurant booking agent that lives on a WhatsApp sender. By the end, customers can text the number and the agent will show the menu, check availability, and confirm reservations.You’ll need an active WhatsApp sender in your Zavu project. If you don’t
have one yet, connect WhatsApp first.
1. Install the CLI
npx zavudev@latest resolves the newest release every time, so there is nothing
to upgrade. If you installed globally, update with npm install -g zavudev@latest.
The Homebrew tap is deprecated and no longer updated. If you installed with
brew install zavudev/tools/zavu, remove it and use one of the methods above:2. Log in
~/.zavu/credentials.json (chmod 0600).
Confirm you’re on the right project:
3. Find your sender
4. Scaffold the function
index.ts like this (truncated):
5. Set the sender ID as a secret
6. Deploy
How the sender → function link works
You didn’t runnpx zavudev fn triggers add anywhere — and yet, the sender knows to
forward every inbound to your function. Here’s the wiring:
defineAgent({ senderId, ... })registers your agent on that sender. Whennpx zavudev deploysyncs the manifest, Zavu writes a row that says “sender$SENDER_IDhas an active agent backed by functionreservations.”- Every inbound message to that sender automatically hands off to the agent,
which runs your tools (
view_menu,check_availability, etc.) inside the function. - You can verify the link any time:
No See the Triggers guide for the full event
list and cartesian-binding patterns (multiple events × multiple senders).
defineAgent? You need triggers. If you want a function to react to
sender events without an LLM agent — say, a webhook that logs every
delivery, or a custom non-LLM responder — declare it with defineFunction
and bind it explicitly:7. Try it on WhatsApp
From your phone (not the sender’s number), send the sender:hola, qué tienen vegano?Expected flow:
8. Watch it run
In three terminals:9. Iterate
Editindex.ts — say, add a cancel_reservation tool — and redeploy:
description and
parameters schema directly.
Common pitfalls
The agent doesn't respond on WhatsApp
The agent doesn't respond on WhatsApp
Run
npx zavudev agents get --sender "$SENDER_ID" and confirm enabled: true.
If false, check that defineAgent is being called (deploy must show
Agents synced: + Bella).Tools never get called
Tools never get called
Check that the tool
description is specific enough. The LLM uses the
description to decide when to call the tool, so vague descriptions
("do stuff") don’t trigger. Rewrite each description as the answer to
“when should the model call this?”.Also confirm npx zavudev agents tools list --sender "$SENDER_ID" shows the 4
tools with enabled: true.A tool errors out
A tool errors out
Watch
npx zavudev fn logs --tail while you trigger the tool. The error stack
appears live. Common causes: missing env var (run
npx zavudev fn secrets list to confirm what’s set), JSON parse errors on
response, unhandled async exceptions.My slug is too long error
My slug is too long error
Function names cap at 64 chars internally, and we prefix yours with
zavu-fn-<projectId>- (41 chars used). Slugs over 23 chars get rejected
server-side with a clear message. Pick something short — bella, not
restaurant-reservations-agent-v2.I'm using defineFunction (no agent) and nothing fires
I'm using defineFunction (no agent) and nothing fires
Pure
defineFunction handlers don’t get traffic automatically — they
need an explicit trigger. Run:defineAgent is the only declarative shortcut that auto-binds — every
other event flow goes through triggers. See Triggers.Next steps
Define agents in depth
Providers, models, prompts, triggers.
Define tools in depth
Schemas, handlers, returning structured data.
Customer support example
Knowledge base lookup + ticket creation.
Ecommerce example
Order status + smart recommendations.