SDK guides

Deploy an employee

An employee starts with a small folder that describes its role, instructions, access, schedule, and limits. This guide previews an example, tries it safely, and then deploys it. Every step that spends money or changes a live employee requires an explicit opt-in.

Step 1

Start from an employee bundle

Each SDK ships self-contained example employees under examples/employees, such as chief-financial-officer, research-analyst, launch-operations-coordinator, and site-reliability-engineer. A bundle is a directory with an employee.json manifest and a set of instruction files. Together they define what the employee is responsible for, what information it can use, which actions require review, when it runs, and when it must stop.

Choose the access model before deployment. A read-only employee can investigate and prepare work but cannot make changes. An employee with protected actions can do the same research without interruption, then pause when it is ready to make a specific change. For example, the Research Analyst asks before publishing a finished report, and the Site Reliability Engineer asks before posting a coordination update.

Step 2

Preview the deployment offline

The example runner supports preview, test, and deploy. Preview is the safe default: it checks the employee folder and shows the resulting configuration without connecting to Seren or requiring a credential.

Preview an employee bundle (TypeScript)

pnpm add @serendb/sdk

# From the SDK examples, preview the built deployment spec - no key needed
node dist/employee-lifecycle.js preview research-analyst

The preview is exactly what a test or deployment would use. Review the schedule, available information and actions, approval rules, and limits before moving on.

Step 3

Run a draft test

A draft test runs the employee without creating a live deployment and returns the result. It is a paid call, so it requires both a Seren API key and an explicit opt-in.

Test the draft (requires opt-in)

export SEREN_API_KEY=your_seren_api_key
export SEREN_EXAMPLE_ALLOW_PAID=1

node dist/employee-lifecycle.js test research-analyst "Summarize this week's launch risks"

Without SEREN_API_KEY and SEREN_EXAMPLE_ALLOW_PAID=1, the runner stops before making the request.

Step 4

Deploy the employee

Deploying creates or updates a live employee. It adds a second opt-in on top of the paid gate so the change is always deliberate. The employee folder decides whether the employee is always available, runs on a schedule, or completes a one-time job.

Deploy the employee (requires both opt-ins)

export SEREN_API_KEY=your_seren_api_key
export SEREN_EXAMPLE_ALLOW_PAID=1
export SEREN_EXAMPLE_ALLOW_DEPLOY=1

node dist/employee-lifecycle.js deploy research-analyst

The Python and Rust SDK examples use the same three steps and the same opt-ins, so teams can follow one deployment process in any supported language.

Watch it run

Once an employee is live, follow its health, activity, usage, and pending reviews from a dashboard that cannot change its work.

Build a dashboard Open the API reference