# Quickstart — Deploy Your First Agent

> Pull a ready-made AI agent into your codebase, deploy it with one command, and have it answering a real channel in about ten minutes.

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

> **Info:**
> Prefer to send messages from your own backend instead of deploying code here?
> Start with the [messaging quickstart](https://www.zavu.dev/docs/quickstart-messaging).

## 1. Install the CLI

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

```sh
npm install -g zavudev
zavudev --version
```

```sh
# Download the binary for your platform from
# https://github.com/zavudev/zavu-cli/releases
# Then:
chmod +x ./zavu-macos-arm64
sudo mv ./zavu-macos-arm64 /usr/local/bin/zavudev
```

**Tip:**
Working with a coding agent? Install the
[skills](https://www.zavu.dev/docs/tools/coding-agent-skills) first and it will know every command on
this page, plus `defineAgent` and `defineTool`:

```sh
npx skills add zavudev/zavu-skills
```

## 2. Log in

```sh
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:

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

```sh
npx zavudev agents init
```

To see what you can start from first:

```sh
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**

    ```sh
    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**

    ```sh
    npx zavudev fn init
    ```

    Gives you a bare `index.ts` to write `defineAgent` yourself. The
    [Functions quickstart](https://www.zavu.dev/docs/guides/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:

    ```sh
    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](https://www.zavu.dev/docs/guides/senders/adding-channels).
    `npx zavudev agents init --buy-number` buys a number and creates the
    sender for you instead.
  

## 4. Install dependencies

```sh
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.)

```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 }
  },
})
```

> **Tip:**
> `provider: "zavu"` is our managed AI gateway. No API key of your own required;
> model usage is billed from your Zavu balance. Bring your own key by setting
> `provider` to `openai`, `anthropic`, `google` or `mistral`.

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

```sh
npx zavudev fn secrets set CALENDAR_WEBHOOK_URL "https://..."
```

## 6. Try a tool without deploying

```sh
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

```sh
npx zavudev deploy
```

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

> **Warning:**
> Read the lines **above** the checkmark. Deploy prints its warnings before the
> success line, and 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.

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:

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

> **Note:**
> By default a dry run does not execute tools: it reports which tool the agent
> chose, with its arguments, and stops. Add `--execute-tools` to run them and get
> the full reply; your handlers then run for real. Live conversations on every
> channel call them. A dry run is billed like a live reply.

## 9. Watch it run

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

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

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

## Next steps

  - [How agents work](https://www.zavu.dev/docs/concepts/agent-architecture): What a deploy actually does, and what happens when a message arrives
  - [Defining agents](https://www.zavu.dev/docs/guides/functions/defining-agents): Every field of `defineAgent`, including voice
  - [Defining tools](https://www.zavu.dev/docs/guides/functions/defining-tools): Give the agent access to your systems
  - [Knowledge bases](https://www.zavu.dev/docs/guides/ai-agents/knowledge-base): Ground the answers in your own documents
  - [Voice agents](https://www.zavu.dev/docs/guides/voice-agents/overview): Answer and place phone calls with the same agent
  - [Bring your framework](https://www.zavu.dev/docs/guides/frameworks/overview): Deploy an eve project without restructuring it