Crate serve 

serve (experimental)

An agent framework in the style of Topcoat, with hosting modelled on eve, built on the everruns runtime. It is part of the Everruns ecosystem.

Experimental. serve is a proof of concept. Every API here may change or disappear; it is published as everruns-serve but not covered by the everruns stability policy.

use serve::prelude::*;

/// Rolls dice for board-game nights.
#[agent]
fn assistant() -> Agent {
    Agent::builder()
        .model("anthropic/claude-sonnet-5")
        .instructions("Roll dice when asked.")
        .build()
}

/// Roll one die with the given number of sides.
#[tool]
async fn roll_dice(cx: &Cx, sides: u32) -> Result<u32> {
    cx.progress(format!("rolling a d{sides}")).await;
    Ok(sides)
}

#[tokio::main]
async fn main() -> serve::Result {
    serve::start(App::builder().discover().build()).await
}

A real app also calls serve::assets!() once and embeds agent/** with serve_build::embed() in build.rs, so prompts and skills can live in Markdown files (see md!).

The pieces:

• Attribute macros (agent, tool, channel, schedule, connection, eval) register items at link time.
• App::builder().discover() collects them, validates the file-layout conventions, and resolves agent/** assets embedded by serve-build.
• Manifest is what the build declares and the host provides: schedules, channel routes, secrets, the sandbox, model strings.
• Cx is the one context type: the tool call (session, turn, call id, progress), connections, secrets, starting sessions.
• start runs the binary as dev, start, manifest, eval or deploy, serving everywhere the same /v1 wire API, a subset of the everruns server’s session API (so the everruns SDK can drive it).

Modules

prelude

Everything an application file usually imports.

sim

Simulated models for running agents offline, re-exported from everruns.

Macros

assets

Include the assets serve_build::embed() generated for this crate.

md

Embed a Markdown file from this crate’s agent/ directory.

Structs

Agent

An agent of this app. Build one with Agent::builder inside an #[agent] function.

AgentBuilder

Builder for Agent.

App

A discovered, validated app. Cheap to clone.

AppBuilder

Builder for App.

AppConfig

Parsed serve.toml.

Cx

The context of one tool call (inside tools) or of the app (in schedules).

DeliveryTarget

Where a session’s replies go: a channel and a target on it.

EvalCx

The eval’s handle on one session.

EvalReport

Outcome of an eval run.

EvalResult

Inbound

An inbound webhook request.

Manifest

The host contract. Serialize with serde_json.

Markdown

A Markdown file from agent/, embedded at build time. Create with md!.

McpServer

An MCP server connection, attached to every agent.

Secret

A secret provided by the host as an environment variable.

Server

A booted serve host, for a hosting target to wrap.

ServerBuilder

Builder for Server.

Slack

Slack via the Events API: app_mention (and, unless mention-only, direct messages) in; chat.postMessage out, threaded.

StartSession

A session being started from code. Configure, then .await.

TurnCheck

Assertions on a completed turn. Each returns Result<Self> so they chain with ?.

TurnRecord

One finished turn, as the eval saw it.

Webhook

A generic JSON webhook: {"thread": "...", "text": "..."} in, replies printed (or POSTed to callback, when the request carries one).

Enums

ChannelEvent

What a webhook means.

Instructions

Where an agent’s always-on prompt comes from.

Mode

How the binary is running. Decides hot reload and model fallback.

OnApproval

What to do when a tool asks for approval during an eval.

SandboxKind

Where the agent’s shell and files run. The code never changes between kinds; the host (or dev) supplies the adapter.

Traits

Channel

A conversation surface.

Functions

data_dir

Where dev and start persist: the SQLite path in DATABASE_URL, else SERVE_DATA_DIR, else .serve/.

start

Run the app according to the command line. See the module docs.

Type Aliases

Error

The error type used across serve. Anything std::error::Error converts into it with ?.

MicroVm

What a hosting target supplies for [sandbox] kind = "microvm": it adds the shell and filesystem to each agent as it is built. Without one, microvm falls back to bashkit.

Result

Result with serve’s Error. -> Result alone means Result<()>.

Attribute Macros

agent

Register a function returning serve::Agent as an agent of this app.

channel

Register a function returning a serve::Channel implementation. Its inbound webhook is served at POST /v1/channels/{name}. A companion module with the same name is generated so a schedule can address the channel: slack::channel("C0123ABC").

connection

Register a function whose return value is a connection. Tools read it with cx.connection::<T>(); a serve::McpServer is also attached to every agent as an MCP server. Credentials stay in the connection, never in the model context. Returning Result<T> makes a failure a discovery error.

eval

Register an async function (t: &mut EvalCx) -> Result as an eval. Evals run in-process with cargo run -- eval, or against a deployed URL with cargo run -- eval --against <url>.

schedule

Register an async function (cx: &Cx) -> Result to run on a cron schedule. Five-field cron ("0 9 * * MON") is accepted; a six- or seven-field expression with seconds is passed through.

tool

Register an async function as a tool. The function name is the tool name, the doc comment is its description, and the remaining parameters become the tool’s JSON arguments. An optional first parameter cx: &Cx receives the per-session context.