Skip to content
  • sdk
  • cli
  • api

Write agents as code and publish them with the CLI

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.

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:

BeforeNow
defineExtension from samva/mailboxdefineAgent from samva/agent, handlers in events
runExtension, mailboxEvent in testsrunAgent, createTestClient from samva/agent/test
samva extensions commandssamva agents init, info, build, publish
Extension installation on a mailboxThe mailbox endpoints in the agent's endpointIds

For code that runs on your own server, subscribe an ordinary webhook 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.
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 still apply, and the stricter one wins.
  • Handle mailbox and contact events. Register a mailbox event such as mailbox.message.received, or a custom contact event, 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.
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 is a complete module that walks a WhatsApp contact through connecting their account. See write an agent as code for limits and the full ctx.

Links

Related

All changelog entries