Quickstart — Deploy Your First Agent

By the end of this page an agent you own, as editable TypeScript, is answering messages on one of your channels.

1. Install the CLI


# No install step. Always runs the current version.
npx zavudev@latest --version

2. Log in

terminal
npx zavudev login

Your browser opens, you sign in, pick the project this agent will live in, and authorize. The CLI stores the key in ~/.zavu/credentials.json with mode 0600.

Confirm which project you are pointed at:

terminal
npx zavudev whoami

3. Scaffold an agent

agents init is the guided path. It picks a factory agent, finds or creates the sender it runs on, writes the files, and registers the function.

terminal
npx zavudev agents init

To see what you can start from first:

terminal
npx zavudev agents catalog

Seven factory agents ship today, across sales, support and front desk. Some are voice agents that answer the phone; all of them also run on text channels.

Pull a specific agent

terminal
npx zavudev agents pull fermi --sender <senderId>

Scaffolds into ./fermi, registers the function, and sets the SENDER_ID secret from the sender you passed. Use --dir to scaffold elsewhere.

Start from an empty function instead

terminal
npx zavudev fn init

Gives you a bare index.ts to write defineAgent yourself. The Functions quickstart walks that path in full.

I have no sender yet

An agent answers on a sender, and a sender needs at least one channel. The fastest channel to turn on needs no phone number and no external account:

terminal
npx zavudev senders create --data '{"name":"Agent","enableSmsOneway":true}'

Recipients cannot reply on one-way SMS, so use it to verify the deploy works, then add a real channel. npx zavudev agents init --buy-number buys a number and creates the sender for you instead.

4. Install dependencies

terminal
cd fermi
npm install

Deploy works without this, but every local check does not: fn invoke, tsc --noEmit, and your editor all need the dev dependencies installed.

5. Look at what you got

The scaffold is one file, and it is the whole agent. (You can split it up later — imports between your files are resolved on deploy.)

index.ts
import { defineAgent, defineTool } from "@zavudev/functions"

defineAgent({
  senderId: process.env.SENDER_ID!,
  name: "Fermi",
  provider: "zavu",
  model: "openai/gpt-4o-mini",
  prompt: "You are Fermi, a qualification agent...",
  channels: ["voice", "whatsapp"],
})

defineTool({
  name: "lookup_account",
  description: "Find an existing account by phone number.",
  parameters: {
    type: "object",
    properties: { phone: { type: "string" } },
    required: ["phone"],
  },
  handler: async ({ phone }) => {
    // replace with your real lookup
    return { found: false }
  },
})

Any secret the agent needs beyond SENDER_ID is listed by agents pull when it finishes. Set each one before deploying:

terminal
npx zavudev fn secrets set CALENDAR_WEBHOOK_URL "https://..."

6. Try a tool without deploying

terminal
npx zavudev fn invoke --tool lookup_account --args '{"phone":"+14155551234"}'

This runs the handler on your machine, with no cloud round-trip and nothing charged. Use it to get the business logic right before anyone can talk to the agent.

7. Deploy

terminal
npx zavudev deploy

Code
› status: bundling
› status: uploading
› status: publishing
› status: active
✓ Deployed in 14s
  Agents synced:
    + Fermi
  Tools synced:
    + lookup_account

Your code is now the source of truth. Every deploy reconciles the live agent to match the file, so a defineAgent you delete deletes the agent.

8. Talk to it

Message the sender's number from your phone, or call it if the agent has voice enabled. To check the reply without touching a real channel:

terminal
npx zavudev agents test --sender "$SENDER_ID" --message "what do you do?"

9. Watch it run

terminal
# What the agent did: tools called, tokens, cost, latency
npx zavudev agents executions --sender "$SENDER_ID"

terminal
# Your handlers' console output, live
npx zavudev fn logs --tail

terminal
# Every message in and out
npx zavudev messages list --limit 10

Next steps

How agents work

What a deploy actually does, and what happens when a message arrives

Defining agents

Every field of defineAgent, including voice

Defining tools

Give the agent access to your systems

Knowledge bases

Ground the answers in your own documents

Voice agents

Answer and place phone calls with the same agent

Bring your framework

Deploy an eve project without restructuring it