# Write agents as code and publish them with the CLI
URL: https://samva.dev/changelog/write-agents-as-code
> samva 0.47 and CLI 0.41 let you write hosted agents in TypeScript, handle mailbox and contact events, and publish versions. Agent modules replace extensions.
- Published: 2026-11-18
- Tags: sdk, cli, api

A hosted agent can now be a TypeScript project. You write its instructions, skills, tools, and event
handlers; Samva runs the conversation, holds what your rules say a person must approve, and answers
on email and WhatsApp. Upgrade `samva` to 0.47.0 and `@samva/cli` to 0.41.0.

**What you need to do**

**Breaking: extensions are replaced by agent modules.** `defineExtension`, the `samva/mailbox`,
`samva/mailbox/test`, and `samva/mailbox/webhook` exports, the `extensions` and
`extensionInstallations` SDK services and REST endpoints, and the `samva extensions` commands are
removed. Extensions you published no longer run and are not converted. Move each one to
`defineAgent` from `samva/agent`, with its handlers under `events`, and publish it to an agent:

| Before                                   | Now                                                   |
| ---------------------------------------- | ----------------------------------------------------- |
| `defineExtension` from `samva/mailbox`   | `defineAgent` from `samva/agent`, handlers in `events` |
| `runExtension`, `mailboxEvent` in tests  | `runAgent`, `createTestClient` from `samva/agent/test` |
| `samva extensions` commands              | `samva agents init`, `info`, `build`, `publish`       |
| Extension installation on a mailbox      | The mailbox endpoints in the agent's `endpointIds`    |

For code that runs on your own server, subscribe an ordinary [webhook](/docs/platform/webhooks)
to mailbox events instead.

**What you can do**

- **Scaffold and publish from the CLI.** `samva agents init` creates a project with an `agent.ts`
  entry, `samva agents info` lists what it registers and reports problems before you publish, and
  `samva agents publish <agentId> --dir .` bundles it and publishes the agent's next immutable
  version. Publishing identical code changes nothing.

```bash title="Create and publish an agent project"
samva agents init ./support --name "Support"
cd support && bun install
samva agents info .
samva agents publish "$AGENT_ID" --dir .
```

- **Give it tools.** `defineTool` declares an input as an Effect schema, which Samva checks before
  your code runs, whether a repeated call is safe, and an optional approval floor. The agent's
  [rules](/docs/mailboxes/approvals#configure-decision-rules) still apply, and the stricter one wins.
- **Handle mailbox and contact events.** Register a [mailbox event](/docs/mailboxes/events) such as
  `mailbox.message.received`, or a custom [contact event](/docs/events), under `events`. Each
  handler gets the event and a `ctx` scoped to it, and a failed handler retries with the same event
  id. A `mailbox.message.received` handler takes over that message: Samva does not also start an
  automatic reply, so reply from the handler or leave the event out to keep automatic replies.

```ts title="agent.ts"
import { defineAgent } from "samva/agent";

export default defineAgent({
  manifest: {
    name: "Acknowledger",
    version: "1.0.0",
    endpointIds: ["mbe_..."],
    integrations: [],
    eventTriggers: [],
    policy: { presets: [], rules: [] },
    model: "standard",
    reasoning: "auto",
    workingHours: null,
    takeoverTimeoutMinutes: 30,
  },
  instructions: "Acknowledge new mail.",
  events: {
    "mailbox.message.received": async (event, ctx) => {
      ctx.log("received", event.id);
    },
    "trial.started": async (event, ctx) => {
      ctx.log("trial started for", event.data);
    },
  },
});
```

- **Test without a server.** `defineEval` and `runAgent` from `samva/agent/test` run a tool or
  handler against a fake `ctx`, with input validation kept.
- **Keep the dashboard in step.** A published code version shows in the dashboard with its model
  and rules. Saving a change to the agent's settings in the dashboard rebuilds the draft from those
  settings, so publish code-defined behavior from the CLI.

The [onboarding agent example](https://github.com/SamvaHQ/samva/tree/main/examples/onboarding-agent)
is a complete module that walks a WhatsApp contact through connecting their account. See
[write an agent as code](/docs/agents#write-an-agent-as-code) for limits and the full `ctx`.

## Links

- [Write an agent as code](/docs/agents#write-an-agent-as-code)
- [Event handlers](/docs/agents#event-handlers)
- [Mailbox events](/docs/mailboxes/events)
- [samva 0.47.0 release notes](https://github.com/SamvaHQ/samva-typescript/releases/tag/samva%400.47.0)
- [@samva/cli 0.41.0 downloads](https://github.com/SamvaHQ/samva-cli/releases/tag/v0.41.0)

## Related

- [Give agent modules state, Workflows, and schedules](/changelog/give-agent-modules-state-and-schedules)
- [Check inbound mail disposition before processing](/changelog/check-inbound-disposition-before-processing)
- [All changelog entries](/changelog)
