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 to mailbox events instead.
What you can do
- Scaffold and publish from the CLI.
samva agents initcreates a project with anagent.tsentry,samva agents infolists what it registers and reports problems before you publish, andsamva 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.
defineTooldeclares 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, underevents. Each handler gets the event and actxscoped to it, and a failed handler retries with the same event id. Amailbox.message.receivedhandler 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.
defineEvalandrunAgentfromsamva/agent/testrun a tool or handler against a fakectx, 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.