# Zavu Functions

> Deploy serverless code that powers your agents — no infra to manage, just `npx zavudev deploy`.

## Zavu Functions

Zavu Functions let you run TypeScript in our cloud and wire it directly to your
WhatsApp/SMS/Email senders. You write the code locally, run `npx zavudev deploy`, and
seconds later your agent is live with tools backed by real business logic.

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

defineAgent({
  senderId: process.env.SENDER_ID!,
  name: "Bella",
  provider: "zavu",
  model: "openai/gpt-5.6-luna",
  prompt: "Eres Bella, anfitriona de la Pizzeria. Sé breve.",
  channels: ["whatsapp"],
})

defineTool({
  name: "check_availability",
  description: "Get free reservation slots for a date and party size.",
  parameters: {
    type: "object",
    properties: {
      date: { type: "string" },
      partySize: { type: "number" },
    },
    required: ["date", "partySize"],
  },
  handler: async ({ date, partySize }) => {
    // your real booking logic — DB, POS, external API, whatever
    return { available: true, slots: ["19:00", "21:00"] }
  },
})
```

That's the entire integration. One file. `npx zavudev deploy`. Done.

## When to use Functions

  - **AI agent with real actions**: Customer asks something, the LLM decides which tool to call, your code runs, real data goes back as the answer.
  - **Custom webhooks**: Receive inbound from Stripe, GitHub, your own systems, then forward as a WhatsApp message.
  - **Scheduled jobs**: Daily report digests, reminder broadcasts, cleanup tasks.
  - **Event-driven automation**: React to `message.inbound`, `broadcast.status_changed`, etc. with custom logic without managing webhook receivers yourself.

## How it relates to AI Agents

Zavu has two complementary ways to build agents:

| You want | Use |
|---|---|
| A no-code agent configured from the dashboard | [AI Agents](https://www.zavu.dev/docs/guides/ai-agents/overview) |
| An agent with custom business logic in your own code | **Zavu Functions** (this guide) |
| Both — start no-code, evolve to code | Start with AI Agents, migrate when you need tools or custom flows |

Functions can *fully manage* an AI Agent: the `defineAgent` call creates and
keeps the agent config in sync with your code. Once your function declares
`defineAgent`, the agent is "managed by the function" — the dashboard surfaces
this and disables manual edits to prevent drift.

## Mental model

```
+----------------+        +--------------------+        +-----------+
| WhatsApp user  | -----> | Zavu sender (WABA) | -----> | AI Agent  |
+----------------+        +--------------------+        +-----------+
                                                              |
                                                       (tool call)
                                                              v
                                            +-------------------------------+
                                            | Your Zavu Function            |
                                            |  defineTool(handler)          |
                                            +-------------------------------+
                                                              |
                                                       (return result)
                                                              v
                                                       Agent answers user
```

- **Fully managed runtime.** Each function runs in Zavu's serverless cloud. No
  consoles to log into — `npx zavudev deploy` handles bundling, dependencies, and
  publishing.
- **Internal invocation.** When the agent calls a tool, we use signed
  internal invocations — your function is **not** publicly exposed. No HTTP,
  no HMAC secrets to rotate, no DDoS surface.
- **Native event binding.** Functions can also subscribe to Zavu events
  (`message.inbound`, `broadcast.status_changed`, etc) via triggers.
- **Auto-provisioned credentials.** Every function gets a scoped `ZAVU_API_KEY`
  in its environment so it can call our SDK without you handling key
  distribution.

## Quick tour

**Tip:**
Want your AI coding agent (Claude Code, Cursor, Copilot…) to write the
function for you? Install [Zavu's Coding Agent Skills](https://www.zavu.dev/docs/tools/coding-agent-skills) —
the `functions` skill teaches it `defineAgent`, `defineTool`, `npx zavudev deploy`,
and the full debug flow.

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

  
#### Install the CLI

    ```sh
    npx zavudev@latest --version
    # or install it globally: npm install -g zavudev
    # or grab a standalone binary from
    # https://github.com/zavudev/zavu-cli/releases
    ```
  
  
#### Login (one time)

    ```sh
    npx zavudev login
    ```
    Opens your browser, lets you pick a project. The API key is saved to
    `~/.zavu/credentials.json` and used by every later command.
  
  
#### Scaffold a function

    ```sh
    npx zavudev fn init --template restaurant-booking -y
    cd reservations
    ```
    Creates `index.ts` with `defineAgent` + `defineTool` boilerplate.
  
  
#### Set secrets

    ```sh
    npx zavudev fn secrets set SENDER_ID jn76vnxet8g5nq661by3v06y1581bmmn
    ```
    The agent will run on this WhatsApp sender. Get the ID from
    `npx zavudev senders list`.
  
  
#### Deploy

    ```sh
    npx zavudev deploy
    ```
    Bundle, upload, agent + tools synced to your sender.
  
  
#### Try it

    Send a WhatsApp to the sender's number. The agent answers, calls your
    tool handlers, returns real data.
  

## Continue

  - [Quickstart](https://www.zavu.dev/docs/guides/functions/quickstart): Full step-by-step from zero to live agent in 10 minutes.
  - [CLI reference](https://www.zavu.dev/docs/guides/functions/cli): Every `zavu` command, flag by flag.
  - [Define an agent](https://www.zavu.dev/docs/guides/functions/defining-agents): `defineAgent` API, providers, prompts, models.
  - [Define tools](https://www.zavu.dev/docs/guides/functions/defining-tools): `defineTool` API, schemas, handlers, error handling.
  - [Secrets](https://www.zavu.dev/docs/guides/functions/secrets): Environment variables encrypted at rest.
  - [Triggers](https://www.zavu.dev/docs/guides/functions/triggers): Listen to Zavu events from your function.
  - [Runtime versions](https://www.zavu.dev/docs/guides/functions/runtime): How pinning works, when to upgrade.
  - [Examples](https://www.zavu.dev/docs/guides/functions/examples/restaurant): Complete restaurant booking agent, walked through.