Zavu | Zavu Docs

The native layout

A Zavu project is a single entry file that declares what it is. Nothing is registered by convention or discovered by scanning folders: defineAgent and defineTool run at module load, the deploy reads the declarations, and the live agent is reconciled to match.

Code
my-agent/
  index.ts        <- required. This is what identifies the project.
  package.json    <- optional. Its dependencies are installed for you.

index.ts at the root is the whole detection rule. If it is there, Zavu treats the repository as a native project.

A minimal project

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

defineAgent({
  senderId: process.env.SENDER_ID!,
  name: "Support",
  provider: "zavu",
  model: "openai/gpt-5.6-luna",
  prompt: `You are a support agent.

When someone asks about an order, call get_order_status and answer with what it
returns. Never invent a status or a date.`,
})

defineTool({
  name: "get_order_status",
  description:
    "Look up the delivery status of one order by its id. Call this whenever a customer asks where their order is.",
  parameters: {
    type: "object",
    properties: { orderId: { type: "string" } },
    required: ["orderId"],
  },
  handler: async (args) => ({ orderId: args.orderId, status: "in_transit" }),
})

npx zavudev fn init scaffolds exactly this.

What each part does

defineAgent is the agent's configuration: model, prompt, channels, and optionally a voice block. Read SENDER_ID from the environment rather than hard-coding a sender, so the same repository can be deployed against a different sender without an edit. An agent declared without one is created anyway; attach a sender afterwards from its page and the attachment survives every redeploy.

defineTool is a capability the model can call, with parameters as plain JSON Schema. The handler runs inside your function. Tools are offered on every channel, including plain text, and the model may chain up to five tool rounds in a single reply.

defineFunction is separate, and optional. It handles raw events and HTTP requests, and it is what an event trigger invokes. A project that declares only an agent and its tools has no handler, so a trigger on it wakes the function and runs nothing — the agent replies on its own, because it is attached to a sender.

Deploying


npx zavudev deploy

Both paths run the same pipeline. See Deploy from GitHub for the push-based one, and Frameworks for the other layouts Zavu accepts.