This is the full developer documentation for Everruns
---
# Everruns Documentation
> Tutorials, how-to guides, reference, and explanation for building and operating Everruns agents.
Source:
```
## Development modes
The same binaries collapse into smaller deployments for local work:
* **`DEV_MODE=true` (single process).** Nothing to install or run beside the binary: the server starts a temporary PostgreSQL of its own and deletes it on exit. Execution runs in-process inside the server binary; the gRPC server is disabled. Data is lost on restart. Useful for UI iteration and API development.
* **`just start-all` (full local).** Brings up PostgreSQL, Valkey, and NATS as local processes (no Docker required) and starts the server + worker against them. Mirrors production wiring on a single machine.
* **Docker Compose.** The production-shaped topology in one machine; see [Docker Compose](https://everruns.com/docs/getting-started/docker-compose/).
## Multi-instance deployment
Multiple control-plane instances can run behind a load balancer with no session affinity:
| Concern | How it stays correct |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Database connections | `EXPECTED_INSTANCES=N` divides the pool so `pool × instances ≤ 80% of PG_MAX_CONNECTIONS` |
| SSE delivery | `LISTEN/NOTIFY` or NATS subjects fan out to every instance; reconnects are idempotent |
| Turn and task claiming | `SKIP LOCKED` on session leases and the durable task queue partitions work naturally; a session’s fenced lease keeps one worker on it |
| Migrations | PostgreSQL advisory lock prevents concurrent runs |
| Rate limits | Valkey-backed sliding-window counters are shared; in-memory falls back to per-instance |
Workers do not require coordination, add as many as you need, in as many regions as you need, as long as they can reach the control-plane gRPC port.
## Further reading
* [Architecture (Getting Started)](https://everruns.com/docs/explanation/architecture/), the logical model
* [Environment Variables](https://everruns.com/docs/sre/environment-variables/), every knob and its default
* [Network Access Control](https://everruns.com/docs/advanced/network-access/), per-agent and per-org outbound rules
* [Docker Compose](https://everruns.com/docs/getting-started/docker-compose/), a production-shaped local setup
* [Custom backends](https://everruns.com/docs/framework/custom-backends/), low-level execution-host composition
---
# Tool Output Pipeline
> How Everruns processes tool results from execution to the model, verbosity budgets, distillation, persistence, hard limits, and where the full output lives
Source: /outputs/
│ • Persist Output (exec tools → VFS) {tool_call_id}.stdout
│ • Output Hard Limit (64 KiB ceiling) {tool_call_id}.stderr
▼ ▲
inline result → stored in the session, │
shown to the model next turn ──────────────────────┘
(read_file recovers the full original)
```
Two ideas run through the whole pipeline:
1. **Storage stays lossless.** Whatever the model sees inline, the full output is written to the session filesystem (the *destination*). The inline view always carries a pointer back to it.
2. **Each stage shrinks, none deletes.** Truncation, distillation, and masking only change the *view*. The agent can always `read_file` the persisted original.
## Stage 1: Verbosity budget (exec tools)
Exec and sandbox tools (`bash`, `*_exec`, sandboxed shells) clean their output (strip ANSI, collapse carriage returns) and apply a **verbosity budget** before returning. The mode is configurable per call; the default is `auto`:
* **Success (`exit_code == 0`)** → collapse to a compact summary (\~512 bytes), because the full log is persisted (Stage 3) and the agent rarely needs it inline.
* **Failure (non-zero exit)** → keep a larger diagnostic window (\~8 KiB) so the error stays debuggable in-loop.
The full pre-truncation output is stashed on the result as `raw_output` for the persistence hook to consume. Non-exec tools (MCP, web fetch, client tools) do **not** have a verbosity budget, that gap is what Stage 2 exists for.
## Stage 2: Tool Output Distillation (non-exec tools)
[Tool Output Distillation](https://everruns.com/docs/capabilities/) targets the tools Stage 1 doesn’t: **MCP tools and `web_fetch`**, whose results otherwise enter history verbatim. It runs as a capability hook, so it executes *before* the final hooks.
For a large non-exec result, distillation produces a compact, **content-aware** inline view:
| Output shape | What you get inline |
| ---------------- | ---------------------------------------------------------------------------- |
| Large JSON array | Schema-preserving sample: the first few rows + `[… N more items elided …]` |
| Long string | Head + tail window (both ends preserved), with a byte-elision marker |
| Unified diff | A diffstat-style summary: file + hunk headers and `+added / -removed` counts |
| Nested object | Each oversized field distilled; small fields untouched |
Before it replaces anything, distillation **persists the full original** to the session filesystem (same destination as Stage 3) and injects a recovery pointer. If persistence fails, or the session has no filesystem, it restores the verbatim output rather than leave a lossy result the agent can’t recover. **Reversibility is never sacrificed.**
Distillation is on by default in **Worker** and the harnesses built on it. Every transform is deterministic, so identical output distills identically and the model provider’s prompt cache keeps hitting across turns.
## Stage 3: Persistence and the hard limit
Two infrastructure hooks always run last, in order:
1. **Persist Output**: for tools that declare the `persist_output` hint (exec/sandbox), writes the full `raw_output` to the session VFS. When content is absent from the inline result, it adds a recovery pointer; complete inline results keep the retained file internal and do not invite a redundant read. It **skips** if a result already carries `output_files` (e.g. distillation already persisted it), so the two never double-write.
2. **Output Hard Limit**: a final, unremovable 64 KiB ceiling. By the time it runs, the result has usually already been budgeted or distilled, so it rarely fires; it’s a backstop against pathological cases.
## The destination, where full output lives
Everything the pipeline elides is recoverable from the **session filesystem**:
```plaintext
/outputs/{tool_call_id}.stdout ← full standard output
/outputs/{tool_call_id}.stderr ← full standard error (when present)
```
When the inline result omits persisted content, it carries the recovery pointer in `output_files` and `full_output`, plus a human-readable note telling the model to use `read_file` (with `offset`/`limit`) for the missing detail. Complete inline output has no model-facing pointer. Persisted streams are capped at 1 MiB each. Deleting the session cascades and removes them.
This is the key to aggressive shrinking: because the original is one `read_file` away, the inline view can be small without the agent losing the ability to drill in.
## How this relates to compaction
The pipeline above operates on **individual tool results at capture time**. [Context Compaction](https://everruns.com/docs/advanced/compaction/) operates **later**, across the whole conversation, when it approaches the context window, masking or summarizing older messages at serialization time.
They compose cleanly:
* The pipeline keeps each result lean as it’s produced.
* Compaction further masks older results when the *accumulated* history grows too large.
* [Infinity Context](https://everruns.com/docs/capabilities/) adds a `query_history` tool to retrieve older *messages* that scrolled out of the window.
Together: the pipeline controls per-result size, compaction controls total-history size, and both keep the full record recoverable.
## Summary
| Stage | Applies to | Effect | Destination of full output |
| ----------------- | -------------------------- | -------------------------------------------------------- | --------------------------------------------- |
| Verbosity budget | exec/sandbox | Compact summary on success, diagnostic window on failure | `raw_output` → persisted in Stage 3 |
| Distillation | MCP / web fetch / non-exec | Content-aware compact view | `/outputs/{id}.stdout` |
| Persist Output | `persist_output` tools | Lossless write + pointer | `/outputs/{id}.{stdout,stderr}` |
| Output Hard Limit | all | 64 KiB ceiling backstop | (already persisted) |
The agent always sees a lean view and can always recover the full original with `read_file`.
---
# Built-ins Overview
> Built-in harness types and capabilities that ship with Everruns. Harnesses define reusable behavior; Agent Sandbox Template bindings select compute.
Source: `; its ID and bindings stay intact. Clients using its old name should switch to its ID.
Conversation introductions and starters now belong exclusively to Agents. Existing harness presentation is copied to its assigned Agents when those Agent fields are empty. Harness presentation fields are deprecated and no longer accepted on writes.
---
# Sandbox Worker Harness
> Worker plus a full sandbox shell, for agents that need real processes, packages and builds.
Source: { ... }
// L180: fn validate(output: &Output) -> bool { ... }
// L220: struct Config { ... }
// L235: impl Config { ... }
// L236: fn load(path: &str) -> Result { ... }
// L270: fn merge(&mut self, other: &Config) { ... }
// L310: #[cfg(test)] mod tests { ... }
```
### Supported Languages
| Language | Extensions |
| ---------- | ----------------------------- |
| Rust | `.rs` |
| TypeScript | `.ts`, `.tsx`, `.mts` |
| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` |
| Python | `.py` |
### What Gets Outlined
* **Functions/methods** — name, parameters, return type
* **Structs/classes/enums** — name
* **Impl blocks / trait implementations** — with nested methods
* **Modules** — including `#[cfg(test)]` detection
* **Interfaces and type aliases** (TypeScript)
For unsupported languages, no outline is generated — the response still works, just without structural context for unread portions.
---
# Capabilities Overview
> Capabilities give an agent tools, system prompt fragments, and execution features. Index of every built-in capability.
Source: " }`. `target.external_agent_id` is a deprecated spelling of `id` |
| `mode` | No | `foreground` (default) or `background` |
| `wait_timeout_secs` | No | How long to wait for the remote task, 1 to 86400. Default 300 |
| `wake_on_completion` | No | Wake the session when a background run finishes. Default `true` |
| `result_schema` | No | JSON Schema for a required structured result from the external agent |
`message_schema` is not supported: a remote agent cannot call `report_task_progress`, so passing one fails. Text results are truncated to 8192 characters.
`foreground` waits for the remote task and returns its reply. `background` returns a `task_id` at once. When task tracking is available, each run is a session task of kind `external_agent`, so `wait_task` collects the result, `message_task` answers a remote task that asks for input, and `cancel_task` stops it.
## See also
* [A2A](https://everruns.com/docs/features/a2a/), serving agents over A2A and the delegation overview
* [Agent Handoff](https://everruns.com/docs/capabilities/agent-handoff/), delegation to first-party agents
* [Sub Agents](https://everruns.com/docs/capabilities/sub-agents/), the session task tools
---
# Agent Handoff
> Delegate work to configured first-party agents with spawn_agent, as a background task, a blocking call, or an invited participant in the current session.
Source: " }` |
| `mode` | No | `background`, `foreground`, or `invite` |
| `public_context` | No | Non-secret structured context, appended to the instructions |
| `result_schema` | No | JSON Schema for the child’s final result. The child must call `report_result` before the task can succeed |
| `message_schema` | No | JSON Schema for structured progress messages. The child gets `report_task_progress` |
### Modes
| Mode | Behavior |
| ------------ | -------------------------------------------------------------------------------------- |
| `background` | Default when session task tracking is available. Returns a `task_id` right away |
| `foreground` | Default otherwise. Blocks until the handoff finishes and returns the result |
| `invite` | Adds the target agent as a member of the current session instead of starting a new one |
A background handoff is tracked as a session task of kind `agent_handoff`, so the parent manages it with the session task tools (`list_tasks`, `get_task`, `message_task`, `cancel_task`, `wait_task`). Background mode fails when task tracking is not available.
Invite mode does not create a child task, so it rejects `result_schema` and `message_schema`. It also refuses the invite when the target’s configuration conflicts with the current session’s: the same capability with a different config, the same mounted file path with different contents, or the same MCP server name with a different definition.
### Connections
When a target lists `required_connections` and the session cannot resolve a connection for one of those providers, `spawn_agent` returns a `connection_required` result naming the provider. The client collects the credentials through the Connections flow. The system prompt tells the agent never to ask for tokens in chat or pass them in tool arguments.
## See also
* [A2A Agent Delegation](https://everruns.com/docs/capabilities/a2a-agent-delegation/), delegation to external agents
* [Sub Agents](https://everruns.com/docs/capabilities/sub-agents/), child sessions from the parent’s own configuration, and the session task tools
---
# AGENTS.md
> Project instructions resolved hierarchically from workspace files such as AGENTS.md and injected as the leading user message on every turn.
Source: ` tags, broadest scope first.
4. The block is injected as the leading user-role message: visible to the model, re-resolved every turn, and below system instructions in precedence.
Edits during a session apply on the next turn, with no restart. If a configured file doesn’t exist, the agent operates normally.
## Prompt order
Every turn the model sees, top to bottom:
1. **System prompt**: harness safety instructions, tool guidance, role (cache-stable).
2. **Conversation context**: the resolved `AGENTS.md` hierarchy, broadest scope first.
3. **Conversation history and the latest user message**.
Explicit user instructions win over project files on conflict; system instructions always win over both.
## Config
```json
{
"files": ["AGENTS.md", "CLAUDE.md"]
}
```
`files` is optional. When omitted, Everruns resolves `AGENTS.md` at every level from the root to the working directory. A config may list at most 16 files.
## Limits
* **32 KiB per file**. Longer content is truncated with a warning.
* **128 KiB total per turn**, which bounds hierarchy depth. Deeper files past the budget are omitted with an explicit note.
* At most 16 instruction files resolved per turn.
* Plain Markdown, no required sections.
## Notes
* Works with [File System](https://everruns.com/docs/capabilities/file-system/) tools, so an agent can update its own instructions.
* Missing configured files are ignored, with no error.
## Do something
* [Use AGENTS.md for project instructions](https://everruns.com/docs/how-to/use-agents-md/): full guide with examples.
* [Equip an agent with tools](https://everruns.com/docs/how-to/equip-agents-with-tools/): adding capabilities generally.
## See also
* [File System](https://everruns.com/docs/capabilities/file-system/): manage the AGENTS.md file.
* [Agent Skills](https://everruns.com/docs/capabilities/agent-skills/): another way to inject specialized instructions.
* [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# Agent Skills
> Discover and activate portable skill packages from the session workspace at runtime.
Source: --help`, and many also support ` --version`.
* Common builtins: `cd`, `ls`, `cat`, `echo`, `grep`, `head`, `tail`, `sed`, `find`, plus shell features like pipes, redirections, and command substitution. `grep` is backed by the session’s indexed search.
## See Also
* [Bashkit project](https://bashkit.sh), the interpreter powering this capability
* [File System](https://everruns.com/docs/capabilities/file-system/), file operations on the same workspace
* [Sub Agents](https://everruns.com/docs/capabilities/sub-agents/), background and parallel execution
* [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# Browser Use
> Let an agent work in a browser through the page structure, with element refs, form filling, and tabs, on any model.
Source: /`) |
### `daytona_git_credentials`
Configure git credentials in a sandbox so later `git push`, `pull`, and `fetch` commands run through `daytona_exec` authenticate.
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | -------------- |
| `sandbox_id` | string | yes | Target sandbox |
### `daytona_api_call` (opt-in)
Call any Daytona REST endpoint directly, for operations the dedicated tools do not cover. Only available when the capability config sets `enable_api_calling` to `true`. Authentication headers are injected automatically, and the Daytona OpenAPI spec is mounted at `/daytona/openapi.yaml`.
| Parameter | Type | Required | Description |
| --------- | --------------- | -------- | -------------------------------------------------------------------------------------- |
| `method` | string | yes | `GET`, `POST`, `PUT`, `PATCH`, or `DELETE` |
| `path` | string | yes | Management API path (`/sandbox/...`) or Toolbox API path (`/toolbox/{sandbox_id}/...`) |
| `body` | object or array | no | JSON request body |
## Config
```json
{
"enable_api_calling": true
}
```
`enable_api_calling` is the only setting, and it defaults to `false`.
## Git
* `daytona_git_clone` uses your connected GitHub account, so private repositories clone without extra setup. When no person is in the run, or the person has not connected GitHub, it uses the agent’s GitHub connection.
* For push, pull, or fetch, call `daytona_git_credentials` once after creating the sandbox, then run git commands with `daytona_exec`.
* Tokens written into the sandbox only reach repository contents: `daytona_git_clone`’s token covers the cloned repository alone, and `daytona_git_credentials` covers contents of every repository the connection reaches. Neither can open issues or review pull requests.
* Repository arguments accept `user/repo` shorthand instead of full URLs.
## Sandbox lifecycle
Sandboxes auto-stop after 5 minutes of inactivity by default as a safety net. Delete sandboxes when you are done: stopping only pauses a sandbox, and it stays visible in your Daytona dashboard.
All sandbox-scoped tools require a `sandbox_id`. The exceptions are `daytona_create_sandbox`, `daytona_list_sandboxes`, and `daytona_list_snapshots`.
## Security
* API keys are encrypted at rest (AES-256-GCM envelope encryption).
* Each sandbox is isolated from other sandboxes and the host.
* Git credentials are short-lived and scoped to the sandbox.
* Sandbox state is stored in encrypted session secrets.
## See also
* [Sandbox Templates](https://everruns.com/docs/features/sandbox-templates/#desktop): start the Session Sandbox with a desktop the agent drives with the `computer` tool.
* [Storage](https://everruns.com/docs/capabilities/session-storage/): API key and state persistence.
* [Daytona documentation](https://www.daytona.io/docs)
* [Integrations](https://everruns.com/docs/integrations/): every vendor integration.
* [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# Docker Container Sandbox
> Run agent commands and manage files in a Docker container tied to the session. Self-hosted alternative to cloud sandbox providers.
Source: ` (or `path`, which must stay inside `/workspace`) and leaves the head checked out at a detached HEAD, so `bash` can build, test and diff it:
```json
{
"repo": "acme/app",
"number": 42
}
```
It returns `path`, `head_sha`, `base_ref` and `base_sha`; `depth` (default 100) sets how much history is fetched. It needs the Managed Sandbox (`session_sandbox`) capability on a Sandbox Worker, and says so otherwise.
Checkout requires a GitHub App installation. The trusted resolver must supply installation-mint evidence that the token covers exactly this repository, grants only **Contents: read**, **Pull requests: read** and GitHub’s implicit **Metadata: read**, and expires within one hour. Missing evidence, personal OAuth tokens and `GITHUB_TOKEN` session-secret fallbacks are refused before any credential reaches the sandbox. This also fails closed with older control planes. For personal-token workflows, use `github_get_pull_request` and `github_get_pull_request_diff` to review on the trusted host, or connect an App installation for checkout.
The tool hands the admitted token with **Contents: read** and **Pull requests: read** for that one repository to a single `git fetch` through a temporary file it removes before returning, so the token is not in `.git/config`, in later `bash` commands, or in sandbox checkpoints. Plain `git fetch` in `bash` therefore works only for public repositories; call the tool again to refresh a checkout. Concurrent code in the sandbox can read the temporary file; the enforced repository, permission and expiry limits bound this accepted exposure.
### Reviews without repeats
Each inline comment from `submit_github_pull_request_review` starts with a hidden `` line. Pass a short, stable `key` per finding (such as `null-deref-parse-config`); a key the agent already posted on the pull request is skipped, so a review after a new push only adds what is new. A second review of the same head commit is skipped entirely, which makes webhook redeliveries harmless. Comments on lines that are not part of the diff would make GitHub reject the whole review, so the tool moves them into the review summary instead.
Only comments, reviews and issues written by a bot count as the agent’s own, so a person cannot hide a finding by pasting a marker into their own comment.
## Settings
| Setting | Default | Effect |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
| `acts_as` | `agent` | Whose GitHub identity the tools use: `agent`, `person`, or `person_or_agent`. See [Authentication](#authentication). |
| `allow_pull_requests` | `false` | Adds `create_github_pull_request`. Pushing the branch also needs the GitHub App’s **Contents: write** permission. |
| `private_issues_only` | `false` | `upsert_github_issue` refuses public repositories, so a finding is never disclosed in a public issue. |
`upsert_github_comment` starts the comment with a hidden `` line and looks for it on the next run, so an agent that runs on every push updates one comment instead of adding a new one each time. Use a different marker for each kind of comment.
## Authentication
The tools act on GitHub as the identity `acts_as` names; only `person_or_agent` ever uses a second one:
* `agent` (default) uses the agent’s own GitHub connection: its GitHub App when you connected one, so comments are posted as the agent’s bot and the tools reach only the repositories the App is installed on. An agent that chose **Use the Everruns app** acts as the shared Everruns App’s bot on the account an org admin linked. Use it for bots, and for anything triggered without a person.
* `person` uses the GitHub connection of the person talking to the agent. Use it for a personal agent. A triggered run has no person, so it gets nothing.
* `person_or_agent` uses the person’s connection when they have one, otherwise the agent’s.
Each call gets a short-lived token limited to the one repository it names and the permissions that tool needs: the read tools ask for **Pull requests: read**, the checkout tool for **Contents: read** and **Pull requests: read**, the comment tool for **Issues** and **Pull requests: write**, the review tool for **Pull requests: write**, the issue tool for **Issues: write**, and `create_github_pull_request` for **Pull requests: write** and **Contents: read**. Without a connection for that identity the tools return `connection_required`.
The session’s network access policy must allow `https://api.github.com/` when one is set.
---
# GitHub Scout
> Blueprint-only GitHub repository exploration capability that spawns read-only scout subagents.
Source: ` code (e.g. `guardrail.regex`, `guardrail.llm_judge`, `guardrail.moderation`). Clients localize copy from the code rather than the human-readable text. (The separate [Prompt Canary Guardrail](https://everruns.com/docs/capabilities/prompt-canary-guardrail/) capability uses its own `system_prompt_leak` code.)
## Endpoints
| Method | Path | Description |
| ------ | -------------------------------------- | -------------------------------------------------------- |
| `GET` | `/v1/capabilities/guardrails/examples` | List adoptable gallery presets with trust metadata |
| `POST` | `/v1/capabilities/guardrails/dry-run` | Evaluate a config against sample text; nothing persisted |
Both are gated by the same `capability.view` policy as other capability reads.
## Related
* [Prompt Canary Guardrail](https://everruns.com/docs/capabilities/prompt-canary-guardrail/), a narrow streaming-output guardrail for naive system-prompt leakage.
* [Agent Checks](https://everruns.com/docs/features/agent-checks/), advisory, config-*time* review of an agent’s setup. Distinct from guardrails, which enforce at *runtime*.
---
# Host Shell
> Run bash commands on the machine hosting the agent, bounded by a kernel policy (Landlock and seccomp on Linux, Seatbelt on macOS).
Source: "}` | run that binary |
| `{"reexec_self": [""]}` | re-exec this binary with those leading arguments |
`everruns-core` (`host` feature) ships `everruns-sandbox-exec` under the same feature, but cargo does not build a dependency’s binaries, so a single-binary host will not find one beside it. Such a host routes the arguments into `everruns_core::host::containment::worker::run_from_args` from its own `main` and selects `reexec_self`. See the [Host Shell Agent example](https://everruns.com/docs/framework/examples/host-shell-agent/).
## See Also
* [Bashkit Shell](https://everruns.com/docs/capabilities/bashkit-shell/), the sandboxed interpreter
* [File System](https://everruns.com/docs/capabilities/file-system/), file operations on the same workspace
* [Daytona](https://everruns.com/docs/capabilities/daytona/) and [E2B](https://everruns.com/docs/capabilities/e2b/), real binaries on someone else’s machine
* [Capabilities Overview](https://everruns.com/docs/capabilities/)
---
# Infinity Context
> Trim live prompt history and query older messages on demand, so conversation length is not bounded by the context window.
Source: /`: original files, with their hierarchy preserved.
* `/knowledge-text//`: extracted text where available.
The existing **Data Knowledge** capability keeps its read-only `/knowledge/{tables,business,queries}` scaffold. Its index and the collection catalog share `/knowledge/index.md`; collection ID subtrees always use live collection permissions, including when a collection is detached. Directory listings and grep scoped to a Knowledge path include both sources.
Read indexes first, then individual files as needed. An authored `index.md` is preserved; collections without one receive a bounded generated index. Use `browse_knowledge` or `knowledge files` to page through larger directories without enabling indexing. Request metadata only when needed; metadata pages are separately bounded. Knowledge bindings belong to the calling session, including when several sessions share a workspace. Sharing workspace files does not share Knowledge attachments.
## Ownership and attachment scope
Collections, their indexes and search-provider accounts belong to an organization. Users manage them through organization permissions; a personal GitHub connection supplies source credentials, not a private user index.
Attach collections through the **Knowledge** capability on a harness, agent or session. Configuration follows the existing capability precedence: harness, then agent, then session. A higher layer replaces the lower layer’s configuration for that capability, so list every collection the session should retain. Collections are shared rather than copied or reindexed for each agent or session.
Runtime tools, Bashkit search, automatic retrieval and mounts use the calling session’s effective collection bindings and live file visibility. There are no separate user-, agent- or session-owned Knowledge indexes, and an agent does not automatically search every collection in its organization. Sharing a workspace does not share its sessions’ Knowledge bindings.
## Search and grep
Choose **Off**, **Keyword**, or **Hybrid** in collection settings. Hybrid needs an enabled embedding model and a persistent Turbopuffer backend. Keyword indexing works with Turbopuffer or the local PostgreSQL full-text fallback. PostgreSQL stores catalog rows, fragment offsets and local lexical postings, not canonical passage text or binary payloads. Collections using a remote indexer keep their postings there.
The `search_knowledge` tool accepts a query, optional collection subset, path prefix, user metadata filter, result limit and `lexical_only` flag. Requested collections are always intersected with the session’s current bindings. Returned passages carry immutable file/version IDs, source locators and extracted-text offsets.
Bashkit uses the same retrieval service:
```bash
knowledge files --collection kn_0123456789abcdef0123456789abcdef --path /policies --limit 50
knowledge search --limit 5 'refund policy'
knowledge search --collection kn_0123456789abcdef0123456789abcdef --lexical 'retention'
knowledge search --metadata '{"team":"support"}' 'refund policy'
grep -n 'retention' /knowledge/kn_0123456789abcdef0123456789abcdef/policies.md
```
Exact grep is independent of the index. Scope it to `/knowledge-text` to search extracted documents. Scans and returned data are bounded; narrow the path if a scan exceeds its budget.
With `automatic: true`, Everruns retrieves a small amount of relevant evidence for the incoming user message before model execution. Evidence is retained by input ID for replay, checked against live visibility, and added as source data. Retrieval has a five-second timeout and does not prevent a turn from running when unavailable. Query embedding calls use session usage events; ingestion embeddings are attributed to the organization.
## Content and metadata
Original bytes are retained for every format. Markkit extracts HTML, DOCX and spreadsheets. Text and code retain their original UTF-8 representation. Markdown frontmatter, including OKF fields and unknown extensions, is preserved alongside user annotations. Links and file paths remain source-relative. OKF remains a directory of original files: concept Markdown, reserved `index.md` navigation, `log.md` history and binary assets all round-trip through uploads/downloads or a Git source. Unknown frontmatter fields remain intact, including BOM/CRLF files; there is no conversion into fixed entry kinds. `GET /v1/knowledge/{collection_id}/okf` validates a page of OKF v0.2 metadata and reserved-file structure. Follow `next_cursor` to validate the rest of a large catalog. This checks metadata requirements, not every Markdown link or authored index entry.
Unsupported binaries, including PDFs, images, audio and video, remain downloadable. This release does not provide PDF extraction, OCR, transcription or multimodal embeddings. Files exceeding the extraction budget remain stored and report that state rather than disappearing.
Collection rules independently exclude paths from ingestion, indexing or agent reads. File controls can disable indexing or agent reads without removing the original. Managers can annotate connected files; their source content stays read-only.
## Incremental processing and storage
Sync compares Git blob identities before uploading content artifacts. Changed files receive immutable versions; unchanged files retain their version and citations. Extraction is reused for metadata-only edits, and embeddings are cached by organization, model profile and passage hash. Source deletions apply only after a successful complete traversal. Leased jobs renew during source fetches and indexing, retry interrupted work, and index generations publish after the catalog’s visibility checks pass.
Uploads and downloads stream in bounded segments. Content uses the configured S3-compatible blob store; local development falls back to `KNOWLEDGE_STORAGE_ROOT` (default `.local/knowledge`). Use shared object storage for multiple server replicas. Back up the database and content store together.
Organization search accounts reference encrypted, write-only organization service credentials. A revoked or invalid selected credential fails closed; it never falls back to the deployment account. Embedding provider credentials are configured separately in the model catalog.
## Current bounds
File catalogs paginate at up to 500 rows. Agent directory listings cap at 500 children, file reads at 1 MiB, extraction at 8 MiB, and exact grep at 5 MiB of scanned content, 5,000 candidate files and a 512 KiB per-file ceiling. Streamed originals have a 1 TiB per-file transfer ceiling; this is a safety limit, not a tested capacity claim. Git fetching streams shallow snapshot packs directly into the object store, with the existing 512 MiB pack limit. A synthetic million-file catalog and bounded streamed-original fixture qualify catalog/transfer behavior; these do not establish end-to-end terabyte indexing throughput. Source refresh is explicit. Retained versions currently have no automatic expiry; monitor content storage and keep it with database backups. Additional source adapters and document extractors can use the same collection boundary.
Management APIs are under `/v1/knowledge` and `/v1/knowledge-indexers`; the generated command catalog exposes the corresponding `everruns knowledge` commands. Organization settings permissions govern management, and explicit agent/session bindings govern runtime reads. A read-only personal access token can browse, download, validate metadata and search; file changes, source refresh and configuration require a full-access token.
## Deployment storage
Knowledge originals and extracted text need shared, persistent content storage on hosted replicas. `KNOWLEDGE_STORAGE_BACKEND=s3` uses the existing `STORAGE_S3_*` configuration for Knowledge alone, even while `STORAGE_BLOB_BACKEND=db` keeps workspace files and image bytes inline in PostgreSQL. It does not backfill or move existing files. The default `inherit` uses the existing shared blob backend or the local development fallback. Do not use the local fallback on ephemeral hosted containers. An invalid explicit S3 configuration fails startup; storage errors never silently switch to local disk. Organization adoption and collection permissions remain separate.
---
# Knowledge Base
> The undeployed split knowledge features have been consolidated into Knowledge.
Source: ` in its shell, with progressive `--help`, JSON output, pipes, and workspace redirection. It hides the three tools described below. Omitting `surface` retains those tools. Both interfaces use the same command authorization and documentation mounts.
Workspace builds also ship three read-only skills with this capability:
| Skill | Purpose |
| -------------------------- | ------------------------------------------------------------------------------------------------ |
| `everruns` | Product concepts, Cloud and self-hosted entry points, and documentation links |
| `everruns-cli` | Command usage, scripting examples, and differences between installed CLI, session shell, and MCP |
| `everruns-agent-authoring` | Agent design, configuration, dependencies, and behavioral verification |
The capability enables [Agent Skills](https://everruns.com/docs/capabilities/agent-skills/) for discovery and activation. Use `list_skills` and `activate_skill`; full instructions load on demand from `/workspace/.agents/skills//SKILL.md`. Follow the current session interface when a skill shows an external MCP example. Adding skills grants no additional command permissions. Like embedded docs, these product files are included from the repository at build time; standalone crate builds without the repository skills tree omit them.
The external [MCP endpoint](https://everruns.com/docs/features/mcp/#skills-for-mcp-clients) serves these three skills plus `everruns-mcp`. Rust development guidance is maintained separately in the installable `everruns-framework` skill.
## Tools
### `discover`
Search for operations by name, category, description, or schema terms. Results include command metadata, read-only decision, and output-shape hints. Searches with multiple matches omit schemas and return a refinement hint to keep the result compact. A query that exactly matches a command name returns only that command with its schemas and `bash_usage`, a copyable invocation with the exact supported flags. It also includes bounded `output_fields` paths for building `jq` filters without guessing field names. If expanded schemas would make the result too large, the response omits them with a notice while retaining the authoritative scripting summaries. Use `all: true` only when you truly need to list the entire scriptable catalog, not for a task-specific lookup.
```json
{ "query": "models" }
```
Once you find a command, discover its exact name before invoking it:
```json
{ "query": "create_agent" }
```
For commands with a `cli` spelling, use command-tree `--help` as directed by discovery. Flat-only builtins have no `--help`; use their `bash_usage` and returned schema. Pass array and object values as JSON text, for example `--capabilities '[{"ref":"mcp:..."}]'`.
Unknown flags are rejected before a command runs. This prevents misspelled security-sensitive options, such as an authentication flag, from being silently ignored during a mutation.
### `query`
Run a bounded Bashkit script with only read-only Everruns commands available as builtins. It supports pipes, variables, loops, conditionals, and `jq`.
```json
{ "commands": "list_models | jq '.data[] | {id, model_id, display_name}'" }
```
Commands with mutations or open-world side effects are not available in `query`. Use it to inspect current state and validate changes.
### `execute`
Run a bounded Bashkit script with the full scriptable command catalog. Use it for requested create, update, delete, and other mutating operations.
```json
{
"commands": "create_agent --name 'support-agent' --system_prompt 'Help users.' --default_model_id 'model_...'"
}
```
`execute` is not transactional. If a later command in a script fails, earlier commands may already have succeeded. Inspect the resulting state with `query` before retrying.
MCP server command results include both their public resource `id` and a derived `capability_ref` in the `mcp:` form accepted by Agent capability configuration. Capture JSON results and use `jq` to pass dependent IDs or capability references to later commands in the same script. No separate MCP attachment operation is needed.
## Scope and authorization
Platform tools are always bound to the current session’s organization. Their schemas do not accept `organization_id`, and an injected override is rejected. The server resolves the session’s human owner for every distributed call and applies that caller’s normal command permissions. Attaching this capability does not grant authority the owner does not already have.
## Autonomous workflows
For recurring autonomous work, create an Agent and an Agent Trigger. Do not use a schedule on the Platform Chat session: that would wake the management chat, not provision an independently owned worker workflow.
Credentials are not transferred from Platform Chat session secrets into a new Agent. Configure integrations through their supported Agent-scoped credential or connection flow; do not paste credentials into command scripts.
## Platform documentation
When the build embeds the product documentation, this capability mounts it at `/workspace/docs` as a read-only virtual filesystem, served from memory with no database writes per session. Agents browse it with the standard file tools (`read_file`, `list_directory`, `grep`) or with `cat`, `ls`, and `grep` through Bashkit Shell.
Key sections:
* `/workspace/docs/getting-started/`, introduction, concepts, architecture
* `/workspace/docs/features/`, SDK, CLI, UI, events, harnesses, capabilities
* `/workspace/docs/capabilities/`, per-capability reference
* `/workspace/docs/integrations/`, external integrations (Slack, Daytona, etc.)
* `/workspace/docs/advanced/`, budgets, compaction, embedding, network access
* `/workspace/docs/sre/`, environment variables, runbooks
## See also
* [Platform Chat harness](https://everruns.com/docs/built-ins/harnesses/platform-chat/)
* [MCP](https://everruns.com/docs/features/mcp/)
* [Agent Triggers](https://everruns.com/docs/features/agent-triggers/)
* [Platform Management](https://everruns.com/docs/capabilities/platform-management/), the removed predecessor
---
# Platform Management (removed)
> Removed capability. Its management tools are superseded by the catalog-backed Platform capability.
Source: --help` | Lists one MCP server’s tools |
| `tools --help`, `tools --help` | Shows the tool’s input schema |
| `tools search ` | Finds tools by name and description |
| `tools '{...}'` | Calls an MCP tool |
| `tools '{...}'` | Calls any other tool |
### Surface mode
The default `mode: "cli"` routes eligible operations through the shell. Set `mode: "hybrid"` to keep the CLI route while allowing native discovery and calls. Hybrid mode alone keeps native schemas eager. If `tool_search` is also configured with `bounded: true`, it can reveal optional native schemas within its configured limits; eager owner-required schemas remain visible. The shell source inventory is available from `tools --help` and does not change the static Bash tool description.
```json
{
"ref": "tools_in_shell",
"config": { "mode": "hybrid" }
}
```
The CLI and bounded native search use the same authorized, server-aware index. Legacy native `tool_search` remains unchanged unless configured with `bounded: true`. See [Large MCP catalogs](https://everruns.com/docs/features/large-mcp-catalogs/) for discovery bounds, search configuration, and cache and authorization behavior.
MCP tools are grouped by server (`mcp_github__list_pulls` is `tools github list-pulls`); every other tool is a top-level command (`web_fetch` is `tools web-fetch`). Hyphens and underscores are interchangeable. The list is rebuilt on every shell call, so an MCP server added during a session shows up on the next one.
**Input** is the same JSON object the tool takes as a direct call. It can come from stdin (`jq -n '{repo: "a/b"}' | tools github list-pulls`, or `-`), from a JSON argument, or from `key=value` and `--key value` pairs, which merge over the JSON. `--flag` alone is `true`. A value is read as JSON unless the tool’s schema says the key is a string, so `number=7` is a number and `repo=42` stays text.
**Output** is the tool’s result on stdout: a text result as is, anything else as JSON. Images a tool returns are saved under `tool-images/` in the working directory, and stderr names the files.
**Errors** are one JSON line on stderr with exit code 1, so a script can branch on them:
```json
{"error":{"code":"needs_approval","message":"...","retryable":false}}
```
| Code | Meaning |
| --------------------- | ------------------------------------------------------------------------------------------------------- |
| `unknown_command` | No such server or tool |
| `invalid_input` | The input is not a JSON object or does not match the tool’s schema |
| `tool_error` | The tool ran and failed |
| `denied` | A guardrail or hook blocked the call |
| `needs_approval` | The call needs a person’s approval; the script stops here (see [Approvals](#approvals)) |
| `stopped` | An earlier call stopped the script, so this one did not run |
| `connection_required` | The tool or its MCP server needs a connection the person has not made |
| `call_limit` | More than 50 tool calls in one shell call |
| `unavailable` | The command cannot run here, or a server could not load yet (`retryable` says whether a later step can) |
## Which tools move into the shell
A tool moves behind `tools` when calling it only does something and returns data: MCP tools, integration tools, search and fetch, platform and data tools. These stay direct tool calls:
* the `bash` and `lua` tools themselves;
* tools that pause or shape the turn: `ask_user`, approvals, `spawn_agent`, session tasks, `write_todos`, and client-side tools;
* tools whose result the model must see as an image, such as screenshots, `read_file`, `computer` and `browser`;
* structured file editing (`write_file`, `edit_file`);
* tools listed in the `keep_visible` config.
MCP servers set to “Load tools on demand” move behind `tools` too. `tools --help` lists them as `(not loaded)`; the first command that names one, such as `tools docs --help` or `tools docs search-docs q=refunds`, or a `tools search` that matches deferred server descriptions, loads its tools inside the same shell call. One `tools search` loads at most eight matching deferred servers; the others stay `(not loaded)` for a later search. A load adds that server’s tools atomically and respects the combined 10,000-tool/32 MiB shell catalog limit. Search, help and calls use only tools in the current turn’s visible scope, and loaded child tools retain the scope of their server placeholder. From the next step on a loaded server is listed like any other.
Every call from a script goes through the same checks as a direct call: the turn’s guardrails and hooks run before it, the tool’s schema is checked, and the post-tool hooks see the result before the script does.
## Approvals
Approval-gated and destructive tools are reachable from the shell too, and [Tool Approval](https://everruns.com/docs/capabilities/tool-approval/) judges each call from a script the same way it judges a direct call. Most scripts never ask: reads, searches, and tools a person already allowed “always” just run.
Many MCP tools say nothing about whether they change anything. When the deployment has a decision service configured, such a tool is rated once the first time a script calls it: if it looks like it changes or deletes something outside the session, Tool Approval treats it as destructive and asks before it runs. The approval card then says the tool declares nothing about its risk and only looks like it changes things. A rating only ever adds a question; it never removes one, and tools that declare their own risk are not rated. An agent can turn ratings off with the `rate_unlabeled_tools` setting; such tools are then judged by what they declare, which is nothing, so in Tool Approval’s `normal` mode they run without asking.
When a call written out in full in the script, such as `tools github delete-branch branch=fix-x`, needs a person’s answer, the script does not start at all: the `bash` result says so (`"before_start": true` under `stopped`, `done` is empty), the person is asked about that call, and after they answer the agent can run the same script again. Calls whose input is built while the script runs, or that read their input from stdin, are checked as they run instead.
To see what a script would do before running it, pass it to `tools plan`. It runs nothing and prints each `tools` call it can see, with its input and risk:
```bash
tools plan <<'EOF'
tools github list-pulls state=open
tools github delete-branch branch=fix-x
EOF
```
```json
{
"calls": [
{"tool": "tools github list-pulls", "input": {"state": "open"}, "risk": "read_only", "where": "script"},
{"tool": "tools github delete-branch", "input": {"branch": "fix-x"}, "risk": "needs_approval", "why": "destructive", "where": "script"}
],
"complete": true
}
```
`risk` is `read_only`, `changes` (runs without asking), `needs_approval`, `blocked`, or `checked_at_run_time` when the input is built while the script runs. A `needs_approval` call carries `why`, the reason the approval card will give: `destructive`, `open_world`, `mutating`, `policy`, or `rated_changes` when the tool declares nothing and was rated as changing things. `complete` is `false` when the script hides calls from reading, for example with `eval`. The agent uses it to describe a script accurately before asking a person about it.
When a call needs a person’s answer while the script runs, it is not made and the script stops there. Nothing after it runs, and the script is never resumed or run again, because part of its work is already done and may not be safe to repeat. The `bash` result reports what happened, and the person is asked about the stopped call in the same step:
```json
{
"exit_code": 1,
"success": false,
"tools": {
"done": [
{"tool": "tools linear create-issue", "input": {"title": "Flaky test"},
"ok": true, "result": {"id": "EVE-1201"}}
],
"read_only_calls": 3,
"stopped": {
"reason": "needs_approval",
"approval": "requested",
"call": {"tool": "tools github delete-branch", "input": {"branch": "fix-x"}}
},
"not_reached": "the stopped call and everything after it; write a new script for the rest"
}
}
```
`done` lists every call that may have changed something; read-only calls are counted. After the person answers, the agent writes a new script for what is left. A one-off approval covers that exact call (the tool and its input) once, so the new script can make it. The same report appears when a script stops at the call limit, or exits with an error after changing something.
## In the session timeline
The model sees one `bash` call. Each tool the script called through `tools` is also recorded in the session as a [`tool.nested_call`](https://everruns.com/docs/event-reference/) event under that `bash` call, with its command, a short preview of its input, whether it completed, failed, was refused or stopped the script for approval, and how long it ran. The chat shows these as rows under the shell call. They never reach the model.
## Saved scripts
An agent can keep a script it wrote and run it again later as one command:
```bash
cat <<'EOF' | tools scripts save triage-prs --description 'Label new pull requests.' \
--input-schema '{"type":"object","properties":{"repo":{"type":"string"}},"required":["repo"]}'
repo=$(jq -r .repo)
tools github list-pulls repo="$repo" state=open | jq -r '.[].number' | while read -r n; do
tools github add-labels repo="$repo" number="$n" labels='["triage"]'
done
EOF
tools scripts # list the agent's saved scripts
tools scripts triage-prs repo=a/b # run one
```
* The input is checked against the script’s schema and arrives on stdin as JSON; what the script prints is its result.
* A saved script runs with the tools and identity of the agent turn that runs it, and its `tools` calls follow the same rules: approvals, guardrails, and the 50-call limit of the shell call it runs in. A call that needs approval stops the caller’s script too.
* Its shell has the shell builtins and `tools`; `curl` and the `everruns` command are not available inside it.
* Saved scripts can call each other, up to four deep.
* Saving needs the `manage_scripts` setting. Every agent with the capability can run its saved scripts. Scripts are also managed through the `/v1/agents/{agent_id}/scripts` API and the `everruns agents scripts` command.
* A schedule or webhook [trigger](https://everruns.com/docs/features/agent-triggers/#run-a-saved-script) can run a saved script without a model call.
## Tool search
In the default `cli` mode, Tools in Shell replaces tool search. When both are enabled, the tool search capabilities (`tool_search`, `auto_tool_search`, `openai_tool_search`, `claude_tool_search`) contribute nothing. In `hybrid` mode, bounded `tool_search` can reveal native schemas while Tools in Shell provides the same operations through `tools`. See [Large MCP catalogs and tool surfaces](https://everruns.com/docs/features/large-mcp-catalogs/) for the shared registry model. [Agent Checks](https://everruns.com/docs/features/agent-checks/) report a redundant capability as a `capabilities.superseded` suggestion when it is not active for the selected mode.
## Configuration
```json
{
"capabilities": [
{ "ref": "tools_in_shell", "config": { "mode": "cli", "keep_visible": ["web_fetch"] } }
]
}
```
| Field | Type | Default | Meaning |
| ---------------------- | ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mode` | string | `cli` | `cli` routes eligible tools through the `tools` command; `hybrid` also retains native tool discovery where configured. |
| `keep_visible` | string array | `[]` | Tools the model can still call directly. They stay callable from the shell too. |
| `manage_scripts` | boolean | `false` | Let the agent save scripts with `tools scripts save`. |
| `rate_unlabeled_tools` | boolean | `true` | Ask the decision service whether a tool that declares nothing about its risk changes things, and ask for approval before it if so. Off: such tools run without asking in Tool Approval’s `normal` mode. |
---
# Auto-Continue After Usage Limit
> When an LLM subscription/plan usage limit is reached, automatically resume the interrupted work shortly after the limit resets.
Source: .”* When (and only when) a continuation was actually scheduled, it appends *“We’ll continue work automatically once it resets.”*, so the copy never promises a resumption that will not happen. Without the capability, the same error stays generic and no continuation is scheduled.
## Configuration
### Default
```json
{
"capabilities": ["usage_limit_auto_continue"]
}
```
Defaults: continuation fires **120 seconds** after the reported reset with the prompt **“Continue tasks”**.
### Custom delay and prompt
```json
{
"capabilities": [
{
"ref": "usage_limit_auto_continue",
"config": {
"delay_seconds": 300,
"prompt": "Resume the migration where you left off."
}
}
]
}
```
| Field | Type | Default | Description |
| --------------- | ----------------- | ------------------ | ---------------------------------------------------------------------------------------------------------- |
| `delay_seconds` | integer (0–86400) | `120` | How long to wait after the reset before resuming. A small buffer avoids racing the provider’s reset clock. |
| `prompt` | string | `"Continue tasks"` | Message injected to resume work when the limit resets. |
## When To Enable
Use this capability for agents running long, autonomous, or scheduled work on provider plans that enforce usage-window limits, where a multi-hour stall would otherwise require a human to manually restart the session.
## Limitations
* Requires a provider whose error reports a concrete reset time; without one the error copy stays generic and no continuation is scheduled.
* The continuation is delivered through the session schedule machinery, so it requires both a session schedule store and a schedule poller in the deployment. The hosted platform provides both. The default embedded runtime provides neither, so this capability is **not** part of the runtime-safe preset, an embedder must wire a `SessionScheduleStore` (e.g. via a schedule-store factory) and run a poller for it to take effect; otherwise its error hook is a no-op and the error copy stays generic.
## See Also
* [Schedules](https://everruns.com/docs/capabilities/session-schedules/), the scheduling machinery the continuation reuses
* [Capabilities](https://everruns.com/docs/features/capabilities/), the capability model
---
# User Hooks
> Run user-authored shell commands at lifecycle and tool events. Block, mutate, or audit agent actions from outside the model.
Source: "}}` and the turn proceeds with the rewritten text. For example, to prepend a house style reminder:
```jsonc
{
"id": "prepend_style_note",
"event": "user_prompt_submit",
"executor": {
"type": "bash",
"command": "echo \"$EVERRUNS_HOOK_PAYLOAD_JSON\" | jq -c '{decision:\"mutate\",patch:{message:(\"[reminder: follow the house style guide]\\n\" + .data.message)}}'"
},
"on_error": "warn"
}
```
### Log every completed turn
`turn_end` is advisory, its decision is ignored, so use it for side effects like metrics or audit trails. The payload’s `data.success` reports whether the turn finished cleanly.
```json
{
"capabilities": [
{ "ref": "session_file_system" },
{ "ref": "bashkit_shell" },
{
"ref": "user_hooks",
"config": {
"hooks": [
{
"id": "log_turn_end",
"event": "turn_end",
"executor": {
"type": "bash",
"command": "echo \"$EVERRUNS_HOOK_PAYLOAD_JSON\" | jq -r '.ts + \" turn \" + .turn_id + \" success=\" + (.data.success | tostring)' >> /workspace/.turn-log; echo '{}'"
},
"timeout_ms": 3000,
"on_error": "warn",
"description": "Append one line per completed turn to /workspace/.turn-log"
}
]
}
}
]
}
```
## Observability
Today, hook decisions and errors are recorded in the server logs via `tracing`: blocks, ignored post-hook blocks, mutations, `on_error` outcomes, and `disabled_contributions` mutings are logged with the resolved `hook_id` and the `tool_call_id`.
**Planned (deferred):** structured `hook.invoked` / `hook.completed` / `hook.blocked` / `hook.warning` events emitted through the same observability pipeline as tool events (Braintrust, OTel). These are not emitted yet, see the spec’s observability section.
## Event firing
All six events fire:
* **`pre_tool_use`**: before each tool call; can block or mutate the call.
* **`post_tool_use`**: after each tool call; can mutate the result.
* **`session_start`**: after a session is created (mounts + initial files in place); advisory.
* **`session_end`**: when a session is deleted, before VFS eviction; advisory.
* **`user_prompt_submit`**: on the first reason iteration, before the LLM is consulted; can block (aborts the turn with a user-facing message) or mutate the user message text.
* **`turn_end`**: when a turn reaches a terminal outcome; advisory.
Note on `user_prompt_submit` blocking: the API persists the user message and runs the turn asynchronously, so a block does not reject the HTTP request, it aborts the turn. The session shows a `turn.failed` outcome carrying the hook’s `user_message`.
## See also
* [Capabilities](https://everruns.com/docs/capabilities/), compose tools and runtime behavior
* [Guardrails](https://everruns.com/docs/capabilities/guardrails/), runtime safeguards
* [Bashkit Shell](https://everruns.com/docs/capabilities/bashkit-shell/), the sandbox that runs hook commands
---
# User MCP Servers
> Give an agent the MCP servers of the person chatting with it, signed in as that person, and optionally let it add and connect them in chat.
Source: `) and loads a server’s tools through `tool_search`, or by calling that line, when it needs them. They are callable from its next step and stay loaded for the rest of the conversation (see [Loading tools on demand](https://everruns.com/docs/features/mcp/#loading-tools-on-demand)). Turning off **Load tools on demand** on a server in **Settings > My MCP servers** (`deferred: false` when adding or updating it under `/v1/virtual-users/{id}/mcp-servers`) lists its tools at the start of every turn instead. Servers added for one conversation only always load on demand.
## Risk
Medium. The agent can call any tool on servers the person chose, with the person’s login. Tool approval and the agent’s other guardrails apply to these tools as to any MCP tool.
With `manage`, adding a server is how a prompt injection would try to send the person’s data somewhere new. Enable Tool Approval in `normal` or `protective` mode to hold add and enable calls for the person’s approval. Leaving approval absent or off allows these calls to run autonomously. Custom URLs remain off by default, and every URL goes through the same address checks as the API.
---
# Web Fetch
> Fetch a URL and convert its HTML to markdown or plain text, with SSRF protection and structured fetchers for common developer and research sources.
Source: /skills/`.
Start a session with `yolop --profile `. Credentials stay global. A profile at `profiles/triage.toml` under the config directory:
```toml
instructions = "You are the triage agent."
mcp_mode = "replace"
[[capabilities]]
ref = "ext:triage"
[mcp.servers.linear]
type = "http"
url = "https://profile.example/mcp"
```
See [Session coordination](https://github.com/everruns/yolop/blob/main/docs/session-coordination.md) for a profile example and [#586](https://github.com/everruns/yolop/pull/586).
---
# A2A delegation in the everruns crate is now an opt-in feature
> Outbound A2A delegation moved behind a new a2a Cargo feature that is off by default, so local runtime builds no longer compile a second HTTP and TLS stack.
Source: ` can now make a capability discovered after composition resolvable without rebuilding the runtime, via `register_capability`/`is_capability_registered`. Registration stays separate from activation, and readers always see a consistent registry snapshot ([#3224](https://github.com/everruns/everruns/pull/3224)).
* **A2A delegation is now opt-in**: Outbound A2A delegation moved behind a new `a2a` Cargo feature, off by default, so the standard build no longer drags a second HTTP/TLS stack into consumers that only run the local runtime. Hosts that delegate to remote A2A agents enable the `a2a` feature explicitly ([#3221](https://github.com/everruns/everruns/pull/3221)).
## In the changelog
* [A2A delegation in the everruns crate is now an opt-in feature](https://everruns.com/docs/changelog/2026-08-18-a2a-delegation-opt-in/)
* [Register a capability on a running Framework runtime](https://everruns.com/docs/changelog/2026-08-19-register-capabilities-running-runtime/)
Before upgrading, read the breaking changes: [A2A delegation in the everruns crate is now an opt-in feature](https://everruns.com/docs/changelog/2026-08-18-a2a-delegation-opt-in/).
See the [GitHub release](https://github.com/everruns/everruns/releases/tag/v0.20.0) and the [full release notes](https://github.com/everruns/everruns/blob/main/CHANGELOG.md#0200---2026-08-19) for every pull request in this version.
---
# Register a capability on a running Framework runtime
> A host holding a shared InProcessRuntime can add a capability discovered after startup and activate it in live sessions without rebuilding the runtime.
Source: ` exits 1 instead of printing a UTC time.
```toml
bashkit = { version = "0.17", default-features = false, features = ["http_client", "ring", "tzdata"] }
```
Non-ASCII domain names in HTTP allowlists are now rejected rather than normalized; use their punycode form.
See [Networking](https://github.com/everruns/bashkit/blob/main/docs/networking.md), [#2317](https://github.com/everruns/bashkit/pull/2317) and [#2321](https://github.com/everruns/bashkit/pull/2321).
---
# Runs as a WebAssembly component without JS or WASI
> Bashkit can run as a component-model WebAssembly guest in plain wasmtime or a Hyperlight micro-VM, with no JavaScript engine and no WASI needed.
Source: -metal.tar.gz` and `yolop-x86_64-unknown-linux-gnu-cuda.tar.gz`. The default archive, which Homebrew installs, leaves it out, so the Linux tarball dropped from 29.9 MB to 18.2 MB. From source, build with the `metal` or `cuda` feature.
See [Providers and models](https://github.com/everruns/yolop#providers-and-models), [#581](https://github.com/everruns/yolop/pull/581), [#599](https://github.com/everruns/yolop/pull/599) and [#623](https://github.com/everruns/yolop/pull/623).
---
# Archive finished chats and show them again on demand
> Archiving hides a chat thread from the Chats list without deleting it, and a Show archived filter and the archive API bring it back when needed.
Source: .tar.gz` is the default-features build the Homebrew formula points at, and no longer carries the local-inference engine; `yolop--metal.tar.gz` and `yolop-x86_64-unknown-linux-gnu-cuda.tar.gz` carry the engine with the backend that target can use. The Linux tarball drops from 29.9 MB to 18.2 MB. Extension servers are now built for every target too, not just the last one the matrix collapsed onto.
* The runtime recovers from failure loops instead of repeating them: consecutive equivalent invocation, missing-command, wrong-path, and usage failures on an unchanged workspace now require a different action or a bounded progress checkpoint, and a checkpoint is a real trajectory transition rather than a hook-only backstop.
* File discovery is batch-native. `read_many_files` is advertised eagerly, so a model can read independent known paths in one call even when the provider emits one tool call per turn, and `repo_map` keeps its compact parameter schema in the first-turn profile.
* Input routing is one ordered ownership table, so a paste while the sandbox-approval prompt owns the screen no longer lands in the composer behind it.
* ACP prompts continue once after the provider exhausts its stream-stall retries, replaying from the durable transcript so settled tools are not re-run.
* The everruns family moves to core 0.19 and provider 0.20, where reasoning is ordered `ContentPart::Reasoning` artifacts rather than a flat message field, and tuika to 0.11.0.
## In the changelog
* [Run models on your machine with the local provider](https://everruns.com/docs/changelog/2026-08-21-yolop-local-inference-provider/)
See the [GitHub release](https://github.com/everruns/yolop/releases/tag/v0.17.1) and the [full release notes](https://github.com/everruns/yolop/blob/main/CHANGELOG.md#0171---2026-08-27) for every pull request in this version.
---
# Everruns CLI plugins, skills and knowledge-bases commands work again
> The everruns plugins, skills and knowledge-bases commands called unversioned API paths and got 404 responses; they now use the /v1/ routes.
Source: ` inspects global, workspace, or effective scope, and `disable` is its own command instead of `enable --disable`.
* Fresh `cargo install yolop` works again. Every `everruns-*` requirement is pinned exactly, so a from-scratch resolve picks the set that was actually built and reviewed, and that set is now the everruns 0.20 facade release.
* Reasoning effort resolves from every source that knows about it, curated registry, then provider-advertised parameters, then the reasoning-required families, so a model the registry has never seen keeps its `/effort` control and repairs a mandated-reasoning rejection once on its own.
* The runtime stops doing work twice: a background task the foreground turn already reported no longer wakes a duplicate turn, and the environment context reports the shell’s real network access instead of a stale no-network claim.
* `web_fetch` reaches public URLs again, and MCP restart/reconnect/reload land on the typed `mcp reload` command.
## In the changelog
* [Turn activity compacts into one summary row by default](https://everruns.com/docs/changelog/2026-09-03-yolop-compact-work-default/)
See the [GitHub release](https://github.com/everruns/yolop/releases/tag/v0.17.3) and the [full release notes](https://github.com/everruns/yolop/blob/main/CHANGELOG.md#0173---2026-09-10) for every pull request in this version.
---
# Manage and log in to MCP servers from the CLI
> The yolop mcp command now covers show, enable, disable and an OAuth login for remote MCP servers, so MCP setup no longer needs the TUI or config files.
Source: ` prints the global, workspace or effective entry, and `disable` is its own command instead of `enable --disable`.
`yolop mcp login ` runs the OAuth flow for a remote server: it prints the authorize URL, opens the browser, waits for the callback and saves the tokens. Before, that flow existed only as `/mcp login` inside the TUI.
```bash
yolop mcp login linear
```
See [MCP servers](https://github.com/everruns/yolop#mcp-servers), [#661](https://github.com/everruns/yolop/pull/661) and [#677](https://github.com/everruns/yolop/pull/677).
---
# Everruns servers publish an MCP server card and auth.md
> Every Everruns deployment now serves an MCP Server Card and an auth.md document, derived from live config, so agents can discover how to connect.
Source: --flags` is now a single grammar. The external CLI, the `/mcp` endpoint and a session’s shell render it from one declaration, so the CLI grows from 82 commands to 309 across 31 nouns, and `--help` reaches every one of them. Flat names such as `list_agents` keep working as aliases.
```bash
everruns agents list
everruns sessions --help
```
**In code:** a Framework application exposing its own command tree can name its root token with `CliCommandSource::root` instead of `everruns`.
A Platform Chat v2 harness built on this command line is available behind an organization opt-in flag. See [CLI](https://everruns.com/docs/features/cli/) and [CLI reference](https://everruns.com/docs/reference/cli/). [#3680](https://github.com/everruns/everruns/pull/3680), [#3490](https://github.com/everruns/everruns/pull/3490), [#3496](https://github.com/everruns/everruns/pull/3496)
---
# Guardrails can use typed judgments as their check engine
> LLM judge and moderation guardrails can run on calibrated probabilities from TypeSafe judgments, batching every check on a stage into one request.
Source: ` and say whose sign-in its calls use with `actsAs` (`none`, `service`, `user` or `user_or_service`):
```json
{
"github": {
"use": "catalog:github",
"actsAs": "user"
}
}
```
See [MCP](https://everruns.com/docs/features/mcp/) and [MCP credentials](https://everruns.com/docs/integrations/mcp-credentials/). [#3726](https://github.com/everruns/everruns/pull/3726), [#3675](https://github.com/everruns/everruns/pull/3675), [#3638](https://github.com/everruns/everruns/pull/3638)
---
# Install an Everruns agent in Slack with one click
> Connecting an agent to Slack no longer needs credentials copied from api.slack.com: Everruns creates the Slack app and takes its credentials from OAuth.
Source: ",
"parts": [
{
"kind": "data",
"data": {
"everruns/ask_user_answer": {
"tool_call_id": "call_ask_1",
"status": "answered",
"answers": [
{
"id": "target",
"selected": [
"Production"
]
}
]
}
}
}
]
}
```
See [Ask User](https://everruns.com/docs/capabilities/ask-user/), [MCP](https://everruns.com/docs/features/mcp/) and [A2A](https://everruns.com/docs/features/a2a/). PRs [#3781](https://github.com/everruns/everruns/pull/3781), [#3780](https://github.com/everruns/everruns/pull/3780), [#3828](https://github.com/everruns/everruns/pull/3828).
---
# Framework engines get event listeners and OpenTelemetry export
> Register a listener once per Engine to receive events from every session it owns, and export Framework sessions to OpenTelemetry or Braintrust.
Source: "
}
}
}
```
* An agent trigger with `trigger_type: "mcp_event"` subscribes to an event one of the agent’s own MCP servers publishes, such as a tracker announcing new issues, and starts a session when it arrives.
See [MCP](https://everruns.com/docs/features/mcp/) and [Agent triggers](https://everruns.com/docs/features/agent-triggers/). PRs [#3931](https://github.com/everruns/everruns/pull/3931), [#3970](https://github.com/everruns/everruns/pull/3970).
---
# OpenAI structured output and background mode for long reasoning
> OpenAI drivers enforce JSON Schema structured output, and xhigh or max reasoning calls run as background responses that resume after a drop or worker restart.
Source: -custom`; update callers that look it up by name:
```bash
# Before: a custom harness named "conversation"
everruns agents update agent_xxx --harness conversation
# After
everruns agents update agent_xxx --harness conversation-custom
```
**In code:** `Harness::base()`, `conversation()`, `worker_base()` and `worker()` build the same presets.
See [Harnesses](https://everruns.com/docs/features/harnesses/) and the [upgrade notes](https://everruns.com/docs/framework/upgrade-notes/). PR [#4133](https://github.com/everruns/everruns/pull/4133).
---
# Everruns 0.35.0: Safer sandbox tools
> A computer use capability lets agents operate a browser screen, sandbox tools are safer, questions are answered in chat, and every org gets Platform Chat.
Source: ` variable now takes a rollout grade: `dev`, `internal`, `adoption`, `prod` or `off`. `internal` features stay off until a platform operator enables them for an organization, `adoption` features are opt-in for organization owners and admins, and `prod` features are on by default.
Upgrade your configuration:
* `FEATURE_*=preview` becomes `internal`.
* `true` becomes `adoption` to keep organization opt-in, and `false` becomes `off`.
```bash
# Before
FEATURE_PUBLIC_CHAT=preview
# After
FEATURE_PUBLIC_CHAT=internal
```
Invalid values, including the old ones, disable the feature. The separate `DEPLOYMENT_GRADE=preview` is unchanged.
See [Environment variables](https://everruns.com/docs/sre/environment-variables/). PRs [#4115](https://github.com/everruns/everruns/pull/4115), [#4137](https://github.com/everruns/everruns/pull/4137).
---
# Playground for testing agents, and Chat as one permanent conversation
> Agent testing moves to a shared Playground where members pick the agent and the user it runs as, while Chat becomes your permanent Platform Chat conversation.
Source: "})).await?;
```
`TerminalTool::with_sessions` adds up to 8 named tabs that share the filesystem and keep running in the background. Python (`bashkit.Terminal`) and Node (`Terminal` in `@everruns/bashkit`) expose the same calls.
See [Terminal](https://github.com/everruns/bashkit/blob/main/docs/terminal.md), [#2509](https://github.com/everruns/bashkit/pull/2509), [#2518](https://github.com/everruns/bashkit/pull/2518), [#2521](https://github.com/everruns/bashkit/pull/2521), [#2523](https://github.com/everruns/bashkit/pull/2523) and [#2548](https://github.com/everruns/bashkit/pull/2548).
---
# Claude Haiku 5.5 model added for Anthropic providers
> The claude-haiku-5-5 model and its 1M-context twin are seeded as an enabled favorite, with adaptive thinking, tool search and the computer toolset.
Source: --help` now ends with a worked example, every command group describes itself, and about 150 more flags have a help line. Commands whose flat form took a bare ID now take it in the tree form too.
```bash
everruns mcp-servers tools --help
```
The same help is rendered into a new **Reference → CLI Commands** section, one page per command group generated from the binary itself, so the docs and the installed CLI say the same thing.
See the [CLI reference](https://everruns.com/docs/reference/cli/), [CLI](https://everruns.com/docs/features/cli/) and [#4433](https://github.com/everruns/everruns/pull/4433).
---
# Everruns Cloud shows spend per model and agent on a Usage tab
> A Usage tab breaks down Everruns Cloud charges by day, model and agent with token counts and CSV export, and a credit chip and banner warn on low credit.
Source: "Rebase on main before you push."
```
See [Session coordination](https://github.com/everruns/yolop/blob/main/docs/session-coordination.md), [#835](https://github.com/everruns/yolop/pull/835) and [#837](https://github.com/everruns/yolop/pull/837).
---
# New setups default to the latest model on every provider
> New Yolop setups default to gpt-6.1-sol, claude-opus-5-5, muse-spark-1.3 and gemini-3.8-flash; a saved model setting or the -m flag still takes priority.
Source: /quarterly-report.pdf
```
Changing the agent’s avatar also updates the Slack app icon. See [Connect an Agent to Slack](https://everruns.com/docs/capabilities/slack/#connect-an-agent-to-slack).
Watch [Kids Duties in Everruns and Slack](https://www.youtube.com/watch?v=mbbYFif9juY) for a real configuration, saved execution and Slack conversation. The original messages are Ukrainian; narration and captions are English.
[Slack integration: Kids Duties agent in Everruns](https://www.youtube-nocookie.com/embed/mbbYFif9juY?rel=0)
---
# Tool calls cut off by a crash are rerun when it is safe
> After a worker crash, calls that never started, read-only and idempotent calls run again, and MCP servers get a stable idempotency key.
Source: /` in the session’s own files and returns the part that sends it. The agent can open it again with `read_file` after compaction, and a zip unpacks into a folder next to it.
```rust,no_run
let report = session
.attach("report.pdf", Some("application/pdf"), std::fs::read("report.pdf")?)
.await?;
let mut message = InputMessage::user("Summarize the attached report.");
message.content.push(report);
session.run(message).await?;
```
A serve app’s message endpoint takes the same `files` list as the Agent API, and embedded Slack files are kept the same way. See [Send files](https://everruns.com/docs/framework/sessions/#send-files) and the [serve wire API](https://everruns.com/docs/framework/serve/#wire-api).
---
# Gemini setups prefer Argon and include it in favourites
> Gemini 4 Argon is the preferred default for new Gemini setups and an enabled favourite in the server model catalogue. Existing defaults stay selected.
Source: `. Keep the scenario mix with results: the file workload differs from earlier runs that chose arbitrary read tools.
---
# OpenTelemetry fixes export and cached-token totals
> OpenTelemetry fixes background export, cached-token totals, repeated tool-call IDs, error privacy and Framework shutdown failure reporting.
Source: ) -> OpenRouterChatDriver {
OpenRouterChatDriver::new().with_transport(fetch)
}
```
The celld engine example uses the shared driver with a Workers-compatible adapter. Integration tests exercise model and tool-call exchanges inside both workerd Worker handlers and Durable Objects. Native applications keep their existing HTTP client unless they inject a transport.
See [Models and Providers](https://everruns.com/docs/framework/models-and-providers/#wasm-and-host-fetch) for the adapter contract and supported chat drivers.
---
# Control Yolop continuation budgets and trace stop reasons
> Yolop supports five automatic continuations, configurable limits, durable stop and retry reasons, and OpenTelemetry budget diagnostics.
Source:
```
See [Outbound traffic](https://everruns.com/docs/advanced/physical-architecture/#outbound-traffic) and [Tenant egress proxy variables](https://everruns.com/docs/sre/environment-variables/#tenant-egress-proxy).
---
# Yolop searches with the shared web_search tool
> Yolop's default harness now has web_search: the model's own search first, then Brave or Parallel with a key, then free search.
Source: {
Agent::builder()
.instructions("You maintain this repository.")
.model(Model::on("team-openai", "gpt-6.1-sol"))
.host_services(services)
.build()
}
```
Collisions with Framework capabilities, conflicting provider declarations and request metadata that claims a correlation id such as `session_id` fail the build, and the session filesystem stays the one the Environment chose. See [Host Services](https://everruns.com/docs/framework/host-services/).
---
# Run commands and hot-install capabilities on live sessions
> Framework sessions run slash commands, activate host-registered capabilities and switch model, effort and MCP servers without a runtime handle.
Source: {
session
.complete(
CompletionRequest::new()
.system_prompt("Decide whether the task is complete.")
.user(evidence)
.purpose("completion_review"),
)
.await
}
```
Reserved metadata keys and tool messages are rejected, and an unavailable provider fails without fallback. See [Session Controls](https://everruns.com/docs/framework/session-controls/).
---
# Large MCP catalogs use bounded search and schemas
> MCP catalogs load across pages, search server and schema text within current access, and reveal bounded tool schemas through native calls, CLI, or both.
Source: ` and the flat names (`create_agent`) are commands; `query` refuses anything that changes state |
| Platform capability | agents with the `discover`, `query`, `execute` tools | The same scripted toolset as `/mcp`, called from the worker over gRPC |
| `everruns` in the agent’s shell | agents in a shell-only harness | Parses the command line in the worker, then sends the command name and parameters over gRPC |
Workers never read the database. When an agent on a worker runs a platform command, the worker sends it to the control plane, which reloads the session, checks again that the session really has the Platform capability, and runs the command as the session’s owner in the session’s organization. It never trusts an identity the worker sends.
## One grammar
The CLI, the scripted toolset and the agent’s shell all parse `everruns --flags` with the same parser, built from a command contract that the server generates from its registry. That is why `everruns agents list --limit 10` means the same thing typed in a terminal and in an agent’s shell: the same flags, the same short options, the same help, and the same errors for an unknown flag or a missing required one. See [CLI](https://everruns.com/docs/features/cli/#platform-commands) for the commands and [Platform](https://everruns.com/docs/capabilities/platform/) for the agent-facing tools.
## Where the surfaces differ
* **Hand-written CLI commands.** A few CLI commands do local work no server command can, such as reading a definition file or syncing files, so they keep their own flags. Every other CLI command comes from the contract.
* **Flat names.** `/mcp` and the Platform capability also accept flat names like `create_agent --name ...`, for scripts written before the noun-verb spelling existed.
* **Read-only mode.** `query` accepts only commands that do not change state; `execute` accepts any command the caller is allowed to run.
* **Retries.** Only `POST /v1/commands` takes an `Idempotency-Key`, because it is the surface a network sits in front of. The CLI sends one on every command and retries dropped connections with the same key. See [CLI retries](https://everruns.com/docs/features/cli/#retries).
On every surface, a command that changes an entity saves the change, its entry in the entity’s history and, over `POST /v1/commands`, the response a retry with the same `Idempotency-Key` gets back, all together. If any of them cannot be saved, the command fails with a server error and nothing changes, so a retry is safe. A few commands that call other services while they run, such as creating a provider (which discovers its models) or installing a plugin, save the change first and its history after.
---
# Durable execution
> Why Everruns persists every step of agent execution to PostgreSQL and runs each session as a leased actor: the guarantees that gives, and the trade-offs.
Source: `. |
| `/v1/channels/{channel_id}/a2a/message:send`, `/tasks`, … | The same operations over A2A’s plain HTTP binding (HTTP+JSON). Same key. |
| `GET /v1/channels/{channel_id}/a2a/.well-known/agent-card.json` | The public Agent Card, served only while the channel is live. |
When the agent has an avatar, the Agent Card carries it as `iconUrl`: the 256 px square preset, on the same origin as the card.
### Configuration
| Field | Description |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session_mode` | `session_per_invocation` starts a fresh session for each new task. `shared_session` sends every call into one long-lived session. |
| `message` | Template for the user message the agent receives. `{{a2a.text}}` is the caller’s text parts joined by newlines; `a2a.task_id`, `a2a.context_id`, and `payload` (the raw request params) are also available. |
| `agent_card_name`, `agent_card_description` | Shown in the Agent Card. They default to the agent’s name and description. |
| `rate_limit_per_minute` | Optional per-caller-IP limit for this channel. Over the limit, calls get HTTP 429. |
| `signing_secret` | Optional. When set, every request must also carry an HMAC signature of its body. |
Instead of a generated key, a channel can use the shared channel auth modes: HTTP Basic, OIDC or Google JWT bearer tokens, OAuth2 token introspection, or mTLS. The Agent Card advertises whichever scheme is in use and never includes a credential.
### Call it
Any A2A 1.0 client works. With the official [`a2a` CLI](https://github.com/a2aproject/a2a-go):
```bash
CARD="$EVERRUNS/v1/channels/$CHANNEL_ID/a2a/.well-known/agent-card.json"
a2a card get -a "$CARD"
a2a send -a "$CARD" --auth "Bearer $KEY" "Summarize the A2A spec in three bullets."
a2a send -a "$CARD" --auth "Bearer $KEY" --stream "Explain A2A tasks in one sentence."
```
Or with plain JSON-RPC:
```bash
curl -sS -X POST "$EVERRUNS/v1/channels/$CHANNEL_ID/a2a" \
-H "Authorization: Bearer $KEY" \
-H 'Content-Type: application/json' \
-H 'A2A-Version: 1.0' \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "SendMessage",
"params": {
"message": {
"role": "ROLE_USER",
"messageId": "msg-1",
"parts": [{ "text": "Summarize the A2A spec in three bullets." }]
}
}
}'
```
`SendMessage` waits for the turn to finish and returns the task with the agent’s reply as a `response` artifact. Set `"configuration": { "returnImmediately": true }` to get the task back at once and follow it with `GetTask`, `SubscribeToTask`, or a push notification.
The `A2A-Version` header picks the wire format: `1.0`, or `0.3` for older clients. Without it, 1.0 method names such as `SendMessage` are answered in 1.0 and 0.3 names such as `message/send` in 0.3.
Clients that speak A2A’s plain HTTP binding (HTTP+JSON) use paths below the same URL instead of a JSON-RPC envelope. The Agent Card lists both bindings. This binding is A2A 1.0 only:
```bash
curl -sS -X POST "$EVERRUNS/v1/channels/$CHANNEL_ID/a2a/message:send" \
-H "Authorization: Bearer $KEY" \
-H 'Content-Type: application/a2a+json' \
-d '{
"message": {
"role": "ROLE_USER",
"messageId": "msg-1",
"parts": [{ "text": "Summarize the A2A spec in three bullets." }]
}
}'
```
| HTTP+JSON | Operation |
| ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `POST message:send`, `POST message:stream` | `SendMessage`, `SendStreamingMessage` |
| `GET tasks/{id}`, `GET tasks?…`, `POST tasks/{id}:cancel`, `POST tasks/{id}:subscribe` | `GetTask`, `ListTasks`, `CancelTask`, `SubscribeToTask` |
| `POST`/`GET tasks/{id}/pushNotificationConfigs`, `GET`/`DELETE tasks/{id}/pushNotificationConfigs/{configId}` | The push notification config operations |
Errors come back with the matching HTTP status and a `google.rpc.Status` body whose `details[0].reason` names the A2A error, for example `TASK_NOT_FOUND`.
### Supported methods
| A2A 1.0 | A2A 0.3 | Notes |
| -------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SendMessage` | `message/send` | A `taskId` or `contextId` from an earlier reply continues that conversation. |
| `SendStreamingMessage` | `message/stream` | Server-sent events: the task, then the reply as an artifact, then the final status. Needs `session_mode: session_per_invocation`; a `shared_session` channel answers `-32004`. |
| `GetTask` | `tasks/get` | Current state and the latest turn’s reply. |
| `ListTasks` | `tasks/list` | This channel’s tasks, newest first, filtered by `contextId`, `status`, or `statusTimestampAfter`, with `pageSize` and `pageToken` paging. |
| `SubscribeToTask` | `tasks/resubscribe` | Reattach a stream to a running task. A finished task answers `-32004`. |
| `CancelTask` | `tasks/cancel` | Cancels the running turn. A finished task answers `-32002`. |
| `CreateTaskPushNotificationConfig`, `Get…`, `List…`, `Delete…` | `tasks/pushNotificationConfig/set`, `get`, `list`, `delete` | Webhooks for a task. See below. |
The extended Agent Card is not offered (`-32007`).
A task’s id is the id of the Everruns session that runs it, and its `contextId` is the same value. A caller can only see and continue tasks started through its own channel.
### Push notifications
Register a webhook on a task, or pass one in `SendMessage` as `configuration.taskPushNotificationConfig`:
```json
{
"jsonrpc": "2.0",
"id": 2,
"method": "CreateTaskPushNotificationConfig",
"params": {
"taskId": "",
"id": "my-hook",
"url": "https://hooks.example.com/a2a",
"token": "opaque-value-you-check",
"authentication": { "scheme": "Bearer", "credentials": "hook-secret" }
}
}
```
When the task completes, fails, is canceled, or stops to ask a question, Everruns POSTs the full task (`{ "task": … }`, `Content-Type: application/a2a+json`) to each registered URL. The `token` arrives as `X-A2A-Notification-Token` and `authentication` as `Authorization: {scheme} {credentials}`. Both are stored encrypted and are never returned by `Get` or `List`.
A task holds at most ten configs. URLs must be public `https`; private, loopback, and cloud metadata addresses are rejected. A failed delivery is retried twice and dropped on a 4xx other than 429, so treat `GetTask` as the source of truth.
### Questions and approvals
When the agent asks a question with `ask_user`, the task goes to `input-required`. The status message carries the question as text and as an `everruns/ask_user` data part with a JSON Schema for the answer. Answer it with `SendMessage` on the same `taskId`. A question that asks for a secret reports `auth-required` instead and links to the session, so a person provides the value in Everruns rather than through another agent.
### Personal agents (PACT)
[PACT](https://github.com/openpactprotocol/openpactprotocol) (Personal Agent Consent and Trust) is how a person’s own agent, such as an assistant on their phone, talks to a company’s agent on their behalf. Everruns implements the PACT Identity profile. Add `pact` to an A2A channel’s config to serve it:
```json
{
"pact": {
"audience": "everruns-acme",
"personal_agents": [
{ "issuer": "https://pa.example", "jwks_uri": "https://pa.example/.well-known/jwks.json" }
]
}
}
```
| Field | Description |
| -------------------------------------- | ---------------------------------------------------------------------------------------- |
| `audience` | The value personal agents put in the token’s `aud`. Use the same value on every channel. |
| `personal_agents[].issuer` | The personal agent’s `iss`, matched exactly. Any other issuer is refused. |
| `personal_agents[].jwks_uri` or `jwks` | Where its public keys are: an HTTPS URL, or the JWKS document inline. |
| `personal_agents[].enabled` | `false` refuses that personal agent. Defaults to `true`. |
The channel is then also served at `/v1/channels/{channel_id}/a2a/pact`, with its PACT Agent Card at `/v1/channels/{channel_id}/a2a/pact/.well-known/agent-card.json`. Each request carries a short-lived ES256 or RS256 JWT that the personal agent signs for one of its users (`sub`). `message:send` answers with the agent’s reply as a Message. Its `contextId` continues the conversation for that same user only, and a retried `messageId` returns the stored reply instead of running the agent again. There are no tasks, streaming or push notifications on this URL. The channel’s ordinary A2A URL keeps working with its own key.
#### Acting on the user’s account (PACT Delegated)
With `pact.delegation`, the user can let their personal agent act on their account with your company. The user signs in on your own login page, picks what to allow on an Everruns consent page, and the personal agent receives a delegation token for exactly those permissions (OAuth 2.0 device code).
```json
{
"pact": {
"audience": "everruns-acme",
"personal_agents": [{ "issuer": "https://pa.example", "jwks_uri": "https://pa.example/.well-known/jwks.json" }],
"delegation": {
"brand_name": "Acme",
"login_url": "https://acme.example/pact/login",
"login_issuer": "https://acme.example",
"login_jwks_uri": "https://acme.example/.well-known/jwks.json",
"connected_url": "https://acme.example/pact/connected",
"mcp_server": "acme-account",
"scopes": [
{ "id": "orders:read", "description": "See your orders", "tools": ["mcp_acme_account__list_orders"] },
{ "id": "orders:cancel", "description": "Cancel your orders", "tools": ["mcp_acme_account__cancel_order"] }
]
}
}
}
```
| Field | Description |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `login_url` | Your login page. The user arrives with `return_to` set to the Everruns consent page. After signing them in, your site POSTs a form field `assertion` to that URL: an ES256 or RS256 JWT with `iss`, `aud` (the consent URL), `sub` (your user id), `jti`, `iat`, `exp` (at most five minutes) and `user_code` (from `return_to`). |
| `login_issuer` | The assertion’s `iss`, matched exactly. |
| `login_jwks_uri` or `login_jwks` | The keys you sign assertions with: an HTTPS URL, or the JWKS document inline. |
| `connected_url` | Optional. Where the user lands afterwards, with `status=approved` or `denied`, `scope` and `client` added. |
| `mcp_server` | Optional. The org’s MCP server for your account API. Attach it to the agent with `actsAs: user`; during a delegated turn the user’s token is its bearer token. |
| `scopes[]` | The permissions offered: `id`, the `description` the user sees, and the agent `tools` each one unlocks. |
| `brand_name` | Optional. Your name on the consent page. Defaults to the agent’s name. |
Login and connected pages may use plain `http://` on `localhost` for local development.
The OAuth endpoints live under `/v1/channels/{channel_id}/a2a/pact/oauth/`, with metadata at `.well-known/oauth-authorization-server` and the signing keys at `jwks.json`. Your account API verifies the delegation tokens against those keys: `typ` is `at+jwt`, `iss` is the `oauth` URL, `aud` the endpoint URL, `sub` your user id, and `scope` the granted permissions. Check the scope on every call.
The personal agent sends the token in `X-A2A-User-Delegation: Bearer …` beside its own JWT. The turn then runs as that user. If the agent calls a tool a scope lists and the user has not granted that scope, the answer is a task in `TASK_STATE_AUTH_REQUIRED` whose metadata names the missing scopes (`pact.missingScopes`) and a sign-in link asking for them (`pact.verificationUriComplete`). Every reply under a token carries a signed receipt in `metadata["pact.receipt"]` listing the scoped tools that ran. A conversation started for one of your users does not continue with another user’s token.
## Delegate to external A2A agents
The `a2a_agent_delegation` capability gives an agent a `spawn_agent` target of type `external_a2a`. The agents it may call are fixed in the capability’s configuration, so the model can never reach a URL you did not list:
```json
{
"agents": [
{
"id": "research",
"name": "Research agent",
"description": "Researches a topic and returns notes.",
"base_url": "https://agents.example.com/research"
}
]
}
```
`base_url` is where the Agent Card is resolved (`{base_url}/.well-known/agent-card.json`). The model then calls:
```json
{
"instructions": "Research tide pools and return five bullet notes.",
"target": { "type": "external_a2a", "id": "research" },
"mode": "foreground"
}
```
`foreground` waits for the remote task and returns its reply. `background` returns a `task_id` at once and wakes the session when the remote task finishes; the generic `wait_task`, `message_task`, and `cancel_task` tools work on it. Pass `result_schema` to require a structured result.
URLs are checked before every call: localhost, private ranges, and metadata addresses are refused, resolved addresses are pinned, and redirects are not followed. `allow_local_urls: true` lifts the address check only when `DEPLOYMENT_GRADE=dev`.
> **Status:** On the hosted platform, outbound delegation is experimental and available in Dev environments.
## A2A in the Framework
In a [Framework](https://everruns.com/docs/framework/) app (full guide: [Framework A2A](https://everruns.com/docs/framework/a2a/)):
* To **serve** agents over A2A, turn on the `a2a` feature of `everruns-serve`. Every top-level agent then answers at `POST /v1/channels/{agent}/a2a`, the same path shape as an Everruns channel. See [Serve](https://everruns.com/docs/framework/serve/#a2a).
* To **delegate** to A2A agents, turn on the `a2a` feature of `everruns` and add `CapabilityRef::new("a2a_agent_delegation")` with the config above.
The [A2A example](https://github.com/everruns/everruns/tree/main/examples/serve/a2a) example does both. A `researcher` agent is served over A2A, and a `writer` agent delegates research to it and drafts from its notes. It runs offline by default and on OpenAI when `OPENAI_API_KEY` is set:
```bash
cargo run -p serve-example-a2a --bin researcher # serves on :3000
cargo run -p serve-example-a2a --bin writer -- "tide pools"
```
## See also
* [Sub-agents](https://everruns.com/docs/capabilities/sub-agents/), the shared `spawn_agent` tool.
* [ARD Discovery](https://everruns.com/docs/integrations/ard/), for finding A2A agents at runtime.
* [Channels](https://everruns.com/docs/features/channels/), for channel lifecycle and legacy routes.
## Watch PACT account consent
A personal agent checks an order, receives a request for additional permission when cancellation is refused, and verifies the signed receipt after the customer approves. This is a local walkthrough with a demo client and synthetic store data.
[PACT account consent and signed receipts in Everruns](https://www.youtube-nocookie.com/embed/9FZiYv5PsWY?rel=0)
[Watch on YouTube](https://www.youtube.com/watch?v=9FZiYv5PsWY).
---
# Agent API
> Call one agent from your own code with an agent key. Reference for its base URL, keys, routes, auth, channel settings, streaming, retries, errors and SDKs.
Source: `. The credential decides who the **caller** is, and a caller sees only its own sessions.
| Credential | Caller | How to get it |
| ------------------------------------------------ | --------------------------------------------- | ----------------------------------------------------------- |
| Agent key `evr_ak_…` | The application holding the key | [Agent keys](#agent-keys) |
| Agent key with `end_user`, plus `End-User: ` | One of your application’s users | [End users](#end-users) |
| Runtime token | The end user it was minted for | [Runtime tokens for browsers](#runtime-tokens-for-browsers) |
| A token from your identity provider | The token’s subject, as an end user | [Your identity provider](#your-identity-provider) |
| Personal access token `evr_pat_…` | A member of your organization, as an end user | [Organization members](#organization-members) |
Keys of a retired `api_endpoint` channel (`evr_app_…`) were imported when the channel converted and keep working the same way as agent keys.
### End users
A key acting as itself is your application: every request it sends shares one set of sessions. To keep your users apart, create the key with `"permissions": ["end_user"]` and send `End-User` with each request:
```bash
curl -X POST "$EVERRUNS_AGENT_URL/sessions" \
-H "Authorization: Bearer $EVERRUNS_AGENT_KEY" \
-H "End-User: customer-42"
```
The ID is yours: up to 256 characters, no control characters and no leading or trailing spaces. Everruns creates an end user for it on first sight, scoped to the key, so two applications with different keys never collide on the same ID. Sessions an end user starts belong to that end user: the key acting as itself, or for another user, gets `404` for them. The Agent’s per-user connections (tools that act as the user) use that end user’s own connections, never the key holder’s.
`End-User` from a key without `end_user`, a malformed ID, or `End-User` sent with any credential other than an agent key answers `403`.
### Runtime tokens for browsers
Never ship an agent key in a browser or mobile app. Your backend exchanges it for a short-lived token for one user and hands the app that token:
```bash
curl -X POST "$EVERRUNS_AGENT_URL/runtime-auth" \
-H "Authorization: Bearer $EVERRUNS_AGENT_KEY" \
-H "End-User: customer-42"
```
```json
{
"access_token": "eyJhbGciOi…",
"token_type": "Bearer",
"expires_in": 900,
"virtual_user_id": "identity_01933b5a000070008000000000000001"
}
```
The token lasts 15 minutes, works only on this channel, and cannot be exchanged for another, so a leaked token cannot renew itself. `/runtime-auth` also accepts a token from one of the channel’s `auth_methods`. A key without `End-User` gets `400`: a key acting as itself is an application, not a user.
The page calls the channel with `Authorization: Bearer `. List the page’s origin in [`cors_origins`](#channel-settings) so the browser allows the cross-origin calls. Callers with a runtime token always get the public error codes.
### Your identity provider
`auth_methods` lists up to 5 identity providers whose access tokens the channel accepts besides agent keys: `oidc` (JWTs checked against the issuer’s discovery keys), `google_oidc` (Google Sign-In ID tokens) and `oauth2_introspection` (opaque tokens checked at an RFC 7662 endpoint). Each token’s subject becomes its own end user. Everruns only validates these tokens; it never issues them.
```json
{
"auth_methods": [
{
"mode": "oidc",
"provider": {
"type": "oidc",
"issuer": "https://login.example.com"
},
"requirements": {
"audiences": ["api://support-agent"],
"scopes": ["agent:invoke"]
}
}
]
}
```
`requirements` can also restrict `subjects`, `groups`, email `domains` and exact `claims` values. A token that matches no method answers `401`.
### Organization members
Set `org_members` to `true` to let members of your organization call the Agent with their own personal access token. Each member runs as their own end user with their own connections, as in the console. Only a full-access token counts: a read-only token answers `403` with `insufficient_scope`, because running an Agent is a write. Console session tokens are not accepted.
## Channel settings
Set these in the channel’s `channel_config`, or in the console form. Unknown fields are rejected.
| Setting | Default | Values and effect |
| ----------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `visibility` | `activity` | What event reads and the stream show. `messages`: user input, final assistant text, turn boundaries, and questions or approvals waiting on the caller. `activity`: adds tool start and finish with `tool_activity_text`, never tool names or arguments. `full`: the raw events, including tool names, arguments, results, reasoning and usage, for callers who own both ends. |
| `tool_activity_text` | `Working...` | The text a tool start shows under `activity`. |
| `errors` | `public` | `public`: a failed turn reports only one of the [public error codes](#errors-and-status-codes). `detailed`: the internal error and code, for key-authenticated developers. |
| `session_binding` | `per_user` | `per_user` or `session_per_invocation`. Either way each caller has its own sessions; sessions are never shared between callers. |
| `tool_approvals` | `operator` | Who answers tool calls the Agent’s approval gate holds back. `operator`: someone with access to the Agent in Everruns decides, and the caller sees only that a call waits. `caller`: the caller sees the tool and its arguments and decides through [`tool-approvals`](#questions-and-tool-approvals). |
| `rate_limit_per_minute` | none | Requests per minute per caller and client IP. Unset or `0` turns the channel’s own limit off; the global API limit still applies. |
| `daily_spend_limit_usd` | none | The most one caller (a key acting as itself, or one end user) may spend on this Agent per UTC day, up to 1,000,000. Past it, starting a session or sending a message answers `429` until the next UTC day; reads still work and a running turn finishes. |
| `cors_origins` | none | Up to 20 browser origins, such as `https://app.example.com`, whose pages may call this channel’s routes. Write each exactly as a browser sends it: `https` (or `http` for `localhost`, `127.0.0.1` and `[::1]`), no path, no trailing slash, no default port. These origins reach only this channel’s routes, never the management API. |
| `auth_methods` | none | Up to 5 identity providers. See [Your identity provider](#your-identity-provider). |
| `org_members` | `false` | Accept members’ personal access tokens. See [Organization members](#organization-members). |
## Routes
All routes take `Authorization: Bearer ` and answer JSON, except the stream.
| Method | Path | What it does |
| ------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/` | The agent card |
| POST | `/sessions` | Start a session |
| GET | `/sessions` | The caller’s sessions, most recently active first |
| GET | `/sessions/{session_id}` | One session, with what it waits on and its latest [work report](https://everruns.com/docs/features/work-reports/#in-the-agent-execution-api) |
| POST | `/sessions/{session_id}/messages` | Send a user message |
| GET | `/sessions/{session_id}/events` | Events, oldest first |
| GET | `/sessions/{session_id}/sse` | Follow events live over SSE |
| POST | `/sessions/{session_id}/question-answers` | Answer the Agent’s questions |
| POST | `/sessions/{session_id}/tool-approvals` | Allow or reject held-back tool calls |
| POST | `/sessions/{session_id}/cancel` | Cancel the running turn |
| POST | `/runtime-auth` | Mint a runtime token for an end user |
A session that belongs to another caller or another channel answers `404`, the same as one that does not exist.
### Get the agent card
`GET /` describes the Agent and which credentials the base URL accepts:
```json
{
"name": "Support agent",
"description": "Answers questions about orders.",
"streaming": true,
"input": {
"text": true,
"images": false,
"files": false
},
"auth": [
{
"type": "agent_key"
},
{
"type": "runtime_token"
},
{
"type": "oidc",
"issuer": "https://login.example.com"
}
],
"links": {
"sessions": "/api/v1/channels/appchan_01933b5a000070008000000000000001/sessions"
}
}
```
`auth` always lists `agent_key` and `runtime_token`, then `personal_access_token` when `org_members` is on, then one `oidc` entry per OpenID Connect issuer and `oauth2` for introspection. `input` says the Agent takes text, images and files ([Send files](https://everruns.com/docs/how-to/call-your-agent-from-code/#send-files)).
### Start a session
`POST /sessions` with an optional body:
```json
{
"title": "Order 42"
}
```
The title is at most 200 characters. An empty body is fine. `metadata` is not supported on Everruns and answers `400`. The session starts idle; send a message to start a turn. The response is `201` with a `Location` header and the session:
```json
{
"id": "session_01933b5a000070008000000000000001",
"title": "Order 42",
"status": "idle",
"created_at": "2026-10-13T09:00:00Z",
"updated_at": "2026-10-13T09:00:00Z"
}
```
`status` is `started`, `active`, `idle`, `waitingforinput` or `failed`. After a turn ends, `last_turn_status` is `completed`, `failed` or `cancelled`.
### List sessions
`GET /sessions?limit=50&page_token=…` returns `{"data": [...], "next_page_token": "…"}`. `limit` is 1 to 200, 50 by default. Pass `next_page_token` back as `page_token` for the next page; it is absent on the last page. A list leaves out `pending_questions` and `pending_approvals`.
### Get a session
`GET /sessions/{session_id}` returns the session plus `pending_questions` and `pending_approvals`: what the session waits on from the caller. See [Questions and tool approvals](#questions-and-tool-approvals).
### Send a message
`POST /sessions/{session_id}/messages` sends a user message. It starts a turn when the session is idle, or steers the running turn.
```json
{
"message": {
"role": "user",
"content": [
{
"type": "text",
"text": "Where is order 42?"
}
]
}
}
```
The role must be `user` and the content one or more `text` parts. The response is `201` with the stored message, including its `id`, `session_id`, `sequence`, `role` and `content`.
### Read events
`GET /sessions/{session_id}/events?after_sequence=0&limit=100` returns `{"data": [...]}`: the session’s events after `after_sequence` (exclusive), oldest first. `limit` is 1 to 500, 100 by default. To page, pass the last event’s `sequence` as the next `after_sequence`. Each event uses the [event envelope](https://everruns.com/docs/event-reference/), filtered by the channel’s [visibility](#what-callers-see).
### Cancel a turn
`POST /sessions/{session_id}/cancel` cancels the running turn and answers `{"status": "cancelled", "message": "Turn cancelled"}`. The stream then shows `turn.cancelled`.
## Streaming
`GET /sessions/{session_id}/sse` follows a session’s events live as Server-Sent Events. It uses the same framing as the session API’s stream (event data shortened here):
```text
event: connected
data: {"status":"connected"}
event: output.message.completed
id: event_01933b5a000070008000000000000009
data: {"id":"event_01933b5a000070008000000000000009","type":"output.message.completed","sequence":9,"data":{"message":{"role":"assistant","content":[{"type":"text","text":"Order 42 shipped yesterday."}]}}}
: heartbeat
event: disconnecting
data: {"reason":"connection_cycle","retry_ms":100}
```
* The SSE `event:` name is the event type, and `data:` is the event envelope after visibility.
* Durable events carry an `id:`. To resume after a drop, reconnect with `since_id` set to the last `id` you received.
* `after_sequence` replays events after that sequence first, then continues live. A client that holds no events yet passes `after_sequence=0` to replay the whole session; without either parameter the stream starts live and can miss a turn that ends quickly.
* A heartbeat comment arrives while nothing happens.
* The server cycles each connection every 5 minutes. It sends `disconnecting` first; reconnect right away with `since_id`.
Open streams are capped per organization and per session; past the cap the stream answers `429`. The SDKs’ `stream_events` handles reconnection for you; see [Stream events](https://everruns.com/docs/how-to/stream-events/).
## What callers see
`visibility` filters both `GET …/events` and the stream, before anything is written.
| Event type | `messages` | `activity` | `full` |
| -------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- |
| `input.message`, `output.message.completed` | Text parts only | Text parts only | Raw |
| `turn.started`, `turn.completed`, `turn.cancelled` | `turn_id` only | `turn_id` only | Raw |
| `turn.failed` | Per `errors` | Per `errors` | Raw, with public errors when `errors` is `public` |
| `tool.call_requested` | Only questions and approvals waiting on the caller | Same | Raw |
| `tool.started`, `tool.completed` | Hidden | `tool_call_id` with `activity` text, or `success` | Raw |
| Everything else (reasoning, usage, deltas) | Hidden | Hidden | Raw |
Under `messages` and `activity`, intermediate assistant commentary is dropped, an event keeps only `id`, `type`, `ts`, `session_id`, `sequence`, `context` and its filtered `data`, and event metadata and tags are removed.
## Questions and tool approvals
When the Agent asks a question with [`ask_user`](https://everruns.com/docs/capabilities/ask-user/), or its [tool approval](https://everruns.com/docs/capabilities/tool-approval/) gate holds a call back, the session waits and `GET /sessions/{session_id}` lists what it waits on. The stream carries the same as a `tool.call_requested` event at every visibility.
```json
{
"id": "session_01933b5a000070008000000000000001",
"status": "waitingforinput",
"created_at": "2026-10-13T09:00:00Z",
"updated_at": "2026-10-13T09:01:00Z",
"pending_questions": [
{
"tool_call_id": "toolu_01933b5a00007000800000000000001",
"questions": [
{
"kind": "choice",
"id": "target",
"header": "Environment",
"question": "Which environment should I check?",
"multi_select": false,
"allow_other": true,
"options": [
{
"label": "Staging",
"description": "The staging cluster",
"default": false
},
{
"label": "Production",
"description": "The live cluster",
"default": false
}
]
}
],
"expires_at": "2026-10-13T09:31:00Z"
}
],
"pending_approvals": [
{
"tool_call_id": "tool_approval_toolu_01933b5a00007000800000000000002",
"answerable": true,
"tool_name": "refund_order",
"arguments": {
"order_id": "42"
},
"risk": "destructive",
"expires_at": "2026-10-13T09:31:00Z"
}
]
}
```
**Answer questions** with `POST /sessions/{session_id}/question-answers`:
```json
{
"tool_call_id": "toolu_01933b5a00007000800000000000001",
"status": "answered",
"answers": [
{
"id": "target",
"selected": ["Staging"]
}
]
}
```
`tool_call_id` is optional when only one question set waits. `status` is `answered` (the default) or `declined`. Each answer names the question `id`, the chosen option labels in `selected`, and free text in `other_text` for a `text` question or a choice that allows another answer. The response is `{"status", "answered_by", "session_status"}` and the turn resumes. A question that asks for a credential (`kind: "secret"`) cannot be answered over this API, only declined; a person completes it in Everruns. Answers that do not match what was asked answer `400`; a session that is not waiting, or a set already answered, answers `409`.
**Approve tool calls** with `POST /sessions/{session_id}/tool-approvals`, on a channel whose `tool_approvals` is `caller`:
```json
{
"decisions": [
{
"tool_call_id": "tool_approval_toolu_01933b5a00007000800000000000002",
"decision": "allow"
}
]
}
```
`decision` is `allow`, `allow_always` (this call and later calls of the same tool in this session), `reject` or `reject_always`. A pending request of the same batch that is left out is settled as not approved; silence never approves. The response lists how each request was settled in `resolved` (`tool_call_id`, `tool`, `outcome`) with the session `status`. When `tool_approvals` is `operator`, approvals show `answerable: false` without the tool name, arguments or risk, and this route answers `403`. A request that expired or was already answered answers `409`.
## Safe retries
`POST /sessions` and `POST /sessions/{session_id}/messages` accept an `Idempotency-Key` header of 1 to 255 printable ASCII characters. A retry with the same key and the same request within 24 hours returns the first response with `Idempotent-Replayed: true` instead of starting a second session or sending the message twice.
* The same key on a different request answers `422` with `idempotency_key_reused`.
* A retry while the first request is still running answers `409` with `idempotency_key_in_progress`.
* Keys belong to the caller, so two applications or two end users never collide on one key.
* Only a success is remembered. A failed request frees its key, so you can fix the request and retry with the same key.
## Errors and status codes
Errors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details (`application/problem+json`) with `title`, `status` and `detail`, and a `code` where one applies.
| Status | When |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | Invalid body or query (bad `limit` or `page_token`, non-text content, `metadata`), a credential in a question answer, `/runtime-auth` with a key and no `End-User`, or a retired `api_endpoint` request shape (`api_endpoint_retired`) |
| `401` | Missing or invalid credential, including a token none of the channel’s `auth_methods` accepts, or a personal access token when `org_members` is off |
| `403` | The channel is not live, its Agent is inactive or its exposures are suspended (`This agent is not available`); `End-User` not allowed; a read-only personal access token (`insufficient_scope`); or `tool-approvals` on an `operator` channel |
| `404` | No such `api` channel, or a session that is not the caller’s |
| `409` | Nothing to answer, an answer already given, or an `Idempotency-Key` still in progress |
| `422` | An `Idempotency-Key` reused for a different request |
| `429` | The channel’s rate limit, the caller’s daily spending limit, or too many open streams |
The checks run in a fixed order: the channel resolves and is live, then the credential, then the rate limit, then the session. A bad key and a missing channel give the same generic answer, so a caller cannot probe which channels exist.
A turn that fails shows up as a `turn.failed` event rather than an HTTP error. With `errors: "public"`, which callers with a runtime token always get, its `data` carries only `turn_id`, a public `error` message and one of four `error_code` values: `rate_limited`, `service_unavailable`, `request_too_large` or `internal_error`. With `detailed`, it carries the internal `error` and `error_code`.
## SDKs
The Python, TypeScript and Rust SDKs have an `AgentClient` for the Agent API. Use `everruns-sdk` 0.3.1 or later. It reads `EVERRUNS_AGENT_URL` and `EVERRUNS_AGENT_KEY` from the environment, or takes them as arguments, and sends the credential as a Bearer token.
```python
from everruns_sdk import AgentClient
async with AgentClient() as agent:
# One call: start a session, send, follow the stream, return the reply.
print(await agent.run("Where is order 42?"))
# Or step by step, with a safe retry key.
session = await agent.create_session("Order 42", idempotency_key="order-42-start")
await agent.send_message(session["id"], "Where is order 42?", idempotency_key="order-42-msg-1")
async for event in agent.stream_events(session["id"], after_sequence=0):
if event.type == "turn.completed":
break
# Act for one of your users, and mint a token for their browser.
alice = agent.for_end_user("customer-42")
await alice.run("Where is my order?")
token = await alice.runtime_token()
```
```typescript
import { AgentClient } from "@everruns/sdk";
const agent = new AgentClient(); // EVERRUNS_AGENT_URL + EVERRUNS_AGENT_KEY
console.log(await agent.run("Where is order 42?"));
const session = await agent.createSession({ title: "Order 42", idempotencyKey: "order-42-start" });
await agent.sendMessage(session.id, "Where is order 42?", { idempotencyKey: "order-42-msg-1" });
for await (const event of agent.streamEvents(session.id, { afterSequence: 0 })) {
if (event.type === "turn.completed") break;
}
const alice = agent.forEndUser("customer-42");
const token = await alice.runtimeToken();
```
```rust
use everruns_sdk::AgentClient;
let agent = AgentClient::from_env()?; // EVERRUNS_AGENT_URL + EVERRUNS_AGENT_KEY
println!("{}", agent.run("Where is order 42?", None).await?);
let session = agent.create_session(Some("Order 42"), Some("order-42-start")).await?;
agent.send_message(&session.id, "Where is order 42?", Some("order-42-msg-1")).await?;
let alice = agent.for_end_user("customer-42");
let token = alice.runtime_token().await?;
```
The client also has `card`, `list_sessions`, `get_session`, `list_events`, `cancel`, `answer_questions` and `submit_tool_approvals` (camelCase in TypeScript). `run` raises an error when the turn fails. Calling an Agent through the management client’s `sessions.create` and `messages.create` still works but is deprecated. See [SDKs](https://everruns.com/docs/features/sdk/).
## The same API on serve
A [serve](https://everruns.com/docs/framework/serve/) app serves the same routes and shapes for each top-level agent at `/v1/channels/{agent}`, so a client written for one host works against the other: point `EVERRUNS_AGENT_URL` at either. A serve app is one operator’s process rather than a multi-tenant platform, so some parts differ:
* **Credentials.** With no method configured the API is open. Static keys come from `SERVE_API_KEYS` (comma separated) or `[auth]` in `serve.toml`, and `oidc`, `google_oidc` and `oauth2_introspection` methods use the same verifier and requirements as a channel’s `auth_methods`. Keys are not managed through an API, and there is no `End-User`, `/runtime-auth` or personal access token.
* **Callers are not separated.** Every authenticated caller reaches every session of the agent, as an operator would. A session is still reachable only under its own agent’s base URL.
* **Public card.** `GET /v1/channels/{agent}` needs no credential; its `auth` list names the accepted methods, and its `links` add the agent’s AG-UI and A2A routes.
* **No channel settings.** Events are not filtered by visibility, the caller answers tool approvals, and there are no spending or rate limits, browser origins or `Idempotency-Key` handling.
* **Messages.** `content` takes text parts only; send images and other files in `files`, which serve keeps in the session’s `/attachments` folder as the server does.
* **Sessions.** `POST …/sessions` accepts `metadata`, and `GET …/sessions` returns up to `limit` sessions with no `page_token`.
See [Serve](https://everruns.com/docs/framework/serve/#one-agents-api) and the [serve tutorial](https://everruns.com/docs/framework/serve-tutorial/), which calls an agent with `AgentClient`.
## Migrating from `api_endpoint`
The former `api_endpoint` channel type converted to Agent API channels, keeping keys and sessions. Requests in the old shape answer `400` with `api_endpoint_retired`: starting a session no longer takes a message, and a message is an object, not a string. `/v1/apps/{app_id}/api/{channel_id}/…` routes answer `410`. Create the session, then send `{"message": {"role": "user", "content": [...]}}` to `…/messages`.
## See also
* [Call your agent from code](https://everruns.com/docs/how-to/call-your-agent-from-code/): the step-by-step guide.
* [Channels](https://everruns.com/docs/features/channels/): every channel type and the shared lifecycle.
* [Stream events](https://everruns.com/docs/how-to/stream-events/): reconnection patterns.
* [Handle errors and cancel turns](https://everruns.com/docs/how-to/handle-errors-and-cancellation/).
* [Event Reference](https://everruns.com/docs/event-reference/): every event type.
* [API reference](https://everruns.com/docs/api/): the generated reference for every route.
---
# Agent Checks
> Advisory quality checks for agent configurations, structural problems, completeness gaps, and cost warnings surfaced while you build.
Source: --revision N` shows the configuration that ran. Versions saved before the change were moved into the agent’s history as revisions, in the order they were created, with the version’s summary as the reason. A channel or trigger that was pinned to a version now runs the current agent, and the pinned configuration is one restore away.
## Manager context
Manager context is one markdown document per entity (up to 16 KiB) with a revision that increases on every write.
```bash
everruns context get agent_01h9
everruns context append agent_01h9 --text "Answers must stay suitable for children." --reason "Product review"
everruns context set agent_01h9 --content @notes.md --expected-revision 3
everruns context clear agent_01h9 --expected-revision 4
```
Reading or writing an entity’s context requires permission to manage that entity. Writes are recorded in the entity’s history like any other change. A write with `--expected-revision` that no longer matches fails with `manager_context_changed`, so two editors cannot silently overwrite each other. Deleting an entity deletes its context.
The context never reaches the entity’s own runtime. An agent’s sessions do not see their agent’s notes or history, so the notes cannot steer the agent they describe. Knowledge entries, eval cases and sessions have history but no context.
## Acknowledging context before a change
A change can say which context revision its author read, with `--context-revision` (CLI and agent shell), `"context_revision"` (commands envelope) or the `everruns-context-revision` header (REST):
* If the context has changed since that revision, the change is refused with `manager_context_changed`. The error’s `allowed_actions` says to re-read the context and decide again.
* If the entity has context and the change acknowledged none, the change goes through with a warning. The commands envelope returns it in `warnings`, and the CLI and agent shell print it on stderr.
```bash
everruns context get agent_01h9 | jq .revision # 5
everruns agents update agent_01h9 --name "Support bot" \
--context-revision 5 --reason "Rename agreed with support"
```
## In the UI
On an entity’s page, open the **⋯** menu at the end of the header:
* **History** lists the entity’s changes, newest first, with who made each one, the agent session it came through, the surface and the reason. Open an entry to compare it with the current state. Secrets show only as changed or unchanged. **Restore this point** asks for a reason and lists the secrets that keep their current values.
* **Manager notes** shows the entity’s manager context as markdown. Only people who manage the entity see this item. Edit the notes and save them with an optional reason. If someone else saved first, the save is refused and you are asked to reload.
The open sheet is part of the page address (`?sheet=history`, `?sheet=notes`), so a link reopens it. On the agent page, edit mode shows “This agent has manager notes” under the title when the agent has notes. Its save, archive and delete flows have an optional **Reason for this change** field.
## Agents
Platform Chat, the Platform capability and the `/mcp` server all tell agents the same rule: read an entity’s context before changing it, pass `--context-revision` with the revision read and a `--reason` with what the user asked for, and ask the user when a request conflicts with the recorded context. Agents treat context and history as data written by people in the organization, not as instructions.
A change an agent makes without a reason is refused: the command fails with the `reason_required` code and a `retry` action, and the agent retries with `--reason`. Built-in tools such as `spawn_agent` give their own reasons, so they keep working. This is the **Require reasons from agents** feature flag, on by default. An organization can turn it off to let those changes through with a warning that asks the agent to give a reason next time; the `everruns_entity_changes_without_reason_total` metric then counts them, by entity kind. People in the UI and scripts calling the API may always leave the reason out.
## See also
* [CLI](https://everruns.com/docs/features/cli/): global flags and the command surface.
* [Platform Chat](https://everruns.com/docs/built-ins/harnesses/platform-chat/): the built-in agent that follows these rules.
---
# Channels
> Expose an Agent to Slack, AG-UI clients, A2A agents, FCP callers, and Public Chat visitors through Agent-owned channels, each with its own lifecycle and auth.
Source: ` (default 300), `--no-stream` to queue without waiting.
## Output formats
Every command accepts `-o` / `--output`:
```bash
everruns agents list -o json
everruns agents list -o yaml
```
`--quiet` suppresses headers and prints only the essential identifier, useful for capturing IDs in shell variables.
## Platform commands
Every other command comes from the same command contract that agents use in their shell and through MCP `execute`, so the spelling, flags and validation are identical everywhere. Run `everruns --help`, `everruns --help` or `everruns --help` to browse them, or read the [CLI command reference](https://everruns.com/docs/reference/cli/), which is generated from the same help.
```bash
everruns agents triggers list --agent-id agent_...
everruns sessions participants add --session session_... --kind agent --agent-id agent_... --reason "Hand off to the reviewer agent"
everruns capabilities list --search web
# Plugins, skills and knowledge bases
everruns plugins install --marketplace-id --plugin-name --reason "Add the release tooling"
everruns skills create --skill-md @./SKILL.md --reason "Share the code-review checklist"
everruns knowledge-bases create --name "Product docs" --description "Published product documentation" --reason "Ground support answers in the docs"
```
These commands print the command’s JSON output (YAML with `-o yaml`). A text or JSON flag written `@path` is read from that local file, as in `--skill-md @./SKILL.md`; write `@@` for a value that really starts with `@`.
### Retries
Platform commands are safe to retry. The CLI retries a dropped connection or a gateway error itself, and the server runs a create or update at most once for the same request. A script that re-runs a whole command can get the same guarantee by setting a key it reuses for that one command:
```bash
EVERRUNS_IDEMPOTENCY_KEY="nightly-agent-$(date +%F)" everruns agents create --name nightly --system-prompt @./prompt.md
```
A repeat with the same key returns the first result. Reusing a key for a different request is an error, so use one key per command.
### Reasons and manager context
Every command that changes something takes `--reason "..."`, which is stored on the changed entity’s history entry. That includes `agents create`, `agents update`, `agents import` and `sessions create`. [Platform commands](#platform-commands) also take `--context-revision N`, which says which revision of the entity’s manager notes you read. `everruns history list ` shows who changed an entity and why. `everruns context get ` shows its notes. See [Change history](https://everruns.com/docs/features/change-history/).
## See also
* [CLI command reference](https://everruns.com/docs/reference/cli/): every command with its flags and a worked example.
* [Use in AI tools](https://everruns.com/docs/getting-started/use-in-ai-tools/): the Everruns plugin teaches coding agents these same commands.
* [Automate with the CLI](https://everruns.com/docs/how-to/automate-with-the-cli/): `jq`, quiet mode, scripting patterns.
* [Define agents as files](https://everruns.com/docs/how-to/define-agents-as-files/): file formats for `-f`.
* [SDK](https://everruns.com/docs/features/sdk/): the programmatic equivalent.
---
# Dreaming
> Consolidate completed agent experience into authorized Memory files, with bounded background work, source references, and durable recovery.
Source: --help`. Legacy native `tool_search` keeps its existing matcher and does not use this server-aware index.
By default, `tool_search` keeps its existing behavior. To opt into bounded schema disclosure, set `bounded` and the three limits on the capability:
```json
{
"ref": "tool_search",
"config": {
"bounded": true,
"max_active_tools": 32,
"max_active_bytes": 65536,
"max_result_bytes": 32768
}
}
```
The first two limits bound optional disclosed schemas only. Eager, client-side, and `never_defer` tools remain in addition to those limits, and fallback drivers may temporarily hold removals during a warm-prefix transition. Held definitions must still fit the combined native tool budget: eager definitions plus the configured optional count and byte limits. If a lower live budget no longer admits the held list, the runtime releases those removals immediately. `max_result_bytes` bounds schemas returned by a search. Discovery remains progressive: the model searches, receives schemas for a bounded set of operations, then calls those operations using their registered schemas. A search result does not create a second execution path. If matching schemas do not fit in one result, search asks the model to narrow the query instead of presenting omitted schemas as available. Removing an active schema does not remove its earlier transcript history; this feature does not set a cumulative history limit.
Tool search applies the current attachment and authorization rules before returning matches, and the shell catalog is built from the current turn’s visible-tool scope. Search, help, and invocation all stay within that scope; deferred child tools retain the scope of their server placeholder. The runtime checks authority again when an operation is called. Removing a server or revoking its connection therefore makes its operations unavailable even if a prior turn disclosed their names or schemas. When a server’s schema changes, refreshed discovery supplies its current definition; old arguments still go through current schema validation. A transient refresh failure may leave the last successful catalog available under the existing recovery policy. An authentication failure clears the cached catalog, and an incomplete page sequence is never published as a successful refresh.
## Native, CLI, and hybrid access
The same registered operation can be exposed as a native function, through the session’s `tools` command, or through both surfaces. Configure [`tools_in_shell`](https://everruns.com/docs/capabilities/tools-in-shell/) with `mode: "cli"` for the shell surface (the default), or `mode: "hybrid"` to retain native calls alongside the CLI. Hybrid mode alone keeps native schemas eager; to progressively reveal bounded native schemas, also enable bounded [`tool_search`](https://everruns.com/docs/capabilities/tool-search/):
```json
{
"capabilities": [
{ "ref": "tool_search", "config": { "bounded": true } },
{ "ref": "tools_in_shell", "config": { "mode": "hybrid" } }
]
}
```
With both capabilities configured, `tool_search` reveals selected native schemas while the same catalog is searchable and callable through `tools`. The CLI is useful when a script should chain operations or filter intermediate results; native calls are useful for one typed operation. Both routes use the same operation identity, schema validation, authorization, and execution policy.
When a CLI search matches deferred MCP servers, it loads at most eight per query. Other matching servers stay marked as not loaded for a later search. Each loaded server joins the shell catalog atomically; if it would exceed the 10,000-tool or 32 MiB catalog ceiling, none of that server’s tools are added.
MCP servers and plugins join the runtime’s operation registry when attached. Attaching, removing, or redefining one updates what the next search or CLI lookup can see. Existing authorization is checked during search and again during execution, including after a warm cache, session restart, or history compaction. Tool and prompt changes use the runtime’s existing incremental disclosure path; cache behavior can vary by provider and endpoint.
See [MCP](https://everruns.com/docs/features/mcp/) for server setup and [Tool Search](https://everruns.com/docs/capabilities/tool-search/) for provider-specific search modes.
## Run the synthetic example
The repository’s [Rust/Mira study](https://github.com/everruns/everruns/tree/main/evals/mcp-scale) includes a working paginated MCP server and an agent using the Framework’s production discovery and execution paths. From an Everruns checkout, provide `OPENROUTER_API_KEY` and run:
```bash
cd evals/mcp-scale
cargo run -- --offline-catalog
EVERRUNS_EVAL_TRIALS=1 EVERRUNS_EVAL_CONCURRENCY=1 \
cargo run -- --run --sample readonly-ticket \
--filter 'catalog_size=600,servers=1,' --runs-report /tmp/mcp-scale.jsonl
```
This runs the same read-only task through native, CLI, and hybrid surfaces using Muse Spark 1.3 Contributor. The fixture has 600 tools, returns 100 tools per page, and persists isolated synthetic state across MCP process launches. The scorer requires completed operations and checks that no mutation occurred; a model’s final answer alone cannot pass. Change the catalog size to `2000` to exercise a larger catalog. The study README documents the full matrix, stress measurements, and limitations.
---
# Model Context Protocol (MCP)
> Everruns is both an MCP server, exposing its agents and tools to external clients with OAuth 2.1, and an MCP client that registers remote servers as virtual capabilities.
Source: ` with its name and description, and loads the server’s tools when it needs them, by finding it with `tool_search` or calling that line. The tools are callable from the agent’s next step and stay loaded for the rest of the conversation. Off is the default, so existing agents are unchanged. A person’s own servers ([User MCP servers](https://everruns.com/docs/capabilities/user-mcp-servers/)) load on demand by default; a person can turn that off for one of their servers with its **Load tools on demand** switch in **Settings > My MCP servers**.
For catalogs with hundreds or thousands of operations, Everruns paginates discovery and supports bounded search and schema disclosure. See [Large MCP catalogs and tool surfaces](https://everruns.com/docs/features/large-mcp-catalogs/).
```json
{
"mcpServers": {
"linear": { "use": "catalog:linear", "actsAs": "user", "deferred": true }
}
}
```
A catalog entry can take the agent’s account from an existing connection instead of its own sign-in (`service_connection_provider`, **Agent credential** in the catalog form). The seeded `github` entry (`https://api.githubcopilot.com/mcp/`) uses the agent’s GitHub App, so an agent with a GitHub App needs no second GitHub login. A connection is only accepted for servers on its provider’s own hosts, so its tokens cannot be sent anywhere else.
GitHub’s MCP server accepts the App’s installation token, but that token acts as the App, not a person. It reaches only the repositories the App is installed on, with the App’s permissions, and tools about a person (`get_me`, notifications, starred repositories, “my” issues and pull requests) fail. For those, attach the server acting as `user` so the person signs in.
### Long-running tools
A call to an MCP tool fails if the server has not answered within 60 seconds. For a server whose tools take longer, such as one that runs a build or a deployment, set `tool_timeout_ms` on the attachment or catalog entry (**Tool call timeout** in the catalog form, in seconds). It accepts 1 second to 30 minutes. `timeout`, the key common `mcpServers` config files use, works as well. An attachment that uses a catalog entry may set its own timeout. If it does not, it uses the catalog’s timeout.
```json
{
"mcpServers": {
"ci": { "type": "http", "url": "https://ci.example.com/mcp", "tool_timeout_ms": 600000 }
}
}
```
A server that supports the [MCP Tasks extension](https://modelcontextprotocol.io/extensions/tasks/overview) does not need a longer timeout. Everruns declares the extension on every tool call, so such a server can answer with a task instead of holding the request open. The agent then checks on the task until it finishes, for up to 30 minutes. While it runs, the server’s status message (for example “Running tests”) shows on the tool call in chat and in the session’s events. Questions the task asks reach the agent’s user the same way as a server’s [form questions](#when-a-tool-needs-a-person). If the turn is cancelled or the wait runs out, Everruns cancels the task on the server.
### Waking an agent on a server’s events (experimental)
With the **MCP Events** flag on, an agent can also subscribe to events that one of its own MCP servers publishes, such as a tracker announcing new issues. Create an agent trigger with `trigger_type: "mcp_event"`, the attachment’s name in `mcp_server`, the event name from the server’s `events/list` in `mcp_event`, and any subscription arguments in `mcp_event_arguments`:
```bash
curl -X POST "$EVERRUNS_API/v1/agents/$AGENT_ID/triggers" \
-H "Content-Type: application/json" \
-d '{
"trigger_type": "mcp_event",
"mcp_server": "tracker",
"mcp_event": "issue.created",
"mcp_event_arguments": {"team": "eng"},
"message": "Triage {{payload.issue.title}}"
}'
```
Everruns subscribes with the agent’s credential for that attachment (its sign-in to the server, or the connection a catalog entry such as `github` names), a signing secret it generates, and a callback URL of its own; the server must accept webhook delivery. Each signed event starts a run with the event’s `data` as `{{payload}}`. Subscriptions are renewed before they expire and cancelled when the trigger is disabled or deleted. The attachment must act as the agent (`service` or `user_or_service`), not only as the calling user, since a trigger runs as the agent.
## Which tools ask before they run
In the normal approval mode, a tool that can change something asks a person before it runs. Everruns can’t see inside a remote tool, so most MCP tools ask by default, even ones that only read. You can tell Everruns what each tool does:
* **Read only**: the tool only looks things up. It never asks.
* **Changes**: the tool changes or sends something. It always asks.
Your label wins over what the server says about its own tools, and it stays when the server’s tool list changes. A tool with no label follows what the server says about it.
In the app, open **Settings > MCP catalog** and click **Tools** on a server. Each tool shows its description, what the server says about it, and a choice: **Default**, **Read only**, or **Changes things**.
**Suggest labels** asks a decision model to judge every tool that has no label yet. It only fills in a suggestion, such as “Suggested: read only”. Nothing changes until a person picks a choice or clicks **Use suggestion**.
The deployment’s decision model judges, unless your organization set **System decisions** to **This organization’s model**: then your organization’s default decision model judges, on your provider account. If that model is not usable, the button reports an error rather than using the deployment’s.
List a server’s tools with their labels, then set or clear one:
```bash
curl "$EVERRUNS_API/v1/mcp-servers/mcp_01h9/tools"
curl -X PUT "$EVERRUNS_API/v1/mcp-servers/mcp_01h9/tools/search_docs/label" \
-H "Content-Type: application/json" -d '{"label": "read_only"}'
```
Send `{"label": "changes"}` to always ask, or `{"label": null}` to remove the label. Setting a label needs the same permission as editing the server, and it removes the tool’s suggestion. To get suggestions, which come back with the tool list:
```bash
curl -X POST "$EVERRUNS_API/v1/mcp-servers/mcp_01h9/tools/suggest-labels"
```
Labels work on the other places an MCP server can live too:
* **An agent’s or harness’s own server** (one added by URL): put the labels in the server’s `tool_labels`, keyed by the tool’s own name. They win over a catalog server’s saved labels when the entry uses one.
```json
"mcpServers": {
"notes": {
"url": "https://notes.example.com/mcp",
"tool_labels": { "search": "read_only", "publish": "changes" }
}
}
```
* **Your own server** (one you added by URL under **My MCP servers**): click **Tools** on it. Everruns asks the server for its tools with your sign-in. A server you added from the catalog uses the catalog’s labels.
Servers added during a conversation never carry labels, because the agent can add them itself and a label only ever lets a tool run without asking.
## When a tool needs a person
Some MCP tools cannot finish without a human: a payment to authorize, an API key to paste, a consent screen to click. Under protocol `2026-07-28` the server hands back a URL instead of asking for the value, and Everruns holds the turn until someone answers. See [URL mode elicitation](https://everruns.com/docs/features/mcp-url-elicitation/).
A server can also ask the person a few structured questions (form mode elicitation), such as which environment to deploy to. This is off by default: set the server’s **Elicitation** setting (`elicitation_policy`) to `url_and_form` to allow it. The questions appear in the conversation marked as coming from that server, and the answer goes back to the server when the tool runs again. Everruns refuses questions that ask for a password or key, and declines on the person’s behalf if nobody answers in time. `none` stops a server eliciting at all.
## Use Everruns from your AI tools
To give Claude Code, Codex, Cursor or Gemini CLI the MCP server plus skills for building, debugging and shipping agents, install the [`everruns` plugin](https://github.com/everruns/plugins); see [Use in AI tools](https://everruns.com/docs/getting-started/use-in-ai-tools/).
## Related
* [URL mode elicitation](https://everruns.com/docs/features/mcp-url-elicitation/), tool calls that need a person
* [Capabilities](https://everruns.com/docs/features/capabilities/), how virtual capabilities fit the capability system
* [Slack Integration](https://everruns.com/docs/capabilities/slack/), publishing an Agent through a messaging endpoint
---
# URL mode elicitation
> When an MCP server needs a secret, an authorization or a payment, Everruns pauses the turn and a person finishes it in their browser, out of the model's sight.
Source: /api` for a self-hosted Platform. Create the token under **Settings** > **Personal Access Tokens**.
* Rust
```rust
use everruns_sdk::Everruns;
let client = Everruns::from_env()?; // EVERRUNS_API_KEY + EVERRUNS_API_URL
let client = Everruns::with_base_url("evr_pat_...", "https://app.everruns.com/api")?;
```
* Python
```python
from everruns_sdk import Everruns
client = Everruns() # EVERRUNS_API_KEY + EVERRUNS_API_URL
client = Everruns(api_key="evr_pat_...", base_url="https://app.everruns.com/api")
```
* TypeScript
```typescript
import { Everruns } from "@everruns/sdk";
const client = new Everruns(); // EVERRUNS_API_KEY + EVERRUNS_API_URL
const client = new Everruns({ apiKey: "evr_pat_...", baseUrl: "https://app.everruns.com/api" });
```
## API coverage
| Resource | Operations |
| ------------------- | -------------------------------------------------------------------------------------- |
| **Agents** | Create, list, get, apply, copy, delete, import, export, stats, versions, health checks |
| **Sessions** | Create, list, get, delete, cancel, resume, pin, export, set secrets, budgets |
| **Messages** | Create, list, submit client-side tool results |
| **Events** | List, stream (SSE) |
| **Capabilities** | List, get, guardrail dry runs |
| **Harnesses** | Create, list, search, get, update, delete |
| **Models** | List, get |
| **Workspaces** | Create, list, get, update, delete |
| **Workspace files** | List, read, create, update, delete, move, copy, grep, stat |
| **Memories** | Create, list, get, update, delete, sync, file operations |
| **Budgets** | Create, list, get, update, delete, top up, ledger, check |
| **Connections** | Set, list, remove |
Everything else (providers, MCP servers, organizations, schedules) is available through the [REST API](https://everruns.com/docs/api/).
## Error handling
| Error type | Description |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `AuthenticationError` | Invalid or missing API key (Python, TypeScript) |
| `NotFoundError` | Resource not found (Python, TypeScript) |
| `RateLimitError` | Rate limit exceeded (Python, TypeScript) |
| `ApiError` | General API error; Rust uses `Error::Api { status, .. }` for all HTTP errors and `Error::Auth` for credential problems |
* Rust
```rust
use everruns_sdk::Error;
match client.agents().get("invalid-id").await {
Ok(agent) => println!("Found: {}", agent.name),
Err(Error::Api { status: 404, message, .. }) => println!("Not found: {}", message),
Err(Error::Auth(msg)) => println!("Auth error: {}", msg),
Err(e) => println!("Other error: {}", e),
}
```
* Python
```python
from everruns_sdk import NotFoundError, AuthenticationError
try:
agent = await client.agents.get("invalid-id")
except NotFoundError as e:
print(f"Not found: {e}")
except AuthenticationError as e:
print(f"Auth error: {e}")
```
* TypeScript
```typescript
import { NotFoundError, AuthenticationError } from "@everruns/sdk";
try {
const agent = await client.agents.get("invalid-id");
} catch (e) {
if (e instanceof NotFoundError) {
console.log(`Not found: ${e.message}`);
} else if (e instanceof AuthenticationError) {
console.log(`Auth error: ${e.message}`);
}
}
```
## Do something
* [Build your first agent](https://everruns.com/docs/tutorials/building-agents-using-sdk/) — guided tutorial.
* [Call your agent from code](https://everruns.com/docs/how-to/call-your-agent-from-code/) — `AgentClient` with an agent key.
* [Stream events with the SDK](https://everruns.com/docs/how-to/stream-events/) — common streaming patterns.
* [Handle errors and cancel turns](https://everruns.com/docs/how-to/handle-errors-and-cancellation/) — graceful failure paths.
* [Orchestrate multi-agent pipelines](https://everruns.com/docs/how-to/orchestrate-multi-agent-pipelines/) — chain agents together.
## See also
* [API reference](https://everruns.com/docs/api/) — every endpoint, generated from OpenAPI.
* [Agent API](https://everruns.com/docs/features/agent-api/) — the routes `AgentClient` calls.
* [Event Reference](https://everruns.com/docs/event-reference/) — every event type.
* [GitHub Repository](https://github.com/everruns/sdk) — source code and examples.
## Overview video
[Everruns SDK Overview](https://www.youtube.com/embed/1FfGKUTzBzA)
---
# Session Participants
> Invite agents into a shared session, address a specific agent for a turn, and understand host, member, user, join, and leave behavior.
Source: `.
2. **Activation** (under 5,000 tokens): full SKILL.md instructions load when the agent calls `activate_skill`.
3. **Resources**: bundled files mount at `/workspace/.agents/skills/{name}/` and are read with the normal filesystem tools.
This keeps thousands of skills available to an agent without burning context on the ones it doesn’t need.
## Two ways to use skills
| Source | Where they live | When to use |
| ---------------- | ------------------------------------------------------------- | ---------------------------------------------------- |
| Workspace skills | `/.agents/skills/` in the session VFS | Project-specific skills; per-session experimentation |
| Registry skills | Organization-wide, in the [Skills Registry](#skills-registry) | Shared across agents; managed via API |
The built-in `skills` capability handles discovery and activation for both. Registry skills appear in the capability system as virtual capabilities (`skill:{uuid}`) that mount the skill into `/.agents/skills/{name}/`, where the `skills` capability finds it alongside workspace skills.
## Skills Registry
The **Skills Registry** stores skills at the organization level. Registry skills persist across sessions and can be assigned to any agent like any other capability, with ID `skill:{uuid}`. The organization must have the `skills` feature enabled.
### API surface
| Method | Path | Description |
| ------ | ------------------------- | -------------------------------------------- |
| POST | `/v1/skills` | Create from SKILL.md |
| POST | `/v1/skills/upload` | Create from ZIP archive |
| GET | `/v1/skills` | List |
| GET | `/v1/skills/usage` | How many agents and harnesses use each skill |
| GET | `/v1/skills/{id}` | Get metadata |
| GET | `/v1/skills/{id}/content` | Get full content |
| PATCH | `/v1/skills/{id}` | Update |
| DELETE | `/v1/skills/{id}` | Delete |
| POST | `/v1/skills/validate` | Validate without creating |
See the [API reference](https://everruns.com/docs/api/) for request and response schemas.
### ID formats
| Source | ID | Example |
| --------- | ------------------------------------ | -------------------------------------------- |
| Registry | `skill:{uuid}` | `skill:550e8400-e29b-41d4-a716-446655440000` |
| Workspace | Aggregated under `skills` capability | – |
### Dependencies
Registry skills automatically depend on `session_file_system` so bundled resources can be read after activation. You don’t need to add it explicitly.
### Security
* Archive uploads are validated against path traversal, ZIP bombs, and size limits.
* Skill instructions are returned as tool results, not injected into the system prompt, so they cannot bypass capability isolation.
* Skill names are unique per organization.
* Disabled skills are hidden from listings.
## Do something
* [Package and publish an agent skill](https://everruns.com/docs/how-to/package-a-skill/): author a SKILL.md, bundle scripts, and share it through the registry.
## See also
* [Agent Skills capability reference](https://everruns.com/docs/capabilities/agent-skills/): tools, dependencies, config.
* [SKILL.md format spec](https://agentskills.io/): upstream open spec.
---
# Management UI
> Manage agents, sessions, capabilities, settings, files, and event streams through the optional web interface.
Source: -2` (or the next free number).
Turn a server off to hide it from agents without losing your sign-in. Remove it to delete both the server and your sign-in. For a catalog server that sign-in is also the one agents acting as you use for the same catalog entry, so they ask you to connect again. Signing out from the connection alone keeps the server on your list, waiting for you to connect again.
## Let an agent use them
Add the **User MCP Servers** capability (`user_mcp`) to the agent. With its `use` setting on (the default), each turn adds the enabled servers of the person who sent the message. [Platform Chat](https://everruns.com/docs/built-ins/harnesses/platform-chat/) has it on.
The agent gets nothing from it when:
* **nobody is chatting**: a schedule, trigger or other unattended run has no person to act for;
* **more than one person is in the conversation**: in a shared session, one person’s tools would otherwise show up in everyone’s turns;
* **the agent already has a server with that name**: agent and capability servers always win, so an agent’s behaviour cannot be changed by a person adding a server with the same name;
* the server is turned off, or a catalog entry it came from was archived.
An OAuth server works for agents once you sign in to it; until then your list shows it as **Needs sign-in**.
The agent’s **MCP servers** sheet shows a **User servers of the person chatting** group with these settings, and lists any of your own servers the agent skips because one of its servers has the same name.
## Add and connect from chat
With the capability’s `manage` setting on, you can ask the agent instead of opening Settings, for example “add Linear and connect it”. The agent:
1. adds the server from your organization’s catalog, asking you to approve first when the agent’s [Tool Approval](https://everruns.com/docs/capabilities/tool-approval/) mode is `normal` or `protective`;
2. shows a **Connect** card, where you sign in in your own browser; the agent never sees your credentials;
3. can use the server’s tools from your next message.
The **Connect** card also works for the agent’s own servers: an agent with a server that acts as you (`user` or `user_or_service`) can show it without `manage`. A server that acts as the agent sends you to the agent’s **MCP servers** sheet instead, where only someone who manages MCP servers can sign the agent in.
It can also list, turn off, turn on (under the same approval policy) and remove your servers. It can add a server by URL only when the agent’s `allow_custom_urls` setting is on, and never with an API key or headers. These tools only ever change your own list, need you to be the one chatting, and do not work in conversations with several people. Platform Chat has `manage` on. Management adds no hard approval gate when Tool Approval is absent or set to `off`. Signing in through the Connect card remains a separate authorization step.
## API
The same operations are available over the API, for yourself (`me`) or, with virtual-user management permission, for an account you manage:
| Method | Path | Purpose |
| -------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `GET` | `/v1/virtual-users/{id}/mcp-servers` | List your servers and their sign-in state |
| `POST` | `/v1/virtual-users/{id}/mcp-servers` | Add a server (`{"catalog":"linear"}` or `{"name","url","auth_mode"}`) |
| `GET` | `/v1/virtual-users/{id}/mcp-servers/{server_id}` | Read one server |
| `PATCH` | `/v1/virtual-users/{id}/mcp-servers/{server_id}` | Rename, turn on or off, or replace the API key |
| `DELETE` | `/v1/virtual-users/{id}/mcp-servers/{server_id}` | Remove the server and your sign-in |
| `GET` | `/v1/virtual-users/{id}/mcp-servers/{server_id}/tools` | List a custom server’s tools, asked live, with your [risk labels](https://everruns.com/docs/features/mcp/#which-tools-ask-before-they-run) |
| `PUT` | `/v1/virtual-users/{id}/mcp-servers/{server_id}/tools/{tool}/label` | Label a custom server’s tool `read_only` or `changes`, or `null` to clear |
Sign in with `GET /v1/virtual-users/{id}/connections/{provider}/authorize`, where `provider` is the `connection.provider` value a server reports. The URL of a server cannot change; remove it and add it again instead.
```bash
curl -X POST "$EVERRUNS_URL/v1/virtual-users/me/mcp-servers" \
-H "Authorization: Bearer $EVERRUNS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"notes","url":"https://notes.example.com/mcp","auth_mode":"oauth"}'
```
## Security
* Another person’s server answers `404` on every route, and only the owner can start its sign-in. An agent’s own account can never hold a grant for it.
* Custom URLs go through the same address checks as catalog servers, so a user server cannot point at private or internal addresses.
* API keys and header values are write-only.
* A user server never appears in the organization catalog and cannot be attached to an agent by name.
---
# Voice
> Let people talk to an Everruns agent and hear its answers through a voice channel, with the same model, tools and instructions the agent uses for text.
Source: ,
}
struct Lookup;
#[capability::async_trait]
impl capability::Handler for Lookup {
type Input = LookupInput;
type Output = Record;
type Error = capability::Error;
fn name(&self) -> &str { "lookup_record" }
fn description(&self) -> &str { "Look up one record by exact id." }
fn hints(&self) -> capability::Hints {
capability::Hints::default()
.readonly(true)
.idempotent(true)
}
async fn execute(
&self,
input: Self::Input,
context: capability::Context,
) -> Result {
context.progress("Looking up the record").await;
if input.id != "rec_42" {
return Err(capability::Error::user(
"record_not_found",
"No record has that id",
).details(capability::serde_json::json!({ "id": input.id })));
}
Ok(Record {
id: input.id,
score: 0.98,
labels: vec!["verified".into()],
})
}
}
let records = capability::Definition::new(
"records",
"Records",
"Application-owned record lookup.",
)
.instructions("Use exact record ids and do not infer missing records.")
.metadata(capability::serde_json::json!({ "owner": "risk" }))
.tool(Lookup);
let agent = Agent::builder()
.instructions("Answer with verified record data.")
.provider(OpenAI::from_env()?)
.model("gpt-6.1-sol")
.capability(records)
.build()?;
```
Both input and output types must satisfy the compile-time protocol bounds. The generated schemas are available through `Definition::tools()[..].spec()` for tests, documentation, or a host catalog. Results are serialized directly to JSON, so structs, arrays, numbers, booleans, and null do not pass through a string conversion.
## Errors
Return `capability::Error::user(code, message)` for an expected domain failure. Add bounded JSON details when they help the model recover. The code, message, and details travel through the model-visible tool-error channel.
Return `capability::Error::internal(code, message)` for diagnostic details that are unsafe to show to the model, such as network internals or implementation bugs. The engine logs the diagnostic and gives the model a generic error; internal details do not cross the model boundary. Never include credential values or other secrets in any error because host logs may retain internal diagnostics.
Custom application error enums can implement `Into` and be used as `Handler::Error`.
## Context, progress, and cancellation
`capability::Context` exposes only stable lifecycle data:
* opaque session and workspace ids;
* the resolved locale, when present;
* best-effort correlated `tool.progress` events;
* a call-scoped cancellation signal.
Observe progress through `Session::events()` and `SessionEventKind::ToolProgress`. Everruns does not currently expose a custom capability result-streaming protocol; return one typed result when execution finishes.
Normal awaited work needs no cancellation branch. Cancelling a turn drops the handler future. Clone `context.cancellation()` only into child tasks, processes, or watchers that might otherwise survive after `execute` is dropped. The signal fires on cancellation and on every other call completion path.
## Security boundary
The advanced SPI intentionally does not export provider credentials, stores, tenant or organization objects, registries, payment authority, filesystem backends, or other host services. Pass application-owned clients or state into your handler struct when constructing the definition. A handler is trusted application code and retains whatever process authority those values provide; `Hints` describe behavior but do not enforce authorization, egress, or approval policy. Apply authorization, egress policy, timeouts, and input bounds at those application boundaries, and never place secrets in capability or tool metadata.
For a complete provider-backed program, run the [`advanced_capability` example](https://github.com/everruns/everruns/blob/main/crates/everruns/examples/advanced_capability.rs).
Some built-ins expect the application to supply behavior rather than configuration. `ask_user` is one: it needs someone to answer, so `AgentBuilder::ask_user` takes a responder instead of a config value. See [Answer agent questions](https://everruns.com/docs/framework/ask-user/).
---
# Serve AG-UI
> Stream a Framework session to CopilotKit or any AG-UI 1.0 client from your own HTTP server, with ask_user questions and tool approvals as interrupts.
Source: > {
let gate = InterruptGate::new();
let agent = Agent::builder()
.instructions("You are a helpful assistant.")
.provider(OpenAI::from_env()?)
.model("gpt-6.1-sol")
.ask_user(gate.clone())
.approver(gate.clone())
.build()?;
let handler = AgUiHandler::new(
AgUiThreads::new(Engine::new(), agent),
StaticToken::bearer(std::env::var("AG_UI_TOKEN")?),
)
.options(AgUiOptions::new().gate(gate));
let router = Router::new().route("/ag-ui", handler.route());
let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await?;
axum::serve(listener, router).await?;
Ok(())
}
```
Each request is authorized, its `threadId` resolved to a session with `AgUiThreads` (the first run of a thread creates one from your agent, later runs reopen it), and the run streamed as server-sent events: one unnamed `data: ` event per AG-UI event and a `: keepalive` comment every 15 seconds. Everything that can fail does so before the stream opens:
| Status | When |
| ------ | ---------------------------------------------------------------------------------------------- |
| `401` | The authorizer refuses the request. The body is not read. |
| `400` | The body is not a `RunAgentInput`, the `threadId` is invalid, or the run cannot use the input. |
| `500` | The thread store or the session failed. The detail is logged, not returned. |
Errors are `application/problem+json`. Once the stream is open, a failure is the run’s own `RUN_ERROR`. Request bodies are capped by axum’s default 2 MB limit.
### Authorization
`AgUiHandler::new` takes an authorizer, so an open endpoint is a choice you write down:
* `StaticToken::bearer(token)` accepts `Authorization: Bearer `, and `StaticToken::header(name, token)` a custom header. Tokens are compared in constant time; a refusal carries `WWW-Authenticate: Bearer` for the bearer form.
* `Unauthenticated` accepts everything: for local development, or behind a proxy that already authenticates.
* Any `Fn(&HeaderMap) -> Result`, or your own `AgUiAuthorizer` implementation when the check needs to await.
The authorizer returns an `AgUiCaller`. `AgUiCaller::scoped(user_id)` gives each caller its own threads, so one user cannot continue another’s conversation by sending its `threadId`:
```rust
use axum::http::HeaderMap;
use everruns::ag_ui::{AgUiCaller, Unauthorized};
// Your proxy has verified the user and set this header.
let by_user = |headers: &HeaderMap| {
headers
.get("x-user-id")
.and_then(|value| value.to_str().ok())
.map(AgUiCaller::scoped)
.ok_or_else(Unauthorized::new)
};
let handler = AgUiHandler::new(threads, by_user);
```
### Your own route
On another HTTP server, or to resolve sessions yourself, call `Session::ag_ui_with` (or `AgUiThreads::run`) and frame the stream. With `ag-ui-axum`, `sse_response(run)` does the framing; without it, each event is `serde_json::to_string(&event)` in a `data:` line.
The crate’s `ag_ui_axum` example is the handler on the offline simulated model:
```bash
cargo run -p everruns --features ag-ui-axum --example ag_ui_axum
```
Point any AG-UI client at the route:
```ts
import { HttpAgent } from "@ag-ui/client";
const agent = new HttpAgent({
url: "http://127.0.0.1:3000/ag-ui",
headers: { Authorization: `Bearer ${token}` },
});
```
## Threads across restarts
`AgUiThreads::new` keeps its thread map in memory. To keep threads when the process restarts, keep both halves on disk: the sessions, with an agent on the `local` backend, and the map, with `SqliteThreadStore` (both need the `local` feature):
```rust
use everruns::ag_ui::{AgUiThreads, SqliteThreadStore};
use everruns::{Agent, Engine, LocalConfig, OpenAI};
let config = LocalConfig::new("/var/lib/my-app");
let agent = Agent::builder()
.instructions("You are a helpful assistant.")
.provider(OpenAI::from_env()?)
.model("gpt-6.1-sol")
.local(config.clone())
.build()?;
let threads = AgUiThreads::with_store(Engine::new(), agent, SqliteThreadStore::local(&config)?);
```
After a restart the next run of a thread reopens its session, history included. Implement `ThreadStore` to keep the map in your own database instead.
With durable session hosting (`SqliteHosting`), use `AgUiThreads::hosted` and a registered build instead of an Agent value. Each new thread is created through the authority, at an identity derived from the thread, so a retried first run reuses the same session. Threads whose sessions were moved from the `local` backend with `Engine::cut_over_legacy_session` keep answering from those same sessions:
```rust
let threads = AgUiThreads::hosted(engine, build, SqliteThreadStore::local(&config)?);
```
A thread id is chosen by the client, and anyone who knows one continues that conversation. When one server serves several users, scope threads to the authenticated caller: `AgUiCaller::scoped` does it in `AgUiHandler`, and `run_in` on your own route:
```rust
let run = app.threads.run_in(&user_id, input, options).await?;
```
Thread ids must be 1 to 128 characters of `[A-Za-z0-9-_.]`; anything else is `AgUiError::InvalidInput`.
## History the client already has
A client such as CopilotKit keeps the conversation and sends all of it with every run. When a thread is new to the server, for example after a restart without a durable backend, `AgUiThreads` records the input’s earlier user and assistant messages as the new session’s history before the run’s user message, so the agent picks up where the conversation was. Once the session has history, the earlier messages are not read again: the session’s own conversation wins.
Only user and assistant text is seeded (an assistant’s tool calls as text); `tool`, `system`, `developer`, activity and reasoning messages are not. The most recent 256 messages and 512 KiB of text are kept. On a session you resolve yourself, turn it on with `AgUiOptions::seed_history(true)` for a thread’s first run. The client writes these messages, assistant turns included, so treat them as no more trusted than the user message.
## Questions and approvals become interrupts
In the Framework, `ask_user` questions and tool approvals are answered by responders on the agent while the turn waits. `InterruptGate` is a responder for both that answers through AG-UI instead: register it with `.ask_user(...)` and `.approver(...)`, and pass it with `AgUiOptions::gate`. A question or approval then ends the run with the 1.0 interrupt outcome while the turn stays parked in your process:
| Parked on | `reason` | Answer (`resume[].payload`) |
| ----------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `ask_user` | `everruns.ask_user` | `{ "answers": [{ "id", "selected", "other_text" }], "status"? }`, described by the interrupt’s `responseSchema` |
| `ask_user` with a `secret` question | `everruns.secret_required` | none: only abandoning is accepted |
| a tool that needs approval | `tool_approval` | `{ "decision": "allow" \| "allow_always" \| "reject" \| "reject_always" }` |
The interrupt id is the tool call id. The next run sends `resume` entries and no new message; the entries answer the parked requests and the run streams the rest of the same turn. Abandoning an entry (`status: "cancelled"`) declines the question or rejects the call. An interrupt left without an entry is not abandoned: nothing is resolved and the run ends with the interrupts again, as it does when a new message arrives while one is open. An entry that cannot be applied returns `AgUiError::InvalidInput` before the stream opens, and nothing is resolved.
Parked requests live in memory. If the process exits, the waiting turn is left unfinished in the session’s log; after a restart, `Session::resume_interrupted_turn` runs its waiting calls again, so they park on the gate anew and a client’s resume run can answer them (see [session history](https://everruns.com/docs/framework/sessions/#history-and-resume)).
## Policy
`AgUiOptions::policy` takes a `ProjectionPolicy` to hide reasoning or usage, show fixed text while tools run, or map failures to your own error codes:
```rust
use everruns::ag_ui::{AgUiOptions, ProjectionPolicy};
let options = AgUiOptions::new().policy(ProjectionPolicy {
reasoning_visible: false,
usage_visible: false,
tool_activity_text: Some("Working on it...".into()),
..ProjectionPolicy::default()
});
```
## What a run reads from the input
The session owns the conversation, so only the last message is sent, and it must be a user message (its text parts), unless the run carries frontend tool results (below). Earlier messages are read only to seed a new thread (above); `state` and `forwardedProps` are not read. `RUN_STARTED` carries `protocolVersion: "1.0"` only when the request declared a version, so pre-1.0 clients see the stream they expect.
## Frontend tools
The input’s `tools` are tools your page runs, such as a confirmation dialog or a navigation action. Each run makes them the session’s client-side tools, so send them on every run; the latest set wins. When the model calls one, the turn parks and the run streams the call as `TOOL_CALL_START`, `TOOL_CALL_ARGS` and `TOOL_CALL_END` with its name and arguments, then finishes in success with `outcome.pendingToolCallIds`.
Run the calls in the page, then post the next run with their results as trailing `tool` messages (`toolCallId` set, `content` the result, `error` for a failure). The same turn continues and the run streams the rest of it. A result for a call that is not parked is ignored. Until every parked call has a result, nothing is recorded and the run reports the calls again, as it does when a new user message arrives instead.
Definitions are bounded: at most 64 tools, names matching `^[A-Za-z0-9_-]{1,64}$`, descriptions up to 4096 characters, parameter schemas up to 16 KiB, results up to 256 KiB. Names starting with `mcp_` are refused. Parked calls live in memory: if the process exits, they stay unanswered.
`system` and `developer` messages and `context` entries are ignored by default, and a system message after the user message is refused. If your server authenticates whoever posts the input, you can let each run carry instructions:
```rust
use everruns::ag_ui::AgUiOptions;
let options = AgUiOptions::new().input_instructions(true);
```
Each run’s system and developer messages, in order, then its context entries, are then appended to the agent’s instructions for that run. They may appear anywhere in `messages`, including after the user message, which stays the run’s input. The next run replaces them with its own, and a run with none clears them; they never enter the conversation history. Leave this off for callers you do not trust: these messages carry the authority of the system prompt.
A [serve](https://everruns.com/docs/framework/serve/#ag-ui-and-copilotkit) app gets this route built in with its `ag-ui` feature, at `/v1/channels/{agent}/ag-ui`. For a hosted agent with no server code, Everruns serves the same protocol at `/v1/channels/{channel_id}/ag-ui`.
---
# Author an agent blueprint
> Contribute a code-defined specialist agent from a capability, with a typed configuration contract the spawn path enforces
Source: {
vec![AgentBlueprint {
id: "repo_scout",
name: "Repo Scout",
description: "Search repositories for code, files, and issues. \
Read-only agent for codebase exploration.",
model: BlueprintModel::Fixed("claude-haiku-5-5".to_string()),
system_prompt: REPO_SCOUT_PROMPT,
tools: vec![Box::new(SearchCodeTool), Box::new(ReadFileTool)],
max_turns: Some(15),
config_schema: Some(json_schema_for::()),
}]
}
```
The `description` is what a parent agent reads when deciding whether to delegate, so write it as a routing decision: what the blueprint is for, and when to pick it.
`model` chooses one of three strategies. `Fixed` pins a model the host cannot override, which suits specialist work with a known cost/quality target. `Default` names a model the validated config may override. `Inherit` takes the parent’s model, for work that genuinely needs the parent’s characteristics.
Tools listed here are **private**. They are instantiated only for the blueprint’s own child session and never appear in the host agent’s tool list.
## Define configuration as a type
Derive the config schema from a Rust struct rather than writing JSON by hand. The struct is the single source of truth: field set, bounds, defaults, and descriptions all reach the spawning agent from one place.
```rust
use everruns_contracts::capability::json_schema_for;
use everruns_contracts::capability::schemars::JsonSchema;
use serde::{Deserialize, Serialize};
/// The same ceiling the search tools apply to their own arguments.
const MAX_REPOS: u32 = 50;
/// Configuration for the repository scout.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields, default)]
#[schemars(crate = "everruns_contracts::capability::schemars")]
pub struct RepoScoutConfig {
/// Maximum number of repositories to scan.
#[schemars(range(min = 1, max = MAX_REPOS))]
pub max_repos: u32,
}
impl Default for RepoScoutConfig {
fn default() -> Self {
Self { max_repos: 10 }
}
}
```
Three habits keep the contract honest:
* **Express each bound once.** Write it as a constant shared by the schema attribute and the code that enforces it at runtime, so a schema edit cannot drift from the clamp it describes.
* **Write doc comments for the caller.** They become the schema descriptions the spawning agent reads. Implementation notes belong in ordinary `//` comments.
* **Close the object** with `deny_unknown_fields` unless the blueprint genuinely accepts open configuration.
Requiring configuration is a matter of leaving a field without a default: fields serde cannot default become `required` in the derived schema, and the spawn path rejects a call that omits them.
## What the spawn path enforces
Configuration is validated against the derived schema **before** a child session exists, so a declared bound constrains the host rather than merely advising the model. A spawn is rejected when:
* a value violates the schema — out of range, wrong type, missing a required property;
* the config carries a key the schema does not define (with `deny_unknown_fields`);
* the blueprint declares no schema at all but config was supplied.
The error returned to the calling agent names the violations and includes the schema, so a model can usually correct its own call and retry.
Validation governs what a **host** may configure. It is not a substitute for a tool checking its own arguments: keep the runtime clamps in the blueprint’s tools, so a misbehaving child agent stays inside the same envelope.
Configuration can only select behavior the blueprint intentionally exposes. It cannot replace the system prompt, inject tools, bypass model policy, or expand capability permissions.
## Delegation and lifetime
A spawned blueprint session is a real durable session. It takes part in the same message, event, task, workspace, cancellation, and recovery infrastructure as any other sub-agent; the difference is only how its runtime is assembled. The session persists the blueprint identity and its validated config, so a worker can reconstruct the same runtime after a retry or handoff.
The blueprint itself stays a stateless template. Follow-ups address the durable session, not the blueprint.
## Worked examples
Two blueprints ship in-tree and are worth reading as references:
* [`crates/integrations/src/github/lib.rs`](https://github.com/everruns/everruns/blob/main/crates/integrations/src/github/lib.rs) — the minimal case: one config field, a pattern constant shared with the runtime check that enforces it.
* [`crates/integrations/src/openrouter/model_scout.rs`](https://github.com/everruns/everruns/blob/main/crates/integrations/src/openrouter/model_scout.rs) — the fuller case: numeric bounds tied to runtime constants, a nested config type, and a spend budget.
## Related
* [Sub-agents](https://everruns.com/docs/capabilities/sub-agents/) — the delegation tool blueprints are invoked through
* [GitHub Scout](https://everruns.com/docs/capabilities/github-scout/) — a shipped blueprint from the caller’s side
---
# Agents and Tools
> Describe an agent with instructions, a model, tools, files, integrations, and an optional workspace, and add typed Rust functions as tools.
Source: {
Ok(left + right)
}
let agent = Agent::builder()
.instructions("Use the add tool for arithmetic.")
.provider(OpenAI::from_env()?)
.model("gpt-6.1-sol")
.tool(add())
.build()?;
```
Use `#[everruns::tool(name = "…", description = "…")]` to override metadata, or `#[tool(rename = "…")]` on a parameter to change its model-facing name. Functions must be async, non-generic, and have plain named parameters.
The published `everruns-macros` package is an implementation crate. Applications should use the re-exported `everruns::tool` macro and should not depend on `everruns-macros` directly.
### Dynamic handlers
`FunctionTool::new` is available when a tool schema is determined at runtime:
```rust
use everruns::FunctionTool;
use serde_json::json;
let echo = FunctionTool::new(
"echo",
"Return the supplied text.",
json!({
"type": "object",
"properties": { "text": { "type": "string" } },
"required": ["text"]
}),
|args: serde_json::Value| async move {
Ok::<_, String>(args["text"].clone())
},
);
```
Prefer the macro for normal typed application tools. Use the dynamic form for schemas obtained from configuration or another protocol.
### Call context and progress
Make the first parameter a `ToolCallContext` (by value or reference) to learn which session, turn, and tool call a handler is serving, and to report progress. Progress arrives on `Session::events()` as `SessionEventKind::ToolProgress`. The context is not a model argument, so it never appears in the schema. The dynamic equivalent is `FunctionTool::with_context`.
```rust
use everruns::ToolCallContext;
/// Export the report.
#[everruns::tool]
async fn export(ctx: &ToolCallContext, pages: u32) -> String {
ctx.progress(format!("rendering {pages} pages")).await;
format!("exported for session {}", ctx.session_id())
}
```
### Approval
Mark a tool with `needs_approval` to ask a host approver before it runs. The bare flag asks on every call. `needs_approval = ` asks only when the rule returns `true`. The rule receives the generated arguments struct, named after the function in PascalCase with an `Args` suffix (`run_sql` becomes `RunSqlArgs`). The approver gets the session id and the tool call, including its id and arguments, so a host serving many sessions can route the request. A rejected call never runs, and the model receives a tool error saying it was rejected. An agent with a gated tool but no `.approver(..)` fails to build.
```rust
use everruns::approval::{ApprovalDecision, ToolApprover, async_trait};
use everruns::{Agent, Model, SessionId, ToolCall, ToolDefinition};
/// Run one SQL statement.
#[everruns::tool(needs_approval = |args: &RunSqlArgs| args.sql.contains("DROP"))]
async fn run_sql(sql: String) -> String {
sql
}
struct Console;
#[async_trait]
impl ToolApprover for Console {
async fn approve(&self, _: SessionId, call: &ToolCall, _: &ToolDefinition) -> ApprovalDecision {
println!("approve {}? {}", call.name, call.arguments);
ApprovalDecision::Reject
}
}
let agent = Agent::builder()
.instructions("Answer with SQL.")
.model(Model::simulated("Done."))
.tool(run_sql())
.approver(Console)
.build()?;
```
`FunctionTool::needs_approval(|args: &Value| ..)` and `FunctionTool::always_needs_approval()` are the dynamic forms.
## File-based agents
Load and export the shared portable package format, including initial files and complete skill directories. See [Define agents as files](https://everruns.com/docs/how-to/define-agents-as-files/) for validation, diffs, model bindings and runnable examples.
---
# Framework Architecture
> Understand Agent, Engine, Session, pluggable session hosting, and the shared execution kernel.
Source: ` is retained. It does not survive a process restart. A host that needs durable recovery supplies a `WorkBackend`.
* **Scheduling:** `Immediate` work is claimable now; `At(SystemTime)` work is not claimable early. Both are one-shot requests. The host owns polling; recurring calendars and schedule runners stay host concerns. There is no hidden scheduler or database in the default build.
* **Delivery:** task and wake claims are leased and at least once. If a process stops before settlement or acknowledgment, the item is claimable after the lease expires. Each retry has a new token and attempt; stale attempts cannot settle newer work.
* **Idempotency:** task keys and direct-wake keys each have a session-scoped namespace. Repeating the same request returns the original task or wake. Reusing a key for different input fails with `IdempotencyConflict`. Workers should also deduplicate external side effects on the stable task id or submission key.
* **Cancellation:** pending work cancels immediately. Running work records cancellation intent; the worker checks the latest task snapshot, stops cooperatively, then reports `TaskOutcome::Canceled`. A task may still succeed if it passes its safe cancellation point first.
* **Wakes:** applications can request an immediate wake directly. A task can also create one atomic completion wake with `WakePolicy::OnCompletion`. Wakes use the same lease/retry/acknowledgment model as tasks.
Durable platform scheduling, retention, distributed polling, and multi-host coordination belong in the host’s `WorkBackend`; they are not enabled by the offline Framework default. The in-memory backend retains accepted payloads until it is dropped and does not enforce admission quotas, so hosted providers must apply tenant authorization, payload limits, quotas, and retention at their own boundary.
---
# Portable and hosted capabilities
> Understand which capabilities run in the Framework and which require the Everruns Platform host.
Source: > {
let decisions = Decisions::new("jev-latest", TypeSafeAI::from_env()?);
let text = "CONGRATULATIONS! You've WON $1,000,000. Click here to claim your prize now!";
let spam = decisions.probability("Is this message spam?", text).await?;
println!("spam: {spam:.2}");
if spam > 0.9 {
println!("quarantined");
}
Ok(())
}
```
```text
spam: 0.98
quarantined
```
One number, and your own `> 0.9` decides — the model reports how likely, not what to do. The same call answers `0.03` for “Standup moved to 10am.” and `0.74` for a bare “Claim your prize now!”; the middling ones are what a threshold is for.
`--features typesafe` adds `TypeSafeAI` and the `Jev` capability. Without it `everruns` names no vendor: `Decisions::new` takes any `DecisionsService`.
### OpenAI’s Decisions API
[OpenAI’s Decisions API](https://developers.openai.com/api/docs/guides/decisions) (public beta, model `gpt-6-luna`) answers the same questions. `OpenAIDecisions` in `everruns-integrations` is a `DecisionsService`, so it drops into the same `Decisions`:
```bash
cargo add everruns
cargo add everruns-integrations --features openai-decisions
export OPENAI_API_KEY=...
```
```rust
use everruns::Decisions;
use everruns_integrations::openai_decisions::OpenAIDecisions;
let service = OpenAIDecisions::new(std::env::var("OPENAI_API_KEY")?);
let decisions = Decisions::new("gpt-6-luna", service);
let urgent = decisions
.probability("Does this convey urgency?", "My card was charged twice, fix it today.")
.await?;
println!("urgent: {urgent:.2}");
```
A runnable version that routes a support ticket with all three primitives is [`openai_decisions_triage`](https://github.com/everruns/everruns/blob/main/crates/integrations/examples/openai_decisions_triage.rs):
```bash
OPENAI_API_KEY=... cargo run -p everruns-integrations --features openai-decisions --example openai_decisions_triage
```
All three primitives are native and calibrated, and one request sends every question in one call. Score questions take at most ten levels. On Everruns Platform, set `UTILITY_DECISION_DRIVER=openai` with `UTILITY_OPENAI_API_KEY` to answer guardrail `jev` checks with it (see [environment variables](https://everruns.com/docs/sre/environment-variables/)).
### Three primitives
A decision asks one or more questions about the same state. Each is one of three shapes:
```rust
use everruns::Decisions;
let answers = decisions
.about("I've been on hold for two hours and my card was charged twice.")
.noul("urgent", "Does this convey urgency?")
.score(
"severity",
"How severe is the problem the writer describes?",
[
"A minor annoyance",
"A real problem with their account",
"Serious harm requiring immediate action",
],
)
.choice(
"queue",
"Which team should handle this message?",
["billing", "technical", "sales"],
)
.send()
.await?;
let urgent: f64 = answers.probability("urgent")?;
let queue: &str = answers.selected("queue")?;
```
* **`noul`** — whether something holds, as the probability of yes. A value near 0.5 means yes and no are near-equally likely, not “medium”. ([Noul](https://docs.typesafe.ai/primitives/noul))
* **`choice`** — exactly one option from your set, with the distribution behind it. Needs at least two options. ([Choice](https://docs.typesafe.ai/primitives/choice))
* **`score`** — a position along levels you define, lowest first. Needs at least two levels. ([Score](https://docs.typesafe.ai/primitives/score))
The three are System One’s own, so TypeSafe’s [Primitives](https://docs.typesafe.ai/primitives) documents what each answer means and how to choose between them, and [State](https://docs.typesafe.ai/concepts/state) covers what to put in the `about(...)` value. Everruns names them the same way rather than inventing synonyms.
Questions in one call are answered **in parallel inside a single request**, so asking five costs one round trip, not five. TypeSafe calls leaning on that [speculative fan-out](https://docs.typesafe.ai/patterns/fan-out): ask the questions you *might* need, and let your code decide which ones mattered.
### Ids are yours; instructions are the model’s
The id labels the answer for your code and is never sent to the model. A question whose meaning lives in its id asks nothing:
```rust
// Wrong: the model never sees "is_the_joke_funny".
.noul("is_the_joke_funny", "?")
// Right: the instructions carry the question.
.noul("funny", "Would a general audience laugh at this joke?")
```
The same applies to score levels. Describe concrete situations — “A minor annoyance” reads on its own where “2 out of 5” does not.
### Read the tail, not the average
For “is there any serious hit here” rules, read the probability mass at or above a level rather than the weighted score. Something probably fine but possibly awful must not average into fine:
```rust
// Not: answers.score("severity")? > 1.5
let serious = answers.tail("severity", 2)?;
if serious > 0.3 {
println!("escalated");
}
```
### Errors
`DecisionsError` separates configuration mistakes from service failures, the same split [`CompletionError`](#errors) makes:
* `MissingService` — the decisions was built without a service to reach.
* `NoQuestions` — the decision was sent with nothing to ask.
* `Unconfigured` — the service exists but the deployment never configured its credential, so it would answer nothing.
* `NoSuchAnswer(id)` — you read an id that was not asked, or read an answer as the wrong shape (a `score` as a probability).
* `Call(..)` — the service call failed, carrying the `AgentLoopError`.
The first three are caught before any request leaves the process. `Unconfigured` is worth handling separately: a guardrail treats it as fail-open, but a direct caller usually wants to know the number never arrived rather than read a confident-looking default.
### Going lower
`Decision` is a thin value-first layer over `DecisionsService`, which is public. Applications that already hold a service — or implement their own, over a different vendor or a local model — can call it directly with `everruns`’s `DecisionRequest`, `DecisionQuestion`, and `DecisionAnswer` re-exports:
```rust
use everruns::{DecisionQuestion, DecisionRequest, DecisionsService};
let outcome = service
.evaluate(
DecisionRequest::new("Claim your prize now!")
.ask("spam", DecisionQuestion::noul("Is this message spam?")),
)
.await?;
```
That surface is the contract itself: every question type and the full `DecisionOutcome`, including usage, with nothing defaulted for you. Implementing `DecisionsService` is also how a different decision service (another vendor, or a fine-tuned local model) plugs into the same `Decisions`, guardrails included.
### Choosing a model
The model is named up front, the way `Model::new` names one: the service is transport, and the model is the thing that answers. There is no default to inherit without noticing, because a threshold calibrated against one version is not evidence about the next.
Ids are the provider’s own, so they are spelled the way the vendor spells them. `jev-latest` is TypeSafe’s alias for the current Jev, so it tracks whatever the current version is; an exact id like `jev-1.13.0` pins one, so a vendor update cannot move your thresholds under you. Bare `jev` is not an id the API knows — nothing here rewrites what you pass.
Ask for the alias and read back what answered, which is the id to pin once a threshold is calibrated:
```rust
let version = answers.model(); // "jev-1.13.0" for a "jev-latest" request
```
A single call can name a different model with the same method on the request builder, and it wins for that call:
```rust
let answers = decisions
.about("...")
.noul("urgent", "Does this convey urgency?")
.model("jev-1.13.0")
.send()
.await?;
```
A deployment that must pin a model does so by never exposing the knob in the config an agent writes — not by the type being unable to carry one, because there will be other decision services and other models.
A deployment running the Everruns platform configures a separate `UTILITY_TYPESAFE_API_KEY` for its [guardrails](https://everruns.com/docs/capabilities/guardrails/) — a different account from the one an embedding application holds.
### Giving an agent the decisions
Everything above is agentless: your code asks, your code decides. The other half is letting an *agent* classify as part of its own work — checking a claim against a source before citing it, rating a draft before sending it.
`Jev` is the same decisions as a capability, so an agent gets it as a tool:
```rust
use everruns::{Agent, Engine, Jev, Model, OpenAI};
let agent = Agent::builder()
.name("reviewer")
.instructions(
"You review copy. When asked how something reads, measure it with \
jev_decision and report the numbers rather than judging by eye.",
)
.model(Model::new("gpt-6.1-sol", OpenAI::from_env()?))
.capability(Jev::from_env()?)
.build()?;
let session = Engine::new().create(agent);
let turn = session
.run("Rate this subject line for pushiness: 'Act now before it is too late'")
.await?;
```
The agent calls `jev_decision`, writing its own questions about whatever it is looking at, and gets the same calibrated numbers back. It is the identical tool the hosted [TypeSafe integration](https://everruns.com/docs/integrations/typesafe/) gives platform agents — same name, same schema — so behavior matches whether you embed the Framework or run on Everruns.
Which one to reach for:
| | you decide | the agent decides |
| ------------ | -------------------------------------- | --------------------------------- |
| **who asks** | your code writes the questions | the model writes the questions |
| **use** | `Decisions` | the `Jev` capability |
| **good for** | a policy check, a routing rule, a gate | verification inside a longer task |
### What stays with an agent
A decision owns no session, no history, and no workspace, and runs no tools. Reach for an [agent](https://everruns.com/docs/framework/agents/) as soon as the work needs any of those. Typed output guarantees the interface, not the truth: validate thresholds against your own data and consequences.
### Testing without a credential
`Decisions::simulated` returns a fixed number from an in-process stub. It is a **test double**, not a local decisions: it runs no inference, reads nothing from the state you pass it, and is not a way to classify without a provider. It exists so tests and examples can assert on the code around a decision without a network call or an API key.
Real work always goes through a decision service: `TypeSafeAI` above, or your own `DecisionsService`.
```rust
use everruns::Decisions;
let p = Decisions::simulated(0.93)
.probability("Does this convey urgency?", "Two hours on hold.")
.await?;
assert!(p > 0.9);
```
Because the answer is fixed, a simulated decision proves your threshold logic runs — never that a real decision service would return that number.
The runnable version of this section is [`direct_decisions.rs`](https://github.com/everruns/everruns/blob/main/crates/everruns/examples/direct_decisions.rs). It uses the stub by default so it runs with no key; pass `--live` (with `--features typesafe` and `TYPESAFE_API_KEY` set) to send the same questions to a real decision service. [`agent_decisions.rs`](https://github.com/everruns/everruns/blob/main/crates/everruns/examples/agent_decisions.rs) does the same for the agent path.
### Shared provider accounts for decisions
`Decisions::from_registry` accepts a `ProviderRegistry` and an explicit `ModelSpec`. Select `ModelSpec::on("typesafe", "jev-1.13.0")` for direct TypeSafe, or `ModelSpec::on("openrouter", "jev-1.13.0")` for OpenRouter. The OpenRouter driver maps that explicit alias to `typesafe/jev-1.13`; other IDs remain opaque. Providers hold authentication once, so their chat and decision drivers use the same account. Returned model IDs report the snapshot that actually answered.
`Jev::with_provider(provider, model_spec)` supplies that same account to a Framework capability. Use its exact provider key in the model spec. Existing `Jev::new` and `Jev::with_client` conveniences remain available for applications holding a direct TypeSafe key.
---
# Durable Object hosting reference
> Run ordinary Everruns Rust agents with durable admission, leases, event logs and alarm-driven recovery owned by a Durable Object.
Source: {
let session_id = request.session_id();
let current_high = self.high_watermark(session_id);
let (after, snapshot) = match request.cursor() {
None => (0, current_high),
Some(cursor) => {
if cursor.session_id() != session_id {
return Err(EventLogError::CrossSessionCursor {
detail: "cursor belongs to another session".into(),
});
}
match cursor.snapshot_high_watermark() {
Some(snapshot) if snapshot > current_high => {
return Err(EventLogError::ExpiredCursor {
detail: "cursor snapshot is not available".into(),
});
}
// Pinned continuation, then the polling form.
Some(snapshot) => (cursor.after_sequence(), snapshot),
None => (cursor.after_sequence(), current_high),
}
}
};
let limit = request.limit().get();
let mut events = self.events_in(session_id, after, snapshot, limit + 1);
let has_more = events.len() > limit;
if has_more {
events.pop();
}
let next_cursor = has_more
.then(|| {
let last = events.last().and_then(|event: &Event| event.sequence).unwrap_or(after);
EventCursor::continuation(session_id, last, snapshot)
})
.transpose()?;
EventPage::new(events, next_cursor, snapshot)
}
}
#[async_trait]
impl EventLog for MyEventLog {
async fn append(&self, request: EventRequest) -> Result {
if request.is_ephemeral() {
return Err(EventLogError::InvalidAppend {
detail: "ephemeral events are sink-only".into(),
});
}
// The log owns identity: assign the event id and the next per-session
// sequence, persist, and return the finalized canonical envelope.
let sequence = self.next_sequence(request.session_id);
let event = request.into_event(EventId::new(), sequence);
self.persist(&event)?;
Ok(event)
}
fn durability(&self) -> EventDurability {
EventDurability::CrashDurable
}
}
```
The contract an implementation must uphold:
* an accepted append owns id and sequence assignment and returns the finalized canonical `Event`, visible to the next read of that session;
* durable sequences are unique and strictly increasing per session, and need not be contiguous, gaps are expected when a reader projects an append-only physical log into a filtered logical event sequence;
* a continuation stays pinned to the first page’s high-watermark and cannot observe concurrent appends; a poll cursor can;
* cursor/session mismatches and inconsistent positions return the typed `EventLogError` variants above rather than panicking;
* the log is append-only. There is no truncate, rewind, or mutation contract, and `EventHistory` remains a read-only projection rather than a second writable message store.
The [external event-log example](https://github.com/everruns/everruns/tree/main/crates/everruns/tests/fixtures/external-consumer/event-log) provides a complete implementation in a standalone application.
### Ordering and bounded delivery
A subscriber receives events in channel arrival order and each session has its own stream. The canonical `sequence` field is a replay position, not a live delivery counter: durable events carry `Some(sequence)` and live-only ephemeral events such as streaming deltas carry no sequence. Persisted sequences increase monotonically per session and may have gaps. Ephemeral events do not consume replay positions.
The live stream has a bounded buffer and never applies backpressure to the agent turn. A dropped or slow subscriber cannot stall model or tool execution. If a subscriber falls behind, `recv()` and `try_recv()` return `EventStreamError::Lagged { missed }`; loss is never hidden. The next receive can continue from the oldest retained event, but the renderer must treat its live projection as incomplete.
Streaming deltas are provisional and sink-only. Completed assistant/tool events are authoritative, and an output-replacement event means accumulated text for that message must be discarded. Durable events reach the live sink only after their log append commits; ephemeral events go directly to the sink and never enter history. After live lag, a Framework application can rebuild its persisted transcript with bounded [`Session::history()` pages](https://everruns.com/docs/framework/sessions/#history-and-resume). That projection excludes ephemeral deltas by design. Applications that need raw durable envelopes rather than derived messages can provide and read an `EventLog` through the advanced `everruns-core` (`host` feature) SPI; neither recovery path relies on the in-process subscriber.
### Cancellation and failure
Pass a `CancellationToken` through `RunOptions` to stop a turn. Cancellation produces both a `Turn` with `TurnStopReason::Cancelled` and a correlated `turn.cancelled` event carrying the same `turn_id`.
Runtime failures remain available through `Session::run()`’s outcome/error semantics and the event stream. Subscribe before running and continue draining the stream after the run resolves to retain the terminal failure event and its full structured payload.
The complete runnable example is [`canonical_events.rs`](https://github.com/everruns/everruns/blob/main/crates/everruns/examples/canonical_events.rs):
```bash
cargo run -p everruns --example canonical_events
```
---
# Runnable Examples
> Complete Framework programs, maintained and compiled with the everruns crate.
Source: , workspace: &Path) -> Result {
Agent::builder()
.name("bashkit-repo-agent")
.instructions(include_str!("resources/instructions.md"))
.provider(provider)
.model(MODEL)
.max_iterations(12)
.workspace(workspace)
.workspace_policy(WorkspacePolicy::read_write())
.capability(BashkitShell::new())
.build()
}
```
## Run and verify
The shared observer displays a bounded shell timeline and waits for a successful turn. The host then verifies the mounted files itself.
```rust
// OPENAI_API_KEY, declared by the OpenAI driver itself.
let agent = agent::build(everruns::OpenAI::from_env()?, &workspace)?;
let engine = Engine::new();
let session = engine.create(agent);
demo::run(&session, &request).await?;
verify_release(&workspace, &release_date)?;
```
Use `session.send_and_wait(&request).await?` when a live tool timeline is not needed.
## How Bashkit behaves
Bashkit interprets shell scripts in-process against `/workspace`. The model gets no host filesystem outside that mount, network, Git credentials, or subprocess execution. Commands, loops, output, and script size are bounded. Repository text is treated as untrusted data rather than agent instructions.
## Validate it
```bash
cargo test -p everruns-bashkit-repo-agent
bash examples/bashkit-repo-agent/demo/record.sh --check
```
These checks validate argument handling, fixture state, host assertions, and the live-demo contract without provider credentials. They do not grade model quality.
## Demo and recording
The screencast types the release task into the interactive binary, displays real `bashkit_shell` calls, and ends with host-side checks over the mutated files. It does not replay prepared output. Read the [captured transcript](https://github.com/everruns/everruns/blob/main/examples/bashkit-repo-agent/demo/transcript.txt) at your own pace.
With VHS, ffmpeg, a VHS-compatible browser, and funded OpenAI credentials:
```bash
bash examples/bashkit-repo-agent/demo/record.sh
```
The script uses `OPENAI_API_KEY` when exported, otherwise Doppler project `everruns-dev`, config `dev`. It updates the GIF and transcript only after the model turn and host verification succeed.
## Adapt it safely
Replace the fixture, request acceptance criteria, and verifier together. Keep the mount disposable and narrow, start read-only unless mutation is required, and verify consequential claims outside the model/tool boundary.
## Boundaries
This demonstrates one sandboxed repository mutation, not a general coding agent. It cannot fetch dependencies, run native programs, commit, or push. The Framework session is in-memory.
---
# Coding Review Agent
> Tool-based code inspection, a tightly scoped execution tool, and distinguishing test failure from tool failure.
Source: ) -> Result {
Agent::builder()
.name("everruns-support-agent")
.instructions(include_str!("resources/instructions.md"))
.provider(provider)
.model(MODEL)
.max_iterations(12)
.tool(tools::search_docs())
.tool(tools::read_doc())
.build()
}
```
## Send, observe, and wait
The shared demo helper subscribes before sending, shows bounded tool previews, waits for completion, and rejects unsuccessful turns. Use `session.send_and_wait(&question).await?` when a live tool timeline is unnecessary.
```rust
// ANTHROPIC_API_KEY, declared by the Anthropic driver itself.
let agent = agent::build(everruns_drivers::anthropic::from_env("anthropic")?)?;
let engine = Engine::new();
let session = engine.create(agent);
println!("MODEL: {}", agent::MODEL);
demo::run(&session, &question).await?;
```
This engine is in-memory. The agent can explain durable sessions from its corpus, but the example itself does not persist its session.
## How the tools work
`search_docs` ranks matches against five bundled pages and returns page IDs, public URLs, and matching excerpts. `read_doc` accepts only those page IDs and returns the complete snapshot. It never accepts an arbitrary filesystem path.
## Validate the behavior
```bash
cargo test -p everruns-framework-support-agent
bash examples/everruns-support-agent/demo/record.sh --check
```
Tests cover content-based search, empty and unmatched queries, complete citable reads, arbitrary-path rejection, and interactive input validation. They do not grade the model’s answer; compare a live response with the expected outcome above.
CI runs the offline checks without provider credentials. Live model behavior is evaluated separately.
## Demo and recording
The screencast types a question into the same interactive binary shown above, then displays the actual Opus tool calls and answer. VHS hides most provider wait time but does not replace the model or tools with scripted output. Read the [captured transcript](https://github.com/everruns/everruns/blob/main/examples/everruns-support-agent/demo/transcript.txt) at your own pace.
With credentials exported and VHS, ffmpeg, and a VHS-compatible browser installed:
```bash
bash examples/everruns-support-agent/demo/record.sh
```
The script uses an exported `ANTHROPIC_API_KEY` when present, otherwise Doppler project `everruns-dev`, config `dev`. It updates `demo/demo.gif` and `demo/transcript.txt` only after a successful turn.
## Adapt it
Replace the bundled pages with a versioned documentation index while retaining separate search and read operations. Attach source/version metadata, restrict reads to authorized documents, and treat retrieved text as untrusted evidence rather than instructions.
## Boundaries
The corpus is a five-page snapshot from 2026-09-08, not a live search of the docs site. Provenance is recorded in the [corpus README](https://github.com/everruns/everruns/blob/main/examples/everruns-support-agent/src/resources/docs/README.md), and the snapshot can lag current APIs.
---
# Foreman
> A decision service supervising a coding agent it never has to stop.
Source: ) -> Result {
Agent::builder()
.name("support-agent")
.instructions(include_str!("resources/instructions.md"))
.provider(provider)
.model(MODEL)
.max_iterations(12)
.tool(tools::lookup_customer())
.tool(tools::read_support_policy())
.build()
}
```
## Send, observe, and wait
The shared demo helper subscribes before sending, filters events to this turn, shows bounded tool previews, waits for completion, and rejects unsuccessful turns. It changes presentation only; use `session.send_and_wait(question).await?` when you do not need the live tool timeline.
```rust
// OPENAI_API_KEY, declared by the OpenAI driver itself.
let agent = agent::build(everruns::OpenAI::from_env()?)?;
let engine = Engine::new();
let session = engine.create(agent);
println!("MODEL: {}", agent::MODEL);
demo::run(&session, question).await?;
```
This engine is in-memory. It does not demonstrate durable session storage; the Everruns Support example can explain that API, but does not itself persist its session.
## How the tools work
`lookup_customer` reads one of three fictional customer records. It returns facts, not a prewritten recommendation. `read_support_policy` returns the bundled recovery rules. The model combines the two; no tool disables MFA or changes a real account.
## Validate the behavior
```bash
cargo test -p everruns-support-agent
bash examples/support-agent/demo/record.sh --check
```
Tests cover the distinct account states and rejection of unknown IDs. They do not grade the model’s recommendation: compare a live response with the expected outcomes above.
CI runs these offline checks without provider credentials. Live model behavior is evaluated separately; passing tests is not proof of answer quality.
## Demo and recording
The screencast runs the same `cargo run -q -p everruns-support-agent` command shown above. VHS hides most provider wait time but does not replace the model or tools with scripted output. Read the [captured transcript](https://github.com/everruns/everruns/blob/main/examples/support-agent/demo/transcript.txt) at your own pace.
With credentials exported and VHS, ffmpeg, and a VHS-compatible browser installed:
```bash
bash examples/support-agent/demo/record.sh
```
The recording script uses an exported `OPENAI_API_KEY` when present, otherwise Doppler project `everruns-dev`, config `dev`. It runs the real command inside VHS and updates `demo/demo.gif` plus `demo/transcript.txt` only after a successful turn. Public/demo data is safe here, but adapting tools may expose private data.
## Adapt it
Replace the fixture lookup with your authorized customer-data service. Keep policy separate from account facts, scope lookups to the authenticated customer, and return only fields needed for the support decision. Add human approval before any account mutation.
## Boundaries
All customers, policy rules, and support.example.com URLs are fictional. This is a read-only support exercise, not a live help desk.
---
# Host Services
> Compose an embedding host's own capabilities, provider resolution, retry budgets, MCP credentials, request metadata and observers into Engine sessions.
Source: ,
_config: &Value,
_context: &ModelViewContext<'_>,
) -> Vec {
messages.push(RuntimeMessage::system("Keep changes reviewable."));
messages
}
}
struct RepoPolicy;
impl Capability for RepoPolicy {
fn id(&self) -> &str { "repo_policy" }
fn name(&self) -> &str { "Repository policy" }
fn description(&self) -> &str { "Guards repository operations." }
fn system_prompt_addition(&self) -> Option<&str> {
Some("Never rewrite published history.")
}
fn pre_tool_use_hooks(&self) -> Vec> {
vec![Arc::new(PolicyGate(NoForcePush))]
}
fn model_view_provider(&self) -> Option> {
Some(Arc::new(Reminder))
}
}
let agent = Agent::builder()
.instructions("You maintain this repository.")
.provider(OpenAI::from_env()?)
.model("gpt-6.1-sol")
.host_services(HostServices::new().capability(RepoPolicy))
.build()?;
let session = Engine::new().create(agent);
let context = session.inspect().await?;
assert!(context.instructions.contains("Never rewrite published history."));
```
`PolicyGate` marks the hook as a policy decision, so it runs after any hook that rewrites arguments and decides on the call that will execute. A blocked call never reaches its tool; the model receives the reason as the call’s result. Commands a capability contributes appear in `SessionContext::commands`.
`HostServices::capability` registers and activates. `HostServices::register` only registers, and the Agent activates it with an ordinary `.capability("repo_policy")` reference or through its Harness.
## Resolve providers through the host
With `HostProviders`, the host’s `ProviderStore` owns endpoints and credentials and the Agent names its model with `Model::on(provider_key, model_id)`. The store is asked under the calling session’s identity on every provider call, so rotated credentials and provider metadata reach the next call without rebuilding anything.
```rust
use everruns::hosting::services::{HostProviders, HostServices, ProviderStore};
use everruns::{Agent, DriverRegistry, Model};
let mut drivers = DriverRegistry::new();
everruns::drivers::openai::register_driver(&mut drivers);
let agent = Agent::builder()
.instructions("You are concise.")
.model(Model::on("team-openai", "gpt-6.1-sol"))
.host_services(HostServices::new().providers(HostProviders::new(store, drivers)))
.build()?;
```
Selection is never implicit. Building fails with `ConflictingProviders` when a host-resolved model also carries an Agent provider, or when `Model::on` names a different provider than `.provider(..)`. A provider key the host cannot serve fails runtime construction before any model call, rather than falling back to another driver.
## Attribute provider requests
`RequestMetadata` is a small set of credential-free strings that every provider request of the Agent’s sessions carries: turn model calls, out-of-band completions, and sessions Engine rebuilds or resumes, on both the in-process and the hosted lanes. `openrouter_attribution` sets the entries the OpenRouter driver sends as its `HTTP-Referer` and `X-Title` headers; other providers receive them as ordinary request metadata.
```rust
use everruns::hosting::services::{HostServices, RequestMetadata};
use everruns::{Agent, Engine, OpenAI};
let metadata = RequestMetadata::new()
.entry("app", "my-app")
.entry("my_app_version", env!("CARGO_PKG_VERSION"))
.openrouter_attribution("https://my-app.example", "My App");
let agent = Agent::builder()
.instructions("You are concise.")
.provider(OpenAI::from_env()?)
.model("gpt-6.1-sol")
.host_services(HostServices::new().request_metadata(metadata))
.build()?;
let session = Engine::new().create(agent);
let context = session.inspect().await?;
assert_eq!(context.request_metadata["app"], "my-app");
```
`SessionContext::request_metadata` shows the entries as assembled for the next request. The runtime adds its own correlation ids to each request after them. Building fails with `InvalidRequestMetadata` when an entry claims one of those ids (`RequestMetadata::RESERVED_KEYS`: `session_id`, `harness_id`, `turn_id`, `exec_id`, `org_id`, `agent_id`, `model_id`), when a key is not 1 to 64 ASCII letters, digits, `_`, `.`, `-` or `:`, when a value is longer than 512 bytes or holds control characters, or when there are more than nine entries. Providers and request capture see these values, so never put a secret in them.
## Budgets, MCP credentials and observers
```rust
use std::time::Duration;
use everruns::hosting::services::{
HostEvent, HostEventListener, HostServices, LlmRetryConfig, McpAuthProvider,
McpAuthRequest, McpAuthResult, McpCredential, async_trait,
};
use everruns::Engine;
struct Vault;
#[async_trait]
impl McpAuthProvider for Vault {
async fn authorization(
&self,
request: &McpAuthRequest<'_>,
) -> McpAuthResult> {
// Called before every discovery and tool call: return the current token.
Ok(Some(McpCredential::bearer(format!("token-for-{}", request.server_name))))
}
}
struct Audit;
#[async_trait]
impl HostEventListener for Audit {
async fn on_event(&self, event: &HostEvent) {
println!("{} {:?}", event.event_type, event.sequence);
}
}
let services = HostServices::new()
.provider_retry(LlmRetryConfig { max_retries: 4, ..LlmRetryConfig::default() })
.provider_stall_timeout(Duration::from_secs(45))
.mcp_auth(Vault);
let engine = Engine::builder().host_listener(Audit).build();
```
Host listeners receive the same committed canonical envelopes as `EngineBuilder::listener`, in Core event form, on their own bounded queue. A slow, full or failing listener cannot fail a turn or delay other listeners, and nothing a listener does is written to session history. Drops are counted in `Engine::observer_stats`. `McpAuthProvider` requires the `mcp` feature.
## Related
* [Advanced capabilities](https://everruns.com/docs/framework/advanced-capabilities/) for typed capability packages that need no Core contract.
* [Session controls](https://everruns.com/docs/framework/session-controls/) to hot-install, activate and deactivate capabilities and run their commands on a live session.
* [Session hosting](https://everruns.com/docs/framework/hosting/) for durable session authority under Engine.
* [Custom backends](https://everruns.com/docs/framework/custom-backends/) when the host itself replaces execution components.
---
# Pluggable session hosting
> Implement durable hosting beneath Engine without implementing an agent runtime.
Source: ) -> Provider {
Provider::new(
"openrouter",
OpenRouterChatDriver::new().with_transport(host_fetch),
)
.base_url("https://openrouter.ai/api/v1")
.auth(BearerAuth::new(api_key))
}
```
The same `.with_transport(...)` method is available on `OpenAIChatDriver`, `OpenAICompletionsChatDriver`, `OpenAIProtocolChatDriver` and `OpenResponsesProtocolChatDriver`. Native applications may also inject a transport; otherwise they keep the shared HTTP client. WASM requires an adapter and reports an error if none is supplied.
The adapter owns endpoint and DNS policy, redirect refusal, network timeouts, and cancellation when a request or response stream is dropped. Treat it as trusted application code: it handles provider credentials. Return response headers before consuming the body and stream bytes incrementally. Host JS futures must be wrapped for the single-threaded WASM `Send` contract. OpenAI WebSocket, realtime, speech, embeddings and decision transports remain native; this support covers HTTP chat.
The [Workers/Durable Object fetch adapter](https://github.com/everruns/everruns/blob/main/examples/durable-object-agent/src/fetch.rs) shows exact bytes, manual redirects, cancellation and read deadlines. The [workerd integration tests](https://github.com/everruns/everruns/tree/main/tests/wasm-providers) run model/tool/model exchanges in both a Worker and a Durable Object without reimplementing either provider protocol.
## Custom providers
Use a custom provider when an application talks to a model service that the Framework does not configure for you. The extension boundary is the public `ChatDriver` trait plus a `Provider` value. The agent selects that provider’s model with a plain credential-free string id.
At a high level:
```rust
use everruns::{Agent, BuildError, ChatDriver, Provider};
fn agent_for(driver: impl ChatDriver + 'static) -> Result {
Agent::builder()
.instructions("Use the company model gateway.")
.provider(Provider::new("company-gateway", driver))
.model("assistant-v2")
.build()
}
```
A driver implements the streaming chat-completion contract. It receives the resolved endpoint, model-facing messages (`everruns::llm::Message`), and call configuration, and returns an `LlmResponseStream`. Exact trait methods and event shapes live in the [`everruns::ChatDriver` API reference](https://docs.rs/everruns/latest/everruns/trait.ChatDriver.html).
Keep credential lookup and refresh in trusted host/provider configuration. Model ids must remain safe to log, compare, store, and pass across application boundaries. Provider errors should preserve useful decisions without including secrets.
A driver registered through a `DriverDescriptor` also declares which environment variables it reads, on its own credential fields. Declaring is inert — the driver never reads them — and it is what lets a caller resolve the provider from the environment without any central name mapping. See [Credentials](#credentials).
Use focused provider crates when they already implement the protocol you need. Custom backends and provider registry topology belong to [low-level host composition](https://everruns.com/docs/framework/custom-backends/), not ordinary model selection.
---
# Moving to Platform or Cloud
> What carries over when a Framework agent moves to a self-hosted Everruns Platform or Everruns Cloud, what has to be rebuilt, and what stays behind.
Source: > {
let agent = Agent::builder()
.instructions("You are a concise assistant.")
.provider(OpenAI::from_env()?)
.model("gpt-6.1-sol")
.build()?;
let engine = Engine::new();
let session = engine.create(agent);
let turn = session.send_and_wait("Explain durable execution in one sentence.").await?;
println!("{}", turn.response);
Ok(())
}
```
The model id stays credential-free: `.model("…")` names the model, and `.provider(…)` supplies the driver, endpoint, and key separately. `OpenAI::from_env` reads `OPENAI_API_KEY` and redacts it from debug output.
`send_and_wait` is the request/response convenience; use `send` when the application needs to stream output or steer a turn while it runs.
## Give it a tool
An agent becomes useful when it can act. Annotate a function and hand it over:
```rust
use everruns::{Agent, OpenAI};
#[everruns::tool]
/// Look up the current stock level for a SKU.
async fn stock_level(sku: String) -> Result {
Ok(inventory_lookup(&sku).await)
}
let agent = Agent::builder()
.instructions("Answer inventory questions. Use the tool rather than guessing.")
.provider(OpenAI::from_env()?)
.model("gpt-6.1-sol")
.tool(stock_level())
.build()?;
```
The macro derives the JSON schema from the signature, so the model sees typed arguments and the code stays ordinary Rust. See [Tools and macros](https://everruns.com/docs/framework/agents/#tools).
## Where to go next
* [Agents](https://everruns.com/docs/framework/agents/) — instructions, files, workspaces, and MCP.
* [Tools and macros](https://everruns.com/docs/framework/agents/#tools) — typed function tools.
* [Sessions](https://everruns.com/docs/framework/sessions/) — multi-turn state and history.
* [Framework architecture](https://everruns.com/docs/framework/architecture/) — how the pieces fit.
## Testing without a provider
Once you are building for real, you will want tests that do not call a model. `Model::simulated` replays a canned response through the same model/provider path:
```rust
use everruns::{Agent, Engine, Model};
let agent = Agent::builder()
.instructions("You are a concise assistant.")
.model(Model::simulated("Everruns is ready."))
.build()?;
let turn = Engine::new().create(agent).send_and_wait("Are you ready?").await?;
assert_eq!(turn.response, "Everruns is ready.");
```
It is a test double, not a local model: it runs no inference, so it proves your wiring rather than any model behavior. Use it in tests and CI, not as a way to run Everruns without a provider. See [Testing and simulation](https://everruns.com/docs/framework/testing-and-simulation/).
---
# Serve (experimental)
> Build a hosted agent app with attribute macros, file-layout discovery and a manifest, served over a subset of the Everruns server /v1 API.
Source: {
let wh = cx.connection::()?; // credentials never reach the model
cx.progress("querying…").await;
Ok(wh.query(&sql)?.truncate(500))
}
serve::assets!();
#[tokio::main]
async fn main() -> serve::Result {
serve::start(App::builder().discover().build()).await
}
```
For a guided start, [Tutorial: Serve an Agent and Call It from Code](https://everruns.com/docs/framework/serve-tutorial/) builds an agent, protects it with an API key, and calls it from the SDKs.
## Install
```sh
cargo add everruns-serve tokio --features tokio/full
cargo add --build everruns-serve-build
```
The package is `everruns-serve` and the library is imported as `serve`. Add a `build.rs` that calls `serve_build::embed()` so `agent/**` and `serve.toml` are compiled into the binary.
## Try it
Both examples run offline against a scripted simulator, so no keys or network are needed. From a checkout of the repository:
```sh
cargo run -p serve-example-revenue-analyst # dev server on :3000 with a live console
cargo run -p serve-example-revenue-analyst -- eval # run the evals in-process
cargo run -p serve-example-revenue-analyst -- manifest
```
Then talk to it with the same requests you would send an Everruns server:
```sh
ID=$(curl -s localhost:3000/v1/sessions -H 'content-type: application/json' -d '{}' | jq -r .id)
curl -s localhost:3000/v1/sessions/$ID/messages -H 'content-type: application/json' \
-d '{"message":{"content":[{"type":"text","text":"What was revenue last week?"}]}}'
curl -N "localhost:3000/v1/sessions/$ID/sse?after_sequence=0"
```
To use a real model, set `OPENROUTER_API_KEY`, or point `SERVE_GATEWAY_URL` and `SERVE_GATEWAY_KEY` at any OpenAI-compatible gateway. With serve’s `bedrock` feature, `bedrock/` models (for example `bedrock/us.anthropic.claude-sonnet-4-6`) call Amazon Bedrock on the AWS default credential chain whenever `AWS_REGION` is set.
| Example | Shows |
| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| [Hello app](https://github.com/everruns/everruns/tree/main/examples/serve/hello) | The smallest app: one agent, one tool, one eval. |
| [Revenue Analyst](https://github.com/everruns/everruns/tree/main/examples/serve/revenue-analyst) | A tool with approvals, a skill, Slack, a schedule, MCP and typed connections, a subagent, evals and the Bashkit sandbox. |
| [AG-UI app](https://github.com/everruns/everruns/tree/main/examples/serve/ag-ui) | An agent streamed to `@ag-ui/client` and CopilotKit, with an approval as an interrupt. |
| [AgentCore app](https://github.com/everruns/everruns/tree/main/examples/serve/agentcore) | The same kind of app packaged for Amazon Bedrock AgentCore Runtime. |
| [AgentCore workspace app](https://github.com/everruns/everruns/tree/main/examples/serve/agentcore-workspace) | An AgentCore workspace agent with a shell in the microVM and an approval. |
| [A2A example](https://github.com/everruns/everruns/tree/main/examples/serve/a2a) | Two agents over A2A: a served `researcher`, and an `everruns` agent that delegates to it. |
| [Voice example](https://github.com/everruns/everruns/tree/main/examples/serve/voice) | A hotel front desk people call from the browser, with a greeting and a speaking style. |
## Project layout
The file layout says what each piece is:
```text
revenue-analyst/
build.rs # serve_build::embed()
serve.toml # name, sandbox, extra secrets
agent/
instructions.md # always-on prompt
skills/sql-style/SKILL.md
src/
main.rs # serve::assets!() + serve::start(...)
agent.rs # #[agent]
tools/run_sql.rs # #[tool]
channels/slack.rs # #[channel]
schedules/weekly.rs # #[schedule]
connections/linear.rs # #[connection]
subagents/reviewer.rs # #[agent(sub)]
evals/revenue.rs # #[eval]
```
The macros register each item at link time and `discover()` collects them; `build.rs` embeds `agent/**` and `serve.toml` into the binary. `discover()` reports every problem in the app at once, such as duplicate names, a bad cron expression or a filter naming an unknown tool.
## The pieces
| Macro | On | Becomes |
| -------------------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `#[agent]`, `#[agent(default)]`, `#[agent(sub)]` | `fn() -> Agent` | An agent. New sessions use the default one; a subagent becomes an `ask_` tool on the others. |
| `#[tool]`, `#[tool(needs_approval)]`, `#[tool(needs_approval = \|a: &Args\| …)]` | `async fn([cx: &Cx,] args…) -> Result` | A tool named after the function, described by its doc comment. It also generates an arguments struct (`run_sql` → `RunSql`) with a JSON Schema. |
| `#[channel]` | `fn() -> impl Into` (a driver such as `Slack` or `Webhook`) | `POST /v1/channels/{name}`. Each external thread maps to one session, and replies are delivered back while the turn runs. `agent = "…"` picks the agent. |
| `#[schedule("0 9 * * MON")]` | `async fn(&Cx) -> Result` | A cron entry. A 5-field cron counts weekdays 0-6 from Sunday (7 is also Sunday), so `0 9 * * 1-5` runs Monday through Friday. |
| `#[connection]` | `fn() -> T` or `fn() -> Result` | A value tools read with `cx.connection::()`. An `McpServer` connection is attached to every agent. |
| `#[eval]` | `async fn(&mut EvalCx) -> Result` | A conversation with assertions, run in-process or against a deployment. |
`Cx` is the one context type. Inside a tool it wraps the Framework’s `ToolCallContext` (session, turn and tool call ids, and `progress`) and adds typed connections, secrets and `start_session`. Approval rules are declared on the tool and enforced by the runtime.
## Commands
The commands are built into the app binary, because only the linked binary knows what it registered.
| Command | What it does |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dev` (default) | Serves the API with local SQLite under `.serve/` and a live console. Models fall back to the simulator, and Markdown prompts and skills hot-reload. |
| `start` | Production mode. Every model must route through a gateway, and every declared secret must be set. With `--store s3://bucket/prefix` (or `SERVE_STORE`) the data lives in a bucket; see [Keep the data in a bucket](#keep-the-data-in-a-bucket). |
| `manifest` | Prints the host contract as JSON: agents, models, tool schemas, skills, channels, cron entries, secrets, sandbox, evals and a build id. |
| `eval [--against URL]` | Runs the evals in-process, or against a running deployment as a gate before promotion. Against an app that requires a credential, set `SERVE_CREDENTIAL` (or pass `--credential`) and every request carries it as a bearer token. |
| `deploy` | Prints what a host would provision from the manifest. The one supported deployment target is [Amazon Bedrock AgentCore](https://everruns.com/docs/framework/serve-agentcore/). |
Sessions that an earlier release kept in the data directory’s `everruns/` folder move to the current session store the first time they are opened, with their history and their shared workspace files. Subagent sessions they started move with them and are linked to their parent. A session that cannot move returns an error; it is never served as missing or empty.
## Keep the data in a bucket
`start --store s3://bucket/prefix` keeps a daemon’s data in an S3 bucket, or in any S3-compatible store that supports conditional writes (R2, MinIO, GCS, Tigris, SeaweedFS). The data directory becomes a local working copy:
* At boot the daemon takes the bucket’s lease, then rebuilds the data directory from the bucket. Files the bucket does not have are removed.
* While it runs, every change is copied to the bucket within about a fifth of a second: databases by the pages that changed, other files (the agents’ workspace) whole.
* A daemon started on another machine with the same `--store` waits for the old one’s lease to expire (15 seconds), rebuilds the data directory, and resumes the turns the old one was running. While the old daemon is still alive and renewing, the new one refuses to start. If the old one wakes up after it was replaced, its next write fails and it stops.
* A clean shutdown (Ctrl+C) copies what is left and releases the lease, so the next daemon starts at once.
Credentials, region and endpoint come from the standard `AWS_*` environment variables. For an S3-compatible store set `AWS_ENDPOINT`, and `AWS_ALLOW_HTTP=true` for a plain-HTTP endpoint. Keep the data directory at the same absolute path on every machine (`SERVE_DATA_DIR`), because a session’s workspace records it.
A crash can lose the changes of its last fifth of a second. One daemon holds a bucket prefix at a time; give each daemon its own prefix.
## Wire API
A serve app speaks a subset of the Everruns server `/v1` API, with the same request and response bodies:
* `POST /v1/sessions` and `GET /v1/sessions/{id}`
* `POST /v1/sessions/{id}/messages`, which also steers an active turn. Its `files` list sends files as base64 `data` or a public `url`, as on the [Agent API](https://everruns.com/docs/how-to/call-your-agent-from-code/#send-files); each is kept in the session’s `/attachments` folder
* `POST /v1/sessions/{id}/cancel`
* `GET /v1/sessions/{id}/sse` (resume with `since_id` or `after_sequence`) and `GET /v1/sessions/{id}/events`
* `POST /v1/sessions/{id}/question-answers`, for [`ask_user`](https://everruns.com/docs/framework/ask-user/) questions
* `POST /v1/sessions/{id}/tool-approvals`, to allow or reject pending tool calls
It adds a few routes of its own: `GET /health`, `GET /v1/agent` (the agent card), channel webhooks, the [AG-UI](#ag-ui-and-copilotkit), [A2A](#a2a) and [voice](#voice) routes, and `POST /v1/sessions/{id}/approvals/{tool_call_id}` to approve or deny one pending tool call. Errors are `application/problem+json`.
### One agent’s API
Every top-level agent also has its own base URL, `/v1/channels/{agent}`, with the same session routes rooted under it: `GET` returns the agent’s card, `POST /v1/channels/{agent}/sessions` starts a session that runs that agent, and `/v1/channels/{agent}/sessions/{id}/…` carries messages, events, cancellation, questions and approvals. A session is reachable only under its own agent’s URL. This is the API an Everruns agent exposes through an API channel, so code written against one agent works against either host. Every SDK’s `AgentClient` calls this API; see the [tutorial](https://everruns.com/docs/framework/serve-tutorial/#6-call-it-from-code). The [Agent API](https://everruns.com/docs/features/agent-api/) reference documents the routes and shapes, and [what differs on serve](https://everruns.com/docs/features/agent-api/#the-same-api-on-serve).
### Authentication
By default the wire API has no authentication and no organizations: run it locally, or behind a host that authenticates requests. Configure one or more methods and every agent route requires `Authorization: Bearer `; anything else gets `401` with `WWW-Authenticate: Bearer`. The methods are the ones an Everruns API channel accepts, checked by the same verifier:
* **API keys.** Static keys, compared in constant time. Set them in `SERVE_API_KEYS`, comma separated.
* **OpenID Connect.** JWTs from an issuer, checked against the keys its discovery document publishes, with a required audience.
* **OAuth 2.0 introspection.** Opaque tokens checked at an RFC 7662 endpoint.
Token methods take the same requirements as a channel: audiences, scopes, subjects, groups, email domains and exact claim values. Methods add up from code, `serve.toml` and the environment:
```rust
use serve::auth::AuthMethod;
let server = serve::Server::builder(app, serve::Mode::Start)
.auth([AuthMethod::oidc("https://login.example.com", ["support-agent"])])
.build()?;
```
serve.toml
```toml
[[auth.methods]]
mode = "oidc"
provider = { type = "oidc", issuer = "https://login.example.com" }
requirements = { audiences = ["support-agent"], scopes = ["agent:call"] }
```
```sh
SERVE_API_KEYS=key-for-ci,key-for-the-web-app ./revenue-analyst start
```
`serve.toml` also takes `api_keys = [...]` under `[auth]`, but it is embedded in the binary, so keep real keys in the environment.
A few routes stay public so clients can find the agent: `GET /health`, each agent’s card at `GET /v1/channels/{agent}` (its `auth` list names the accepted methods), the A2A Agent Card (its `securitySchemes` and `securityRequirements` name the same methods, as an Everruns A2A endpoint’s card does) and the voice test page. Messaging channel webhooks stay public too, because Slack and webhook callers cannot send a serve credential; each channel verifies its platform’s own signature. Auth does not separate callers: every authenticated caller can reach every session.
With auth on, the `dev` console’s sample requests and its approval and question hints include `-H 'authorization: Bearer '`; substitute your own key. To run evals against a protected deployment, give `eval` the credential through the environment, which keeps it out of the process list:
```sh
SERVE_CREDENTIAL=key-for-ci ./revenue-analyst eval --against https://preview.example.com
```
## AG-UI and CopilotKit
With the `ag-ui` feature, every top-level agent also serves [AG-UI](https://docs.ag-ui.com) 1.0 clients such as CopilotKit and `@ag-ui/client`:
```sh
cargo add everruns-serve --features ag-ui
```
The route is `POST /v1/channels/{agent}/ag-ui`, the same shape as an Everruns endpoint’s AG-UI route, so a front end moves between a local serve app and Everruns by base URL and id alone:
```ts
import { HttpAgent } from "@ag-ui/client";
const agent = new HttpAgent({ url: "http://localhost:3000/v1/channels/analyst/ag-ui" });
```
Each AG-UI `threadId` maps to one session, which survives a restart. A thread’s first run records the input’s earlier user and assistant messages as the new session’s history; after that, a run sends only the input’s last user message. Each run streams the turn as AG-UI events, with reasoning, token usage and errors visible. A tool approval or an [`ask_user`](https://everruns.com/docs/framework/ask-user/) question ends the run with an interrupt (`tool_approval` or `everruns.ask_user`), and the next run’s `resume` entries answer it and stream the rest of the turn. These are the same pending requests the approvals and `question-answers` routes answer, so either API can resolve them. Input that is not a valid `RunAgentInput` gets `400`, and an unknown agent `404`. The agent card lists each agent’s route under `ag_ui`. See [Serve AG-UI](https://everruns.com/docs/framework/ag-ui/) for the event and interrupt shapes.
## A2A
With the `a2a` feature, every top-level agent also serves other agents over [A2A](https://a2a-protocol.org) 1.0 JSON-RPC:
```sh
cargo add everruns-serve --features a2a
```
The endpoint is `POST /v1/channels/{agent}/a2a` and its Agent Card is `GET /v1/channels/{agent}/a2a/.well-known/agent-card.json`, the shape of an Everruns A2A endpoint. Any A2A 1.0 client works, including the official `a2a` CLI and another Everruns agent’s `a2a_agent_delegation` capability:
```sh
a2a send -a http://localhost:3000/v1/channels/researcher/a2a/.well-known/agent-card.json "Tide pools"
```
Each A2A `contextId` maps to one session, which survives a restart; each task is one turn. A task streams `working`, then the final reply as a `response` artifact, then `completed` (or `failed`). `GetTask`, `ListTasks`, `CancelTask` and `SubscribeToTask` come from the A2A Rust SDK’s request handler; tasks are kept in memory, so old task ids are forgotten on restart while their context continues. Requests need the `A2A-Version: 1.0` header. A pending approval or `ask_user` question keeps the task `working` until the routes above answer it. The agent card lists each agent’s endpoint under `a2a`. [Framework A2A](https://everruns.com/docs/framework/a2a/) covers serving and calling A2A agents, and [A2A example](https://github.com/everruns/everruns/tree/main/examples/serve/a2a) shows a served agent and a second agent that delegates to it.
Sessions survive a restart: the binary rebuilds each agent and resumes the session from the local store. A turn the old process left waiting on an approval or an `ask_user` question waits again: the call runs again, so the request is pending once more under the same tool call id, and answering it finishes the turn. A turn cut off while a tool executed is not re-run. A session pinned to a different build gets `409 Conflict` with an `x-serve-build` header, so a host can route it to the build that owns it.
## Voice
With the `voice` feature, every top-level agent also takes browser calls through a [voice channel](https://everruns.com/docs/framework/voice/):
```sh
cargo add everruns-serve --features voice
```
`POST /v1/channels/{agent}/voice/calls` takes the browser’s WebRTC offer and answers the SDP answer, the call id and the session id; `POST /v1/channels/{agent}/voice/calls/{call_id}/end` hangs up, and `GET /v1/channels/{agent}/voice` is a test page with a **Start call** button. Each utterance is a user message on an ordinary session, so a call can continue a typed conversation. The optional `[voice]` section of `serve.toml` sets the voice, greeting and speaking style for every agent. Speech uses OpenAI with `OPENAI_API_KEY`; without it, `dev` and `eval` use the offline simulator and `start` refuses calls. The agent card lists each agent’s route under `voice.endpoints`. See [Build a voice agent](https://everruns.com/docs/framework/voice/).
## Limitations
* After a restart, an approval answered “always” before it is asked again, and a request parked by a subagent is lost.
* A2A tasks are held in memory, and A2A 0.3 clients are not served.
* A deny note is not passed to the model.
* There is no generic OCI build or Postgres or NATS adapter. [AgentCore](https://everruns.com/docs/framework/serve-agentcore/) is the one supported deployment target.
* The server’s agent, harness, workspace and tool-result routes are not served.
## Amazon Bedrock AgentCore
[`everruns-serve-agentcore`](https://docs.rs/everruns-serve-agentcore) runs a serve app on AgentCore Runtime. Replace `serve::start` with `serve_agentcore::start` in `main`. With no command, the binary then serves AgentCore’s contract on port 8080: `GET /ping` and `POST /invocations`, which takes an AG-UI `RunAgentInput` or `{"prompt": "..."}` and streams AG-UI events. serve’s own commands keep working. See [Serve on AgentCore](https://everruns.com/docs/framework/serve-agentcore/) for deployment, persistence on session storage, tools and models.
## celld
[`everruns-serve-celld`](https://docs.rs/everruns-serve-celld) runs a serve app durably on [celld](https://github.com/denoland/celld), self-hosted Durable Objects. Replace `serve::start` with `serve_celld::start`; the binary then runs in a container that a Durable Object supervises, and the object keeps a snapshot and a request journal so a lost container is restored and its interrupted turn replayed. See [Serve on celld](https://everruns.com/docs/framework/serve-celld/).
The full guide, wire reference and hosting contract live next to the crate in [serve reference guides](https://github.com/everruns/everruns/tree/main/crates/serve/docs).
## File-based agents
Load and export the shared portable package format, including initial files and complete skill directories. See [Define agents as files](https://everruns.com/docs/how-to/define-agents-as-files/) for validation, diffs, model bindings and runnable examples.
---
# Serve on Amazon Bedrock AgentCore (experimental)
> Deploy a serve app to Amazon Bedrock AgentCore Runtime with everruns-serve-agentcore: sessions on session storage, tools in the microVM, models via the Gateway.
Source: .amazonaws.com/runtimes//ws?qualifier=DEFAULT`) with the same session header, and send one invocation body per text message. Each AG-UI event comes back as its own text message, ending with `RUN_FINISHED` or `RUN_ERROR`; send the next body on the same socket for the next turn.
The upgrade request is authenticated like any other call: sign it with SigV4 (service `bedrock-agentcore`), either in the headers or, where the client cannot set upgrade headers (a browser), as a presigned URL that also carries the session id as the `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` query parameter. The AWS SDKs have no WebSocket client, so sign the request yourself and hand it to a WebSocket library; the [agentcore-workspace example](https://github.com/everruns/everruns/tree/main/examples/serve/agentcore-workspace) has a Python client (`client/ws.py`) that does both.
## Persistence
AgentCore mounts session storage only when an invocation arrives, not while the container initializes. So `/ping` never touches storage, and the server boots on the first other request. It then picks, in order:
1. `SERVE_DATA_DIR` (or a SQLite `DATABASE_URL`) when set. The workspace is `SERVE_WORKSPACE`, else `workspace/` under the data dir.
2. `/mnt/workspace` when it is mounted: the session log goes to `/mnt/workspace/.serve`, and the agent’s workspace is `/mnt/workspace`.
3. Otherwise a temporary directory, with a warning that nothing survives the microVM stopping.
With session storage, a conversation survives AgentCore stopping the microVM after its idle timeout: the next invocation with the same session id resumes it from the log. That includes a turn parked on an approval or an `ask_user` question: on the new microVM the interrupt is still open, and the client’s resume run answers it as before.
Session storage is an NFS mount that refuses POSIX file locks, so the binary switches SQLite to dot-file locking (`unix-dotfile`) and rollback-journal mode for the whole process, and clears lock files a stopped microVM left behind. That is safe because one process owns a session’s storage.
Session storage is per session, kept for 14 days, and reset when you deploy a new runtime version. For history across sessions and versions, point `DATABASE_URL` at storage you own, such as an S3 Files or EFS mount (both need VPC mode).
## Tools
* **In-process tools.** `#[tool]` functions run in the container like anywhere else, including `needs_approval` tools: over AG-UI the run ends with a `tool_approval` interrupt and the client’s next run answers it.
* **A real shell.** With `[sandbox] kind = "microvm"` in `serve.toml`, each agent gets `bash` and file tools in the session’s workspace, running directly in the container. The microVM is the isolation boundary, so there is no second sandbox inside it. Under `dev` and `eval` the same setting uses the bashkit virtual shell, so local runs stay safe. Install whatever the agent should run (git, python, a compiler) in the image, as the [workspace example](https://github.com/everruns/everruns/tree/main/examples/serve/agentcore-workspace) Dockerfile does.
* **AgentCore Gateway tools.** A Gateway is an MCP server, so connect it like any other:
```rust
#[connection]
fn gateway() -> McpServer {
McpServer::http("https://.gateway.bedrock-agentcore..amazonaws.com/mcp")
.auth(Secret::named("GATEWAY_TOKEN"))
}
```
`start` mode, which AgentCore runs, refuses to boot when `GATEWAY_TOKEN` is unset, so a misconfigured runtime fails its first invocation instead of running without tools.
## Models
Name a Bedrock model as `bedrock/`, where the rest is a Bedrock model id or inference profile:
```rust
Agent::builder()
.model("bedrock/us.anthropic.claude-sonnet-4-6")
```
When `AWS_REGION` or `AWS_DEFAULT_REGION` is set, serve calls Amazon Bedrock directly with the runtime’s execution role: no keys in the image or the environment. Credentials come from the AWS default chain, which on AgentCore is the execution role’s container credentials, and refresh before they expire. The role needs `bedrock:InvokeModelWithResponseStream` on the model; for a cross-region inference profile such as `us.…`, on the profile and on the foundation model in each region it routes to. Pass the region in `--environment-variables` if the runtime does not already provide it. This route is serve’s `bedrock` feature, on by default in `everruns-serve-agentcore`; `default-features = false` drops it and the AWS SDK.
Other `provider/model` ids go through serve’s gateway. Set `SERVE_GATEWAY_URL` to an AgentCore Gateway inference endpoint (`https:///inference/v1`) with targets named after providers (`anthropic`, `openai`), and `anthropic/claude-sonnet-5` routes as-is. Provider API keys then stay in the Gateway’s credential providers instead of the runtime’s environment.
## Configuration
| Variable | Meaning |
| ---------------------------------------- | ----------------------------------------------------------------------- |
| `PORT` | Listen port, default `8080` (AgentCore requires 8080) |
| `SERVE_AGENTCORE_AGENT` | The agent `/invocations` runs, default the app’s default agent |
| `SERVE_DATA_DIR`, `DATABASE_URL` | Where the session log lives. Default: session storage when mounted |
| `SERVE_WORKSPACE` | The agent’s workspace. Default: the session storage mount |
| `SERVE_GATEWAY_URL`, `SERVE_GATEWAY_KEY` | serve’s model gateway |
| `AWS_REGION`, `AWS_DEFAULT_REGION` | Region for `bedrock/` models, which run on the execution role |
## Compared with other AgentCore agents
| | serve-agentcore | Strands / `bedrock-agentcore` SDK |
| --------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------- |
| `/ping`, `/invocations`, busy reporting | Yes | Yes |
| AG-UI protocol | Yes, AG-UI 1.0 including interrupts | Yes |
| `/ws` WebSocket | Yes | Yes |
| MCP and A2A server protocols | Not yet | Yes |
| Conversation persistence | SQLite on session storage, including a turn parked on an approval or question | File or AgentCore Memory session managers |
| Long-term memory (AgentCore Memory) | Not yet | Yes |
| Gateway tools | MCP connection | MCP client |
| Shell and files | Built-in (`sandbox = "microvm"`) | Bring your own tools |
| Code Interpreter, Browser | Not yet | Client libraries |
| Identity (OAuth to third parties) | Secrets from the environment | `@requires_access_token` |
| Offline evals and simulator | Yes (`eval`, `--dev`) | No |
## Limits
* Approvals and `ask_user` questions park a turn without keeping the microVM busy. AgentCore may stop the microVM while one waits; with session storage the next microVM asks it again, but an “always” answer given before the restart is not remembered after it, and a request a subagent parked is lost.
* `#[schedule]`s run in-process, so they only fire while a session’s microVM is up. Use EventBridge to call `InvokeAgentRuntime` on a schedule instead.
* Only `bedrock/…` models use the runtime’s execution role. Other providers need the gateway or their own keys. The role must allow `bedrock:InvokeModelWithResponseStream`; a missing permission surfaces as an `AccessDeniedException` on the first turn.
## Reference
* [`everruns-serve-agentcore` API reference](https://docs.rs/everruns-serve-agentcore)
* [AgentCore AG-UI protocol contract](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-agui-protocol-contract.html)
* [AgentCore session storage](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-persistent-filesystems.html)
---
# Serve on celld (experimental)
> Run Framework Engine sessions on celld with per-session Durable Object authority and replaceable native execution.
Source: ` routing and `/celld/snapshot`/`restore` protocol are removed. Existing deployments using that experimental protocol need an explicit migration; their snapshots are not the new authority format.
See the [runnable example](https://github.com/everruns/everruns/tree/main/examples/serve/celld) for setup and deployment. The [isolate example](https://github.com/everruns/everruns/tree/main/examples/celld-engine) uses the same Framework Agent and Engine as Cloudflare, without a container or a celld-specific agent loop. Workerd tests and a local replicated fleet establish only their tested failure modes; production bucket consistency, alarms, build retention and workspace persistence remain deployment responsibilities.
---
# Tutorial: Serve an Agent and Call It from Code
> Build an agent with serve, protect it with an API key, and call it from Python, TypeScript or Rust with the SDK's AgentClient.
Source: {
cx.progress(format!("looking up order {order}")).await;
// A real app would query its order database here.
match order {
42 => Ok("Shipped October 9 with UPS, tracking 1Z999AA10123456784, arrives October 13.".into()),
43 => Ok("Paid. Ships within two business days.".into()),
_ => bail!("there is no order {order}"),
}
}
```
`src/tools/mod.rs` declares it:
```rust
mod order_status;
```
Finally the agent and `main` in `src/main.rs`:
```rust
mod tools;
use serve::prelude::*;
/// Answers questions about orders.
#[agent]
fn support() -> Agent {
Agent::builder()
.model("openai/gpt-6.1-sol")
.instructions(md!("instructions.md"))
.build()
}
serve::assets!();
#[tokio::main]
async fn main() -> serve::Result {
serve::start(serve::App::builder().discover().build()).await
}
```
`#[agent]` and `#[tool]` register the function where it is defined, and `discover()` collects them, so nothing lists the tool by hand. The agent’s doc comment is its description, and its function name, `support`, is its name in URLs.
## 3. Run it
```sh
export OPENAI_API_KEY=sk-...
cargo run
```
The first build takes a few minutes. Then the app prints what it found:
```text
serve · order-desk 0.1.0 · Dev · build b49b68ee33c43b82d
⚠ experimental proof of concept; APIs will change
agent support (default) · openai/gpt-6.1-sol → openai
tool order_status
sandbox none
data .serve
listen http://localhost:3000
```
`→ openai` says the model goes to OpenAI with your key. If it says `simulator`, `OPENAI_API_KEY` is not set in this shell. A set `OPENROUTER_API_KEY` or `SERVE_GATEWAY_URL` takes precedence over `OPENAI_API_KEY`; see [Try it](https://everruns.com/docs/framework/serve/#try-it).
`cargo run` with no command is `dev`: sessions are kept in SQLite under `.serve/`, the terminal shows each turn as it happens, and edits to `instructions.md` apply without a rebuild.
## 4. Talk to it with curl
The agent’s API lives at its own base URL, `/v1/channels/support`. In a second terminal, read its card:
```sh
curl -s localhost:3000/v1/channels/support
```
```json
{"name":"support","description":"Answers questions about orders.","streaming":true,"input":{"text":true,"images":true,"files":true},"auth":[],"links":{"sessions":"/v1/channels/support/sessions"}}
```
Start a session, send a message, and follow the session’s events:
```sh
AGENT=localhost:3000/v1/channels/support
ID=$(curl -s -X POST $AGENT/sessions -H 'content-type: application/json' -d '{}' | jq -r .id)
curl -s -X POST $AGENT/sessions/$ID/messages -H 'content-type: application/json' \
-d '{"message":{"role":"user","content":[{"type":"text","text":"Where is order 42?"}]}}'
curl -N "$AGENT/sessions/$ID/sse?after_sequence=0"
```
The stream shows the turn as server-sent events: `turn.started`, `tool.started` and `tool.completed` for the lookup, `output.message.delta` as the answer streams, and `turn.completed`. The stream stays open for the next turn; stop it with Ctrl+C. The first terminal shows the same turn:
```text
21:42:34 4cc33a ● new session on support
21:42:34 4cc33a ▸ Where is order 42?
21:42:36 4cc33a ⚙ order_status {"order":42}
21:42:36 4cc33a … looking up order 42
21:42:36 4cc33a ✓ order_status
21:42:38 4cc33a ◂ Order 42 shipped on October 9 via UPS and is expected to arrive October 13. Your tracking number is **1Z999AA10123456784**.
```
## 5. Protect it with an API key
Anyone who can reach port 3000 can use the agent so far. Stop the app with Ctrl+C, make a key, and start it in production mode with that key:
```sh
export AGENT_KEY=$(openssl rand -hex 32)
SERVE_API_KEYS=$AGENT_KEY cargo run -- start
```
`start` is production mode: a model with no route is an error instead of a simulator. `SERVE_API_KEYS` takes a comma-separated list, so each application can get its own key and you can rotate one at a time. Keep keys in the environment: `serve.toml` is compiled into the binary.
The startup banner’s sample requests now carry an `authorization` header. Without a key, every session route answers `401`:
```sh
curl -si -X POST localhost:3000/v1/channels/support/sessions -H 'content-type: application/json' -d '{}'
```
```text
HTTP/1.1 401 Unauthorized
www-authenticate: Bearer
...
{"detail":"a valid bearer credential is required","status":401,"title":"Unauthorized"}
```
With the key as a bearer token it works again:
```sh
curl -s -X POST localhost:3000/v1/channels/support/sessions \
-H "authorization: Bearer $AGENT_KEY" -H 'content-type: application/json' -d '{}'
```
The card stays public so clients can find the agent, and its `auth` list now says which credential it takes: `"auth":[{"type":"agent_key"}]`. API keys are one of three methods; [Authentication](https://everruns.com/docs/framework/serve/#authentication) covers OpenID Connect and OAuth 2.0 introspection.
## 6. Call it from code
Every Everruns SDK has an `AgentClient` for one agent’s API. It reads the agent’s base URL from `EVERRUNS_AGENT_URL` and the credential from `EVERRUNS_AGENT_KEY`, and sends the credential as a bearer token. In the terminal where you will run the client:
```sh
export EVERRUNS_AGENT_URL=http://localhost:3000/v1/channels/support
export EVERRUNS_AGENT_KEY=$AGENT_KEY # the key from step 5
```
Pick one language.
### Python
```sh
python3 -m venv .venv
. .venv/bin/activate
pip install "everruns-sdk>=0.3.1"
```
Save this as `ask.py`:
```python
import asyncio
from everruns_sdk import AgentClient
async def main():
async with AgentClient() as agent:
card = await agent.card()
print(f"Agent: {card['name']}")
session = await agent.create_session()
print(await agent.run("Where is order 42?", session["id"]))
print(await agent.run("And order 43?", session["id"]))
asyncio.run(main())
```
```sh
python ask.py
```
```text
Agent: support
Order 42 shipped October 9 via UPS and is expected to arrive October 13. Your tracking number is **1Z999AA10123456784**.
Order 43 is paid and will ship within two business days.
```
### TypeScript
```sh
npm init -y
npm pkg set type=module
npm install @everruns/sdk tsx
```
Save this as `ask.ts`:
```typescript
import { AgentClient } from "@everruns/sdk";
const agent = new AgentClient();
const card = await agent.card();
console.log(`Agent: ${card.name}`);
const session = await agent.createSession();
console.log(await agent.run("Where is order 42?", session.id));
console.log(await agent.run("And order 43?", session.id));
```
```sh
npx tsx ask.ts
```
### Rust
```sh
cargo new ask
cd ask
cargo add everruns-sdk tokio --features tokio/full
```
Replace `src/main.rs`:
```rust
use everruns_sdk::AgentClient;
#[tokio::main]
async fn main() -> Result<(), Box> {
let agent = AgentClient::from_env()?;
println!("Agent: {}", agent.card().await?.name);
let session = agent.create_session(None, None).await?;
println!("{}", agent.run("Where is order 42?", Some(&session.id)).await?);
println!("{}", agent.run("And order 43?", Some(&session.id)).await?);
Ok(())
}
```
```sh
cargo run
```
TypeScript and Rust print the same three lines as Python.
`run` sends one message, follows the event stream until the turn ends, and returns the agent’s reply. Passing the session id keeps both questions in one conversation, which is why “And order 43?” needs no more context. Without a session id, `run` starts a new session each time. For more control, the client has the session calls directly: `create_session`, `send_message`, `stream_events`, `list_events`, `cancel`, and the answers to questions and tool approvals.
## What you built
* A serve app with one agent and one tool, running on a real model.
* An API key in front of the agent’s session routes, with the card left public.
* A client that holds only that key and the agent’s URL.
The same client code works against an agent hosted on Everruns: point `EVERRUNS_AGENT_URL` at the agent’s Agent API channel and use an agent key. See [Call your agent from code](https://everruns.com/docs/how-to/call-your-agent-from-code/) and the [Agent API](https://everruns.com/docs/features/agent-api/) reference.
## Next steps
* Hold a tool call for a person’s approval with `#[tool(needs_approval)]`, and answer it with `submit_tool_approvals`. See [The pieces](https://everruns.com/docs/framework/serve/#the-pieces).
* Check the agent’s behavior with `#[eval]` and `cargo run -- eval`. To run the evals against the protected app, set `SERVE_CREDENTIAL=$AGENT_KEY` and pass `--against http://localhost:3000`.
* Run the app on [Amazon Bedrock AgentCore](https://everruns.com/docs/framework/serve-agentcore/), or keep its data in a bucket with [`start --store`](https://everruns.com/docs/framework/serve/#keep-the-data-in-a-bucket).
---
# Session Controls
> Run slash commands, hot-install capabilities, switch model, reasoning effort and MCP servers, and query session context on a live Engine session.
Source: /`, read-only, and returns the part that sends it with a message. The model gets images and PDFs as content and other files by name and path, and can open any of them again with `read_file`, including after compaction. A zip is unpacked into a read-only folder next to it.
```rust,no_run
use everruns::InputMessage;
let report = session
.attach("report.pdf", Some("application/pdf"), std::fs::read("report.pdf")?)
.await?;
let mut message = InputMessage::user("Summarize the attached report.");
message.content.push(report);
session.run(message).await?;
```
The bytes decide the file’s type, whatever the caller declared. Embedded channels keep the files people send (a Slack file, for example) the same way.
## History and resume
Every Framework session has a typed `SessionId`. Keep that value when an application may need to reopen the conversation:
```rust
use everruns::{Agent, Engine, OpenAI, SessionId};
let agent = Agent::builder()
.instructions("Remember the conversation.")
.provider(OpenAI::from_env()?)
.model("gpt-6.1-sol")
.build()?;
let engine = Engine::new();
let session = engine.create(agent);
let session_id: SessionId = session.session_id();
session.send_and_wait("My project is Atlas.").await?;
drop(session);
let resumed = engine.resume(session_id).await?;
resumed.send_and_wait("Continue with that project.").await?;
```
`resume` verifies the ID against the engine’s session catalog. It does not infer identity from a non-empty transcript: a valid session can have no messages, and stray events do not create a resumable session. An unknown ID returns a typed not-found error. The resumed session uses the immutable Agent snapshot attached to that engine; it never reconstructs behavior from events.
### Read bounded history
`Session::history` creates an owned query. Calling `page` returns at most 100 messages by default in canonical event-sequence order, oldest first:
```rust
let page = session.history().page().await?;
for message in &page.messages {
println!("{:?}: {}", message.role, message.text());
}
```
Set a smaller or larger page size with `limit`. The maximum is 256 messages; an excessive value returns `HistoryError::InvalidLimit` with the allowed maximum. A page never claims to contain the entire transcript. Continue from its opaque cursor:
```rust
let first = session.history().limit(25)?.page().await?;
if let Some(cursor) = first.next_cursor {
let second = session.history().limit(25)?.after(cursor)?.page().await?;
// `second` continues the same stable snapshot.
}
```
`HistoryCursor` is opaque, session-bound, and safe to store as a string with `Display` and restore with `FromStr`. A cursor fixes the snapshot’s high-water mark: events appended after the first page do not appear midway through that page walk. Start a new query to see them. Passing a malformed, cross-session, expired, or incompatible cursor returns a distinct typed history error. History projection also applies a bounded raw-event replay safety limit; an unusually lifecycle-heavy snapshot that exceeds it returns `HistoryError::HistoryTooLarge` instead of performing an unbounded scan.
For callers that intentionally walk the whole snapshot, `pages` is a lazy convenience that still reads one bounded page at a time:
```rust
let mut pages = session.history().limit(50)?.pages();
while let Some(page) = pages.next_page().await? {
for message in page.messages {
println!("{}", message.text());
}
}
```
After the final page, `next_page` remains fused and returns `None`. It does not re-read the backend or produce repeated empty terminal pages.
## Persistence
Framework history is a read-only projection of canonical events. Normal execution has one write path, the engine’s event log, so a resumed session and a running session cannot disagree about the conversation.
| Deployment | Conversation state | Recovery boundary | Use when |
| --------------------------- | ----------------------------------------------- | ------------------------------------------ | -------------------------------------------- |
| `Engine::new()` | Volatile coherent memory authority | One process | Embedding, tests and short-lived tools |
| Engine with `SqliteHosting` | Transactional local session authority | The configured disk plus native supervisor | Durable single-node Framework services |
| Engine with `ObjectHosting` | Per-session object authority | Platform storage and alarms | Native or Wasm execution on Cloudflare/celld |
| Legacy `LocalConfig` | Local canonical events and catalog | One trusted application process | Existing local-store integrations |
| Everruns Platform | PostgreSQL canonical events and actor authority | Distributed server and workers | Horizontal workers and remote clients |
### Default: engine-lifetime memory
By default, `Engine` owns a volatile session catalog and event log. It retains the immutable Agent snapshot associated with each session and requires no database, server, network connection, credential, or filesystem access.
Dropping a `Session` does not immediately discard its committed history. Reopen it by passing its typed `SessionId` to the engine that created it. A separate engine cannot infer the session’s Agent configuration, and process exit loses volatile history.
This default fits tests, command-line tools, short-lived workers, and applications that deliberately own a higher-level record elsewhere.
### Coherent native and Durable Object hosting
For durable admission and independently recoverable execution, choose a coherent session authority on Engine. Native `hosting::SqliteHosting` owns one transactional database; the [session hosting SPI](https://everruns.com/docs/framework/hosting/) supports external authorities for native or Wasm Engine placement. A source-only Durable Object reference demonstrates the extension. Register immutable `AgentBuild` identities and retained Environment factories before creating sessions. Start the native supervisor or configure platform alarms so recovery does not depend on a client reconnecting. See [Durable Object hosting](https://everruns.com/docs/framework/durable-objects/).
`create_registered` and `send_with_id` accept caller-retained identities for retry after uncertain responses. Admissions, approvals, client results and cancellation are authority commands; the journal and wakeup obligation commit together. Resources such as workspace files and compute still require explicit host services.
### Local: crash-durable events
For local applications, the feature-gated `LocalConfig` adds a crash-durable event log under the configured application data directory. It also supplies a trusted real-disk workspace plus SQLite-backed task and schedule state:
```rust
use everruns::{Agent, Engine, LocalConfig, OpenAI};
let local = LocalConfig::new(".everruns-data").workspace("./workspace");
let agent = Agent::builder()
.instructions("Work inside the configured workspace.")
.provider(OpenAI::from_env()?)
.model("gpt-6.1-sol")
.local(local)
.build()?;
let engine = Engine::new();
let session = engine.create(agent);
```
Enable it with `cargo add everruns --features local`. Select both directories from trusted application configuration. After a restart, rebuild the Agent from trusted application configuration, attach it to a new engine, and resume the committed session by ID. For a session created with an explicit Harness, also deserialize its portable definition and call `Engine::attach_with_harness`; `Engine::attach` remains the no-Harness path.
The local profile is designed for one embedded process at a time. Coordinate process ownership before handing the directory to another application process. Within one process, every live Engine configured with the same local data directory shares one backend bundle, so concurrent Engine values cannot build divergent JSONL indexes or SQLite handles for that profile.
The event-log file format and host backends are not Framework APIs. Do not edit the log or build application writes around its representation. Use `Session::history` for bounded reads and `Engine::resume` to continue a session; see [History and resume](#history-and-resume) for the complete lifecycle.
Applications remain responsible for filesystem permissions, backups, retention, and selecting a data directory that is not controlled by model or request input. New local state files are created owner-only on Unix, but applications must still protect copied files and backups. Message content is application data and may be sensitive even though provider credentials are not written there by Framework configuration.
### Resume after a process restart
Enable `local` and configure a trusted application data directory when sessions must survive a new Agent or process:
```rust
use everruns::{Agent, Engine, LocalConfig, OpenAI};
let build_agent = || -> Result> {
Ok(Agent::builder()
.instructions("Remember the conversation.")
.provider(OpenAI::from_env()?)
.model("gpt-6.1-sol")
.local(LocalConfig::new(".everruns-data"))
.build()?)
};
let first_engine = Engine::new();
let session = first_engine.create(build_agent()?);
session.start().await?;
let session_id = session.session_id();
// In a later process, rebuild trusted behavior before resuming persisted state.
let restarted_engine = Engine::new();
restarted_engine.attach(session_id, build_agent()?).await?;
let resumed = restarted_engine.resume(session_id).await?;
```
The local profile stores a durable session catalog and crash-durable canonical event log alongside its workspace, task, and schedule state. After restarting, build another Agent with the same trusted data directory, call `engine.attach(session_id, agent)`, then `engine.resume(session_id)`. Attachment rejects IDs absent from that Agent’s configured local catalog. A new session is made durable by its first async operation (`run`, `inspect`, or a history page read); merely allocating a synchronous handle does not commit it.
A running turn, or one waiting on a person (a tool approval or an `ask_user` question), lives inside the process, so a process exit leaves it in the log without an end. After resuming, `resumed.interrupted_turn()` reports such a turn and the tool calls it had not finished, and `resumed.resume_interrupted_turn()` continues it in the same turn. A call runs again only when that is safe: it waited on a person, which asks the approver or `ask_user` responder again under the same tool call id, its tool is marked `FunctionTool::idempotent()`, or it never started (the log has no `tool.started` for it). Any other unfinished call is recorded as interrupted (listed in `not_rerun`), so the model learns its outcome is unknown and nothing runs twice. A turn cut off between steps reasons again.
For a session created with an explicit Harness, persist its serialized portable definition, deserialize it after restart, and call `engine.attach_with_harness(session_id, agent, harness)` instead. Harness deserialization validates the definition and generates a new process-local runtime identity.
The local profile is for one embedded process at a time. Do not write or edit its files as application data: messages are a read-only projection of committed events, and the storage formats are not Framework APIs.
History does not contain model credentials or application secrets unless an application deliberately includes them in message content or event metadata. Choose and protect the local data directory accordingly.
### Canonical host persistence
Durable conversation truth belongs to canonical events; history and context are projections of that record. Advanced hosts use `EventLog` and `EventHistory` from `everruns-core` (`host` feature), including `JsonlEventLog` when a local append-only event log is appropriate. Framework applications continue sessions with `Engine::resume` and traverse bounded event-derived pages from `Session::history`.
A host that needs its own storage implements the public `EventLog`/`EventReader` SPI and supplies it through `HostBackends::with_event_log`; see [Implementing a custom event log](https://everruns.com/docs/framework/events-and-cancellation/#implementing-a-custom-event-log).
`JsonlEventLog` bounds startup recovery before indexing: the default accepts at most 128 MiB and 1,000,000 canonical events. Oversize logs fail to open with a typed recovery-limit error instead of allocating or scanning without bound.
Do not design new application persistence around a legacy storage representation.
### Moving legacy sessions to `SqliteHosting`
`Engine::cut_over_legacy_session` (experimental) moves an existing `LocalConfig` or custom-backend session into `SqliteHosting` with the same `SessionId`. The import is lossless and atomic: the full event history keeps its event ids and sequences, and admissions, parked client calls and approvals, compaction checkpoints, session values, finished task records and the workspace binding come along. Retrying after a crash or a lost reply returns the same result. A cutover to a different build fails. `cut_over_legacy_session_with_metadata` also records binding metadata the legacy lane never stored, such as the `parent_session_id` of a child session.
```rust
let profile = SqliteHosting::open("authority.db")?;
let engine = Engine::builder().hosting(profile.clone()).build();
engine.register_agent_with_environment(
build.clone(),
agent.clone(),
None,
"imported-workspace",
ImportedWorkspaceFactory::new(agent, profile),
)?;
let report = engine.cut_over_legacy_session(session_id, &legacy_agent, &build).await?;
let session = engine.resume(session_id).await?;
```
The legacy lane is frozen first. After that, `Engine::attach` with the legacy Agent returns `ResumeError::CutOver` and no legacy turn starts, in any process that shares the store. The JSONL file is never written again; when a tool still needs JSONL, rebuild it from the authority with `SqliteHosting::rebuild_jsonl_export(session_id, path)`, which writes the same line format atomically and can be repeated at any time. If a cutover fails before the authority commits, the session stays frozen until you retry or call `Engine::abandon_legacy_cutover`.
The session must be quiescent. A cutover refuses, without writing anything to the authority, while a legacy turn is running or while the session has a task still running under its legacy owner. Schedules move with the session and fire from `SqliteHosting::supervise`; the legacy lane no longer delivers them. Tasks whose owner is gone move with the session; the authority re-attaches or settles them on the next activation without re-running uncertain work. Session secrets move only when the authority has secret keys (`SqliteHosting::with_secret_keys`, the same `key_id:base64_key` format as `SECRETS_ENCRYPTION_KEY`); they are stored encrypted and the cutover refuses without keys. It also refuses when the target build cannot reopen the session’s workspace head. Use `ImportedWorkspaceFactory` so the authority reopens that head after restarts. The Agent’s in-memory default workspace is not durable on either lane, so its files are not migrated; the report sets `volatile_workspace`.
### Rewinding and branching history
`SqliteHosting` keeps every event forever and tracks which events form the conversation (experimental). A branch is a list of event-sequence ranges made of whole turns. The model context, `Session::history` and `Session::events_after` follow the active branch. `SqliteHosting::export_jsonl` still returns every event with its original id and sequence. New input extends the active branch, so sequences on a branch can have gaps.
```rust
let lineage = engine.history_lineage(session_id).await?;
// Rewind to just after sequence 12; the old branch stays retained.
let ranges = lineage.rewind_ranges(12).expect("12 is on the active branch");
engine
.select_history_branch(session_id, command_id, lineage.revision, "undo-1", Some(ranges))
.await?;
// Redo: reselect the retained branch by name.
engine
.select_history_branch(session_id, redo_id, lineage.revision + 1, "main", None)
.await?;
```
A selection is accepted only when the session is quiescent: no execution, no open turn, no pending tool call or approval, and no unconsumed input. It also checks the revision you read. Anything else is refused, never queued or discarded. Retrying the same command id returns the first reply. Compaction checkpoints follow the branch too. A checkpoint can be used only on a branch that shares the history it summarized, so a summary of an abandoned branch never shows up on another branch. Checkpoints of a shared earlier part stay usable. `MemoryHosting` and other authorities without branch support refuse these calls.
To import saved history that already has branches, convert your own timeline format into a `ConversationLineage` and pass it with `Engine::cut_over_legacy_session_with_options(.., CutoverOptions::new().lineage(lineage))`. The whole journal is imported. The lineage names the active branch, the retained branches and each branch’s compaction checkpoints. A retry must pass the same lineage.
### One process runs a session at a time
Each session runs as an actor: its event log is its state, and a turn holds the session’s lease while it runs. The lease is taken when a turn starts, renewed while it runs (including while it waits on an approval or a question), and given up when the turn ends. With the local profile the leases live in the profile’s SQLite database, so if two processes share a data directory, a turn started in one while the other runs the same session fails with an error saying the session runs in another process. Between turns no process holds a session, so either one can pick it up. A lease lasts 10 seconds unless renewed, so after a crash the restarted process waits at most that long before it resumes a turn the old process was running.
### Platform: distributed durable execution
The Everruns Platform uses the same `everruns-core` (`engine` feature) turn state machine and turn loop as the Framework. The server stores each input and marks the session runnable; a worker leases the session over gRPC and runs the whole turn, and PostgreSQL stores the canonical events. If a worker disappears mid-turn, its lease expires and a later worker resumes the turn from the session’s event log.
The Platform is a deployment boundary, not another configuration mode on `everruns::Engine`. Remote applications use the Platform API or an SDK; product hosts compose the lower-level durable crates. See [Framework Architecture](https://everruns.com/docs/framework/architecture/) for the layer map.
---
# Testing and Simulation
> Test Framework applications deterministically without network access or provider credentials.
Source: -custom`, with a numeric suffix if needed. Update API or CLI calls that select that custom harness by name; calls using its ID keep working.
## 0.18
0.18 narrows `everruns-core` to the neutral execution kernel. Types that were persisted control-plane records, hosted service contracts, product composition or concrete integrations moved to the crate that owns them. The behaviour, the wire formats and the stored schema are unchanged, only the import paths.
### Retain an Engine for sessions
The Framework exposes a concrete application execution owner. The 0.18 API removes `agent.session()` and `agent.resume(id)`; applications retain the engine that owns session identity and resume authority:
```diff
let session = agent.session();
use everruns::Engine;
let engine = Engine::new();
let session = engine.create(agent);
let id = session.session_id();
let resumed = agent.resume(id).await?;
let resumed = engine.resume(id).await?;
```
`Engine` volatile resume is deliberately process-local and engine-scoped. The old `InMemoryEngine` name remains a type alias. Engine retains the immutable Agent snapshot and exact Environment/WorkspaceHead; it does not serialize a Scale-compatible Agent definition.
For a locally persisted session after process restart, rebuild the Agent from trusted application configuration, call `engine.attach(id, agent).await?`, and then `engine.resume(id).await?`. Attachment verifies the persisted session catalog before accepting the behavior snapshot; credentials and closures are never serialized.
This affects you if your Rust code imports from `everruns_core` directly. If you use the `everruns` facade, most of this is invisible: the facade re-exports what applications need, and where a moved type is part of that surface it is re-exported from its new home under the same name.
### The quickest path
Most migrations are a find-and-replace of a crate prefix. Compile, read the unresolved-import errors, and look each symbol up in the tables below.
```bash
cargo build 2>&1 | grep -E "unresolved import|no .* in"
```
Add whichever crates the table points you at:
```toml
everruns-platform = "0.18" # persisted records, hosted service contracts
everruns-host = "0.18" # execution composition and host wiring
everruns-provider = "0.18" # provider SPI, typed IDs, sqlx impls
everruns-capability = "0.18" # capability identity/configuration contract
everruns-mcp = "0.18" # MCP adapter and the OAuth protocol client
everruns-llmsim = "0.18" # deterministic production-safe simulator
```
The earlier `everruns-session-services` preview package was consolidated into `everruns-host`; use `everruns_host::session_services` for its namespaced API.
### Composition
The single biggest change for embedders. `PlatformDefinition` no longer exists.
| 0.17 | 0.18 |
| ------------------------------------------------------ | --------------------------------------------------- |
| `everruns_core::PlatformDefinition` | `everruns_host::HostComposition` |
| `everruns_core::PlatformDefinitionBuilder` | `everruns_host::HostCompositionBuilder` |
| `everruns_server::oss_platform_definition()` | `everruns_server::oss_host_composition()` |
| `everruns_server::oss_platform_definition_for_grade()` | `everruns_server::oss_host_composition_for_grade()` |
| `everruns_worker::default_platform_definition()` | `everruns_worker::default_host_composition()` |
| `ServerAppBuilder::platform_definition(..)` | `ServerAppBuilder::host_composition(..)` |
| `WorkerAppBuilder::platform_definition(..)` | `WorkerAppBuilder::host_composition(..)` |
```diff
use everruns_core::PlatformDefinition;
use everruns_host::HostComposition;
let platform = PlatformDefinition::builder()
let composition = HostComposition::builder()
.capability_registry(capabilities)
.driver_registry(drivers)
.build();
ServerAppBuilder::new().platform_definition(platform)
ServerAppBuilder::new().host_composition(composition)
```
The type is otherwise identical, same fields, same builder methods. It moved to the layer that executes a turn, because selecting a deployment’s capabilities and drivers is composition rather than kernel configuration.
#### Input/Reason/Act execution kernel
Concrete phase execution moved out of `everruns-core`. Import phase algorithms and their I/O values from `everruns-engine`; keep neutral effect contracts in core.
| 0.17 | 0.18 |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `everruns_core::atoms::{InputAtom, InputAtomInput, InputAtomResult}` | `everruns_engine::{InputAtom, InputAtomInput, InputAtomResult}` |
| `everruns_core::atoms::{ReasonAtom, ReasonInput, ReasonResult}` | `everruns_engine::{ReasonAtom, ReasonInput, ReasonResult}` |
| `everruns_core::atoms::{ActAtom, ActInput, ActResult, ToolCallResult}` | `everruns_engine::{ActAtom, ActInput, ActResult, ToolCallResult}` |
| `everruns_core::atoms::AtomContext` | `everruns_core::ExecutionContext` (also re-exported by `everruns-engine`) |
| `everruns_core::atoms::{PreToolUseHook, PostToolExecHook, PreToolUseDecision}` | `everruns_core::tool_hooks::*` |
The generic `Atom` trait was removed; it had no production dynamic-dispatch use. Call the concrete executor’s inherent async `execute` method. There is no core compatibility module in 0.18. Serialized phase payloads retain the same fields, so durable records remain readable even though the Rust ownership path changed.
#### Turn context and command completion
Store-backed turn preparation now belongs to `everruns-host`. Core keeps the secret-free execution snapshot, pure context transformations, and narrow effects used by custom hosts.
| 0.17 | 0.18 |
| ---------------------------------------------------- | ---------------------------------------------------- |
| `everruns_core::assemble_turn_context` | `everruns_host::assemble_turn_context` |
| `everruns_core::inspect_turn_context` | `everruns_host::inspect_turn_context` |
| `everruns_core::load_execution_snapshot` | `everruns_host::load_execution_snapshot` |
| `everruns_core::load_execution_snapshot_for_session` | `everruns_host::load_execution_snapshot_for_session` |
| `everruns_core::StoreCommandHost` | `everruns_host::StoreCommandHost` |
`everruns_engine::ReasonAtom::new` no longer accepts harness, agent, session, and provider stores or a driver registry. Construct an `everruns_host::StoreTurnContextResolver` from those host services, then pass that resolver plus the narrow message, capability, and event effects to the atom. Hosts that already loaded a `ResolvedExecutionSnapshot` should call `everruns_host::assemble_turn_context_from_snapshot` and execute the atom with the resulting `AssembledTurnContext`; this avoids a second store load.
For a fully custom host, implement the neutral `everruns_core::TurnContextResolver`, or provide already-resolved `ResolvedTurnContextInput` to `everruns_core::assemble_resolved_turn_context`. That input contains a secret-free model/provider identity and an opaque ready driver; provider keys and endpoints are never serializable kernel values.
`CommandTurnContext` now exposes `session_id` directly instead of an `ExecutionSession`. Commands retain the same filtered messages, effective prompt, locale, model, streaming, and error-decision behavior without receiving a session record.
### Persisted records
These are database and API records. Execution consumes a portable projection of each; the stored row is control-plane state.
| 0.17 (`everruns_core::`) | 0.18 |
| ----------------------------------------------------------------------------------------- | -------------------------------- |
| `Agent`, `AgentVersion`, `AgentStatus`, `AgentVersionChangeKind` | `everruns_platform::` |
| `Harness`, `HarnessStatus`, `BuiltInHarnessDefinition`, `BuiltInHarnessRole` | `everruns_platform::` |
| `Session`, `SessionStatus`, `SessionSource`, `SessionActivity`, `SessionParticipant` | `everruns_platform::` |
| `Workspace`, `WorkspaceStatus` | `everruns_platform::workspace::` |
| `Eval`, `EvalCase`, `EvalRun`, `EvalCaseResult`, `EvalRunDataset`, `EvalTarget`, `Scorer` | `everruns_platform::` |
| `Observer`, `ObserverMatch`, `LlmJudgeConfig`, `TraceScore` | `everruns_platform::` |
| `FeatureFlags`, `FeatureFlagMap`, `FeatureFlagDefinition` | `everruns_platform::` |
| `Budget`, `LedgerEntry` | `everruns_platform::` |
If you were reading a stored record to run a turn, you probably want the portable projection instead, `AgentDefinition`, `HarnessDefinition` and `ExecutionSession` all stay in `everruns_core`, produced at the platform loading boundary by `Agent::execution_definition`, `Harness::execution_definition` and `Session::execution_session`.
### Hosted service contracts
| 0.17 (`everruns_core::`) | 0.18 |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `session_sqldb::*`, `SessionSqlDbStore`, `DatabaseInfo`, `SqlQueryResult`, `SqlExecuteResult`, `TableSchema`, `ColumnSchema`, `SessionSqlDbError` | `everruns_platform::session_sqldb::` |
| `traits::SessionMutator` | `everruns_host::SessionMutator` (also re-exported by platform) |
| `session_sandbox::*`, config, state, instance, exec/file payloads, `SessionSandboxProvider`, `SessionSandboxProviderPlugin` | `everruns_platform::session_sandbox::` |
| `Connector`, `ConnectorRegistry`, `ConnectorPlugin` | `everruns_platform::connector::` |
| `EmailSender`, `EmailMessage`, `SystemEmailConfig`, `ResendEmailSender` | `everruns_platform::email::` |
| `OAuthClient`, `TokenSet`, `PkcePair` | `everruns_mcp::oauth::protocol::` |
Neutral per-turn contracts remain in `everruns-core`, but the catch-all `everruns_core::traits` module is gone. Import from the owning concern instead, for example `everruns_core::tool_context::ToolContext`, `everruns_core::session_files::SessionFileSystem`, or `everruns_core::provider_resolution::ProviderStore`. The deployment-owned `SessionFileSystemFactory` and its context now come from `everruns-host`.
Two of these also changed how a capability *reaches* the service. `sqldb_store` and `session_mutator` are no longer fields on `ToolContext`; they resolve from the type-keyed extension bag:
```diff
let Some(store) = &context.sqldb_store else { ... };
let Some(store) = context.extensions.get::() else { ... };
let store = &store.0;
```
If you implement a custom host, install them the way `everruns-host` does:
```rust
extensions.insert(Arc::new(SessionSqlDbStoreExt(store)));
extensions.insert(Arc::new(SessionMutatorExt(mutator)));
```
### Capabilities and implementations
| what | 0.18 home |
| ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Knowledge Bases and Indexes, Memories, delegation, subagents, background and scheduled work, user hooks, citations, model scouting, platform management | `everruns_platform::capabilities::` |
| Session info and session storage | `everruns_host::session_services::capabilities::` (also re-exported by platform) |
| Session SQL database and session sandbox | `everruns_platform::capabilities::` |
| `spawn_background` and its runtime, event sink, admission permits, reattach | `everruns_platform::background_run::` |
| Portable built-ins, human intent, infinity context, skills, UI prompts, compaction, tool search | `everruns_builtins::` |
| `everruns_openui::{PromptOptions, default_library, generate_prompt}` | `everruns_builtins::openui::{PromptOptions, default_library, generate_prompt}` |
| `everruns_a2ui::{PromptOptions, default_catalog, generate_prompt}` | `everruns_builtins::a2ui::{PromptOptions, default_catalog, generate_prompt}` |
| OpenRouter workspace, model scout, and provider-executed server tools | `everruns_integrations_openrouter::` |
| Filesystem, shell, web fetch, Lua | `everruns_integrations_*` |
| MCP adapter | `everruns_mcp::` |
| In-process HTTP egress transport | `everruns_host::DirectEgressService` |
| Telemetry init, exporter event listeners, `CompositeEventListener` | `everruns_host::observability::` (feature `observability`) |
| `llmsim` driver, configs, scripted turns, registry helpers, host-builder extension | `everruns_llmsim::` |
| in-memory agentic loop, writable test doubles, fixture capabilities | `everruns_test_support::` |
| `everruns_core::in_memory::{InMemoryAgentStore, InMemoryHarnessStore, InMemorySessionStore, InMemoryProviderStore}` | `everruns_host::{InMemoryAgentStore, InMemoryHarnessStore, InMemorySessionStore, InMemoryProviderStore}` |
| `everruns_core::in_memory::{InMemoryMessageRetriever, InMemoryEventEmitter}` | `everruns_test_support::{InMemoryMessageRetriever, InMemoryEventEmitter}` for isolated deterministic tests |
Product presets compose these explicitly. Core registries are now empty by default: use `everruns_host::runtime_capability_registry()` for the Framework preset or `everruns_platform::capabilities::hosted_capability_registry()` for the hosted product catalog.
Hosted conversation history has no writable message-store replacement. Append canonical events through `everruns_host::EventLog` / `HostEventEmitter` and read messages through `EventHistory`. This avoids message/event dual writes and keeps resume and replay behavior identical across in-memory and durable hosts.
`everruns-test-support` continues to re-export its 0.17 simulator paths during the 0.18 migration, so existing test suites can upgrade without an immediate import rewrite. Treat that as a migration bridge: production code, new tests, and low-level hosts should depend on `everruns-llmsim` directly. The application-facing `everruns::Model::simulated` and `Model::simulated_with_config` APIs are unchanged.
### Features
| 0.17 | 0.18 |
| -------------------------------------- | ------------------------------------------------------------------------- |
| `everruns-core/sqlx` | removed, use `everruns-provider` with `features = ["sqlx"]` |
| `everruns-core/embedded-platform-docs` | removed, it gated nothing; use `everruns-platform/embedded-platform-docs` |
| `everruns-platform/sqlx` | removed, it forwarded to core’s and nothing enabled it |
| `everruns-core/llm-tests` | removed, use the `everruns-llm-tests` package for live provider tests |
`everruns-core` now has an empty default feature set. OpenAPI derives remain available only with `features = ["openapi"]`; structural outlines remain available only with `features = ["tree-sitter-outlines"]`. Neither subtree is present in a default core build.
Concrete provider protocol and utility-model implementations also moved to their effectful owners:
| 0.17 (`everruns_core::`) | 0.18 |
| ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `OpenAIProtocolChatDriver`, `openai_protocol` | `everruns_contracts::` |
| `OpenResponsesProtocolChatDriver`, `openresponses_protocol` | `everruns_contracts::` |
| `driver_helpers`, `stream_reconnect` | `everruns_contracts::` |
| `OpenAiUtilityLlmService` (now `ProviderUtilityLlmService`), `SystemUtilityLlmConfig`, `UTILITY_OPENAI_API_KEY_ENV` | `everruns_host::` with `features = ["utility-llm"]` |
Core no longer initializes Rustls. Provider HTTP clients install the workspace crypto provider when they are first constructed, while server, worker, and CLI startup owners install it eagerly. Custom binaries that combine TLS stacks can depend on `everruns-provider` with `features = ["tls-aws-lc-rs"]` and call `everruns_contracts::install_default_crypto_provider()` once during startup; the call is idempotent and safe under concurrent initialization.
### Provider and typed-ID imports
Provider-owned modules are no longer compatibility-exported by `everruns-core`. Low-level consumers must add `everruns-provider` directly. This keeps credentials and concrete driver assembly out of the neutral kernel and makes the dependency owner visible in `Cargo.toml`.
There are two common compiler-error shapes:
1. **The module moved to another crate.** Add that crate and change the prefix.
2. **The module stayed public, but its root convenience re-export was removed.** Keep the dependency and qualify the symbol through its module.
The second case produces the misleading-looking `no X in the root` error. It does not necessarily mean the type moved. These replacements are deliberately literal so they can be applied with ordinary search-and-replace:
| before | after |
| ---------------------------------- | ---------------------------------------------------- |
| `everruns_core::ProviderStore` | `everruns_core::provider_resolution::ProviderStore` |
| `everruns_core::SessionStore` | `everruns_core::execution_loading::SessionStore` |
| `everruns_core::MessageRetriever` | `everruns_core::message_retriever::MessageRetriever` |
| `everruns_core::SessionFileSystem` | `everruns_core::session_files::SessionFileSystem` |
| 0.17 core path | 0.18 direct path |
| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `everruns_core::driver_registry::*` | `everruns_contracts::driver_registry::*` |
| `everruns_core::model::*` | `everruns_contracts::model::*` |
| `everruns_core::model_profiles::*` | `everruns_contracts::model_profiles::*` |
| `everruns_core::model_spec::ModelSpec` | `everruns_contracts::model_spec::ModelSpec` |
| `everruns_core::provider::*` | `everruns_contracts::provider::*` |
| `everruns_core::runtime_provider::*` | `everruns_contracts::runtime_provider::*` |
| `everruns_core::typed_id::*` | `everruns_contracts::typed_id::*` |
| `everruns_core::error::*` | `everruns_contracts::error::*` |
| `everruns_core::tool_types::*` | `everruns_contracts::tool_types::*` |
| `everruns_core::capability_types::{CapabilityId, CapabilityRef, CapabilityError}` | `everruns_contracts::capability::{CapabilityId, CapabilityRef, CapabilityError}` |
| `everruns_core::AgentCapabilityConfig` | `everruns_contracts::capability::CapabilityRef` |
| core plugin capability ID/validation helpers | the same symbol in `everruns_capability` |
| `everruns_core::ExecutionPhase` or `message::ExecutionPhase` | `everruns_contracts::execution_phase::ExecutionPhase` |
| `everruns_core::ToolResultImage` or `tools::ToolResultImage` | `everruns_contracts::tool_types::ToolResultImage` |
| other root-level provider symbols | the same root symbol in `everruns_provider` |
The credential-bearing `everruns_core::ResolvedModel` is removed. Store and transport boundaries now resolve two separate values:
* `ModelSpec`, safe to serialize and pass through the kernel; and
* a host-owned runtime `Provider` (or internal `ProviderConfig`) containing endpoint and authentication state.
`ProviderStore::get_model_spec` and `get_default_model_spec` return only the first value. Hosts obtain provider configuration separately and join it only while constructing a non-serializable driver/provider execution value.
`ProviderStore::get_provider_config` no longer has a default implementation. Every custom host must state where credentials live: return its resolved `ProviderConfig`, or explicitly return `None` when the provider was registered directly in the host registry or is selected but not configured. A missing credential no longer prevents turn-context/command assembly; the constructed driver rejects the first model/list/compact operation locally, before network I/O. This keeps recovery commands reachable without turning an empty token into an outbound authorization header.
### Simulator and compaction naming
`LlmSimRuntimeExt::llm_sim` now only registers/replaces the simulator provider. It never changes the selected model. Existing compact test setups that relied on implicit selection should use the explicit name:
```diff
builder.llm_sim(config)
builder.llm_sim_as_default(config)
```
When a builder already calls `default_model(...)`, keep `.llm_sim(config)`; the selected model is preserved regardless of method order.
`everruns_builtins::CompactionConfig` is the sole application-facing policy builder. The expanded implementation value previously available as `everruns_builtins::compaction::CompactionConfig` is now `everruns_builtins::compaction::RuntimeCompactionConfig` (also re-exported at the crate root). This makes an unqualified `CompactionConfig` unambiguous.
The public core test/backend conveniences are gone as well:
| removed core value | replacement |
| ----------------------------------- | ------------------------------------------------------------------- |
| `EchoTool`, `FailingTool` | define the small test `Tool` locally, or use test-support executors |
| `InMemoryCompactionCheckpointStore` | `everruns_host::InMemoryCompactionCheckpointStore` |
### What deliberately did not move
Worth knowing so you do not go looking:
* **`SessionTask`, `TaskMessage`** and the task registry stay in `everruns_core`. They are turn-execution vocabulary, `wake_queue` decides mid-turn wakes from a task’s wake policy, and they appear in the canonical `task.created` / `task.updated` / `task.message.*` event payloads.
* **`SessionSchedule`, `SessionScheduleStore`** stay. A portable built-in (`usage_limit_auto_continue`) schedules an auto-resume after a provider usage limit, and it sits below platform in the dependency graph.
* Schedule quota and minimum-interval environment variables are no longer read by core. Local/server adapters resolve deployment policy and call the parameterized core validation helpers.
* **`SessionResourceRegistry`** stays. `resource_ownership` and the portable skills capabilities consume it.
* **`SessionFileSystem`, `SessionStorageStore`** and the other neutral store contracts stay. Core owns the contract; hosts own the backend.
The rule these follow: whether something belongs in the kernel is decided by whether a portable execution path consumes it during a turn, not by whether it is persisted. All four above are persisted, and all four are essential for execution.
### Getting unstuck
If a symbol is not in these tables, import it from the crate that defines it; `everruns-core` no longer acts as a compatibility facade for provider-owned APIs. Framework applications can continue to prefer the higher-level `everruns` facade. The crate-level docs on `everruns-core` record where each remaining family lives and why.
---
# Build a Voice Agent
> Let people talk to a Framework agent and hear its answers, in your own Rust host or as a serve app, with the same agent, tools and transcript as text.
Source: > {
let policy = WorkspacePolicy::builder()
.allow_read("/")
.allow_write("generated")
.deny_write("generated/locked")
.allow_hidden(".github")
.build()?;
Ok(Agent::builder()
.instructions("Work only inside the configured workspace.")
.provider(OpenAI::from_env()?)
.model("gpt-6.1-sol")
.workspace(root)
.workspace_policy(policy)
.build()?)
}
```
### Defaults
`WorkspacePolicy::default()` and `WorkspacePolicy::read_only()` use the same secure baseline:
| Operation | Default |
| ---------------------------------------- | ------- |
| Read ordinary workspace files | Allowed |
| Write, create, or delete | Denied |
| Read or write hidden paths | Denied |
| Read or write common credential paths | Denied |
| Read framework-managed `.agents` content | Allowed |
| Recursively delete a directory | Denied |
`WorkspacePolicy::read_write()` is an explicit opt-in to ordinary writes. It does not expose additional hidden or sensitive paths and does not enable recursive deletion. It also keeps common dependency and build directories such as `node_modules` and `target` non-writable at every depth. For narrower access, start with `WorkspacePolicy::builder()`, which has no readable or writable scopes until you add them.
A custom builder does not inherit the default `.agents` exception. If the agent needs workspace-provided instructions or skills, add both a readable scope and a narrow `allow_hidden(".agents")` opt-in.
Protected path names are defense in depth, not content-based secret scanning. Keep credentials outside the mounted workspace, add explicit deny scopes for application-specific secret locations, and never place credentials in `.agents` content.
### Matching and precedence
Scopes are literal path prefixes, not globs, and compare ASCII letters without case sensitivity so a deny cannot be bypassed on a case-insensitive backend. `generated` therefore includes `generated/report.md` but not `other/generated/report.md`.
* A deny scope always wins over an allow scope.
* `deny_write_component` rejects an exact directory or file name at every depth; `deny_write` rejects one rooted path subtree.
* Hidden paths need `allow_hidden` for the narrow path that should be visible.
* Common credential paths need the stronger `allow_sensitive` opt-in, which also permits hidden components inside that specific scope.
* `compose` is restrictive: every composed policy must allow the operation. A library can add constraints without accidentally broadening the application’s policy.
Trusted starter files are installed before model access is enforced. This lets an application seed a read-only file even under a non-writable policy. Later reads, writes, and deletes of that file still go through the policy, so seeding a hidden file does not automatically expose it.
### Paths and containment
Policy paths live in one portable workspace namespace. These spellings identify the same file:
```text
src/lib.rs
/src/lib.rs
/workspace/src/lib.rs
```
Traversal (`..`), NUL bytes, and backslash-separated paths fail closed. Host absolute paths are backend-specific and are not portable policy scopes; use `/workspace/...` in application configuration and model instructions.
The policy layer controls visibility and mutation. The selected filesystem backend remains responsible for mapping workspace paths to storage. The local host backend canonicalizes its root, keeps resolved paths contained, and rejects symlinks in existing path components before every operation. An absolute path outside the configured root cannot expose that host file.
The policy governs capabilities that use Everruns’ session filesystem. A custom tool that calls `std::fs`, launches a shell, or uses another storage API does not pass through this boundary. Apply equivalent restrictions to those tools or run them in a sandbox.
### Symlinks and races
The built-in local backend rejects a symlink introduced after the workspace was configured because it rechecks components on every operation. This blocks normal traversal and symlink-swap attempts between operations.
It is not an OS sandbox. A malicious process running as the same operating system user can race a final path check and filesystem syscall. If local processes are mutually untrusted, use an isolated sandbox/filesystem backend or operating-system isolation. Do not use `WorkspacePolicy` as a substitute for that process boundary.
### Backend extension
The in-process host applies the policy after resolving the platform’s filesystem factory. In-memory, local-disk, database, and custom backends all receive the same policy checks. Backend authors still own containment, symlink-safe I/O, quotas, durability, and atomic update guarantees for their storage system.
Directory listings and grep are enforced at the same boundary as direct reads. Denied files are not opened by policy grep, and denied names, match counts, and byte totals are not returned. Recursive deletes inspect descendants through the backend before deletion, so opting into recursion does not override a deny or protected descendant. Backends with mutable external state must still treat that preflight-to-delete window as a race boundary.
`WorkspaceRootSet` additional roots are named mounts inside one selected head; they are not independent heads and carry no fork/reopen lifecycle. Likewise, `WorkspacePolicy` is path authorization, not a compute sandbox. The sections above describe the identity and lifecycle model.
---
# Everruns Cloud quickstart
> Sign up for Everruns Cloud, use the built-in model provider with starter credit, create a token, and connect from the SDK, CLI, or an AI tool.
Source:
AUTH_JWT_SECRET=
WORKER_GRPC_AUTH_TOKEN=
AUTH_ADMIN_EMAIL=admin@example.com
AUTH_ADMIN_PASSWORD=
# Optional: two extra workers and VictoriaMetrics (see Profiles below)
COMPOSE_PROFILES=scale,metrics
# Optional: Add API keys here to skip UI configuration
DEFAULT_OPENAI_API_KEY=sk-...
DEFAULT_ANTHROPIC_API_KEY=sk-ant-...
DEFAULT_GEMINI_API_KEY=AIza...
SEED_DEFAULT_PROVIDER_KEYS_FROM_ENV=true
```
`SEED_DEFAULT_PROVIDER_KEYS_FROM_ENV=true` copies the keys into the default organization’s providers at startup; without it they are ignored. The server refuses it when people can sign themselves up (`AUTH_MODE=full` with signup or Google/GitHub sign-in), because anyone who joins could spend the keys.
### 4. Start Services
```bash
docker compose pull # Fetch latest images
docker compose up -d
```
The published compose file defaults to app entry point on `9300`. If that port is busy, override before startup:
```bash
EXAMPLE_PROXY_PORT=10300 docker compose up -d
```
This starts:
* PostgreSQL database
* Valkey (rate limiting) and NATS (event delivery and task notifications)
* Control plane (`server`): HTTP API and worker gRPC
* 1 worker, or 3 with the `scale` profile
* Next.js UI
* Caddy reverse proxy
* VictoriaMetrics, scraping server metrics at (`metrics` profile)
Sign in to the UI with `AUTH_ADMIN_EMAIL` and `AUTH_ADMIN_PASSWORD`.
### 5. Access the Platform
| Service | URL |
| ------------------ | -------------------------------------------------------------- |
| **Web UI** | |
| **API** | |
| **OAuth Metadata** | |
| **Health Check** | |
## Configuration
### Run Multiple Copies
If you want multiple Everruns compose stacks on the same machine, set both a Compose project name and host-port overrides:
```bash
COMPOSE_PROJECT_NAME=everruns-demo-2 \
EXAMPLE_PROXY_PORT=10300 \
docker compose up -d
```
### Configure LLM Provider
If you didn’t set LLM API keys (`DEFAULT_OPENAI_API_KEY`, `DEFAULT_ANTHROPIC_API_KEY`, or `DEFAULT_GEMINI_API_KEY`) in your `.env` file, configure via UI:
1. Open
2. Navigate to **Settings** > **Providers**
3. Add your OpenAI or Anthropic API key
4. Save and verify connection
### Create Your First Agent
1. Go to **Agents** in the UI
2. Click **Create Agent**
3. Set a name and system prompt
4. Select your configured LLM provider
5. Save the agent
### Start a Session
The API requires a token. Create a personal access token under **Settings** > **Personal Access Tokens** in the UI (it starts with `evr_pat_` and is shown once), or from the command line as described in [Authentication](https://everruns.com/docs/sre/runbooks/authentication/#create-personal-access-token).
```bash
export EVERRUNS_TOKEN=evr_pat_...
# Create a session (agent_id in request body)
curl -X POST http://localhost:9300/api/v1/sessions \
-H "Authorization: Bearer $EVERRUNS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"agent_id": "{agent_id}"}'
# Send a message
curl -X POST http://localhost:9300/api/v1/sessions/{session_id}/messages \
-H "Authorization: Bearer $EVERRUNS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"message": {"role": "user", "content": [{"type": "text", "text": "Hello!"}]}}'
```
## Profiles
Without profiles the stack is the lean set: PostgreSQL, Valkey, NATS, the server, one worker, the UI and Caddy. Two optional [Compose profiles](https://docs.docker.com/compose/how-tos/profiles/) add the rest:
| Profile | Adds |
| --------- | ----------------------------------------------- |
| `scale` | `worker-2` and `worker-3` |
| `metrics` | VictoriaMetrics at |
Set them in `.env` as `COMPOSE_PROFILES=scale,metrics` (as above), or per command: `docker compose --profile metrics up -d`. Profiles need Docker Compose 2.20 or newer.
## Scaling Workers
Add more workers by scaling the worker services (`worker-2` and `worker-3` need the `scale` profile):
```bash
# Scale to 5 workers
docker compose up -d --scale worker-1=1 --scale worker-2=1 --scale worker-3=3
```
Or modify `docker-compose.yaml` to add more worker services.
## Monitoring
### View Logs
```bash
# All services
docker compose logs -f
# Specific service
docker compose logs -f server
docker compose logs -f worker-1
```
### Distributed Tracing
Set `OTEL_EXPORTER_OTLP_ENDPOINT` to export traces to any OTLP-compatible backend (Grafana Tempo, Datadog, etc.).
## Stopping Services
```bash
# Stop all services
docker compose down
# Stop and remove volumes (deletes data)
docker compose down -v
```
## Troubleshooting
### Check Service Health
```bash
docker compose ps
```
`server` should report `healthy`. Its healthcheck runs `everruns-server --health-check`, which calls `/health` inside the container. Images released before that flag existed always show `unhealthy` even when the API works; check `curl http://localhost:9300/health` instead.
### Database Connection Issues
If services fail to connect to PostgreSQL:
```bash
# Check postgres health
docker compose ps postgres
# View postgres logs
docker compose logs postgres
```
### Migration Failures
Migrations are auto-applied when the server starts. If migrations fail:
```bash
# Check server logs for migration errors
docker compose logs server
# Restart the server to retry migrations
docker compose restart server
```
To inspect migration status, use the [admin container](https://everruns.com/docs/sre/admin-container/).
### Worker Not Processing
Verify workers can reach the control plane:
```bash
# Check worker logs
docker compose logs worker-1
```
A worker that logs authentication errors has a different `WORKER_GRPC_AUTH_TOKEN` from the server. Both read it from the same `.env`, so recreate them after changing it: `docker compose up -d --force-recreate`.
## Next Steps
* [API Reference](https://everruns.com/docs/api/) - Full API documentation
* [Capabilities](https://everruns.com/docs/features/capabilities/) - Extend agent functionality
* [Environment Variables](https://everruns.com/docs/sre/environment-variables/) - Advanced configuration
---
# Start here
> Choose how you run Everruns, the Framework, a self-hosted Platform, or Everruns Cloud, and go to the right first page.
Source: -generated`. Upgrades read them back instead of making new ones, and uninstalling the chart leaves that Secret in place.
**Back up that Secret with the database.** The encryption key protects the provider keys and secrets stored in the database; without it they cannot be read. To manage these values yourself, create a Secret with `SECRETS_ENCRYPTION_KEY`, `AUTH_JWT_SECRET`, `WORKER_GRPC_AUTH_TOKEN` and `AUTH_ADMIN_PASSWORD` and set `secrets.existingSecret`.
Provider keys for the whole server go in `providerKeys` or in a Secret named by `providerKeys.existingSecret`. With `seedDefaultProviderKeys: true` they become the default organization’s keys (not with `auth.mode: full`).
## Upgrade
```bash
helm upgrade everruns oci://ghcr.io/everruns/charts/everruns --version 0.49.0 \
--namespace everruns --reuse-values
```
The new server applies the database migrations when it starts. Migrations only go forward, so back up the database first.
## No operator
Everruns ships a chart, not an operator. PostgreSQL is the only stateful part, and managed databases or a PostgreSQL operator handle its lifecycle. The server migrates itself, and KEDA scales workers. Agents and sessions live in the database behind the API, so they are managed with the [CLI](https://everruns.com/docs/features/cli/), the UI or MCP, not as Kubernetes objects.
All chart values, with comments: [`charts/everruns/values.yaml`](https://github.com/everruns/everruns/blob/main/charts/everruns/values.yaml).
---
# Run Everruns on your machine
> Start the self-hosted Platform on your computer with one command, everruns docker up, which asks a few questions, starts it in Docker and signs the CLI in.
Source: .txt`: one topic at a time, mirroring the sidebar: [start-here](https://everruns.com/docs/_llms-txt/start-here.txt), [framework](https://everruns.com/docs/_llms-txt/framework.txt), [platform](https://everruns.com/docs/_llms-txt/platform.txt), [built-ins](https://everruns.com/docs/_llms-txt/built-ins.txt), [guides](https://everruns.com/docs/_llms-txt/guides.txt), [integrations](https://everruns.com/docs/_llms-txt/integrations.txt), [explanation](https://everruns.com/docs/_llms-txt/explanation.txt), [reference](https://everruns.com/docs/_llms-txt/reference.txt), [operations](https://everruns.com/docs/_llms-txt/operations.txt). Prefer a set over the complete text.
* [`/api/openapi.json`](https://everruns.com/docs/api/openapi.json): the REST API as OpenAPI 3.0. The text sets carry prose only, so take endpoint shapes from here.
Every page in those files begins with its title, its description, and a `Source:` line holding the canonical URL. Cite that URL, not the text file.
---
# How-to guides
> Task-oriented recipes for common Everruns workflows, equipping agents with tools, streaming events, deploying to channels, and operating production agents.
Source: ` block (\~100 tokens per skill):
```xml
csv-analyzer
Analyze CSV files and generate summary reports.
```
When the user’s task matches, the agent calls `activate_skill`:
```json
{ "name": "activate_skill", "arguments": { "name": "csv-analyzer" } }
```
The tool returns the full SKILL.md instructions wrapped in `` tags. The agent now has the detailed instructions in context and can run the bundled scripts.
## Test the skill
1. Start a session with an agent that has the `skills` capability enabled.
2. Write the skill files to `/.agents/skills//` in the session.
3. Send a message that matches the skill’s “When to Use” criteria.
4. Watch the event stream for an `activate_skill` tool call.
## Publish to the Skills Registry
The Skills Registry stores skills at the organization level. Registry skills persist across sessions and can be assigned to any agent as a capability with ID `skill:{uuid}`. When a session starts, the skill is mounted into `/.agents/skills/{name}/`, so the `skills` capability discovers it the same way as a workspace skill.
### From SKILL.md
If your skill is a single Markdown file, post it directly:
```bash
curl -X POST http://localhost:9300/api/v1/skills \
-H "Content-Type: application/json" \
-d '{
"skill_md": "---\nname: hello-world\ndescription: A simple greeting skill.\n---\n\n# Hello World\n\nGreet the user warmly."
}'
```
The response includes the skill ID:
```json
{ "id": "skill_550e8400-e29b-41d4-a716-446655440000", "name": "hello-world", ... }
```
### From a ZIP archive
For skills with bundled scripts, references, or assets:
```bash
curl -X POST http://localhost:9300/api/v1/skills/upload \
-F "file=@csv-analyzer.zip"
```
Archive layout:
```plaintext
csv-analyzer/
├── SKILL.md
├── scripts/analyze.py
└── references/REFERENCE.md
```
The top-level directory name is informational; the skill `name` comes from the SKILL.md front matter and must be unique per organization.
### Validate first
Validate without creating:
```bash
curl -X POST http://localhost:9300/api/v1/skills/validate \
-H "Content-Type: application/json" \
-d '{"skill_md": "---\nname: my-skill\ndescription: Does things.\n---\n\n# Instructions"}'
```
Response:
```json
{ "valid": true, "name": "my-skill", "description": "Does things.", "warnings": [] }
```
### Assign to an agent
Registry skills appear in the capability system as virtual capabilities with ID `skill:{uuid}`:
```bash
curl -X POST http://localhost:9300/api/v1/agents \
-H "Content-Type: application/json" \
-d '{
"name": "Analyst Agent",
"capabilities": [
{ "ref": "skill:550e8400-e29b-41d4-a716-446655440000" },
{ "ref": "session_file_system" }
]
}'
```
`session_file_system` is pulled in automatically as a dependency.
### Update or delete
```bash
# Update
curl -X PATCH http://localhost:9300/api/v1/skills/$SKILL_ID \
-H "Content-Type: application/json" \
-d '{"skill_md": "..."}'
# Delete
curl -X DELETE http://localhost:9300/api/v1/skills/$SKILL_ID
```
Deleting a skill hides it from capability listings. Agents that reference it via `ref: "skill:..."` will still resolve until you update them.
## See also
* [Agent Skills](https://everruns.com/docs/features/skills/): the concept, the registry API, and its security rules.
* [Agent Skills capability reference](https://everruns.com/docs/capabilities/agent-skills/): `list_skills` and `activate_skill`.
---
# Publish an Agent to Slack
> Add a Slack channel to an Agent, publish it, connect a Slack workspace, and verify the first message.
Source: __*` (surfaced through `tool_search`); A2A agents are reachable via `spawn_agent`.
4. `list_attached_resources()`, see what’s attached this session.
## Tools
| Tool | Description |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `discover_resources({ text, filter?, registry_id? })` | Search a configured registry (`POST /search`). Returns ranked `{ urn, displayName, type, score, source, description, attachable }`. `registry_id` is optional when one registry is configured. |
| `attach_resource({ urn })` | Resolve a discovered entry, verify `trustManifest` + `require_trust`, SSRF-validate the URL, and attach it. Idempotent per URN. |
| `list_attached_resources()` | List attachments for the session (visibility / audit). |
## Attachment Lifecycle
* Attachments are **session-scoped** and torn down when the session ends.
* MCP entries become a session MCP server, the same session-scoped `mcpServers` record a server added for [this conversation only](https://everruns.com/docs/capabilities/user-mcp-servers/#this-conversation-only) uses. Their tools are then subject to `tool_search` deferral, in both the hosted and the in-process worker.
* A2A entries merge into the session’s A2A delegation config and are driven through the existing `spawn_agent` / `wait_task` / `message_task` tools.
* Re-attaching the same URN is a no-op (reports `already_attached`).
## Security
* **Registry allowlist**: only configured registries are queryable; the model picks a `registry_id`, never a URL.
* **Trust gate**: an entry’s `trustManifest` identity domain must match its URN publisher, and any `require_trust` attestations (e.g. `["soc2"]`) must be present, before it can be attached.
* **SSRF protection**: every resolved artifact and endpoint URL is validated (DNS-pinned; loopback, private, link-local, and cloud-metadata addresses are blocked). `allow_local_urls` relaxes this for local testing only.
* **Attachment cap**: `max_attachments` bounds how many capabilities a single session can attach, limiting prompt-injection-driven attach storms.
* **Untrusted data**: all registry-returned text is treated as untrusted external input.
See the co-located [`SPEC.md`](https://github.com/everruns/everruns/blob/main/crates/ard/SPEC.md) for architecture and the full security review.
---
# Brave Search
> Web search through Brave: ranked results, freshness filters, pagination, source attribution, and safe search. Requires a Brave API key.
Source: `. Use `--after` and `--before` to choose a failure-time window, and `--limit` and `--offset` to page through matching sessions.
## Available Integrations
For live execution inside the platform, use [Monitoring](https://everruns.com/docs/observability/monitoring/). It provides organization-scoped and platform-wide views of execution phases, worker ownership, and actor leases.
* [OpenTelemetry](https://everruns.com/docs/observability/opentelemetry/), export traces over OTLP to any tracing backend. Spans follow the Gen-AI semantic conventions and the OpenInference conventions at once, so Grafana Tempo, Jaeger, Datadog, Langfuse, and Arize Phoenix all read them.
* [Braintrust](https://everruns.com/docs/observability/braintrust/), LLM observability, evaluation, and trace visualization. Turn traces are grouped by session, with token usage, time-to-first-token, and tool execution times.
## Framework Applications
Framework apps export the same traces from the `everruns` crate, behind the `otel` and `braintrust` Cargo features. See [Framework observability](https://everruns.com/docs/framework/observability/) for registering exporters and your own listeners on the Engine, and for flushing them on shutdown.
## Related
* [Events](https://everruns.com/docs/features/events/), the streaming event protocol that backs every observability export.
* [Environment Variables](https://everruns.com/docs/sre/environment-variables/), configure exporters, sampling, and OTLP endpoints.
* [Runnable Framework examples](https://everruns.com/docs/framework/examples/), complete programs built on the `everruns` crate.
---
# Braintrust
> Send Everruns traces to Braintrust for evaluation and trace visualization.
Source: /ai/v1
```
Set a base URL only to route through a proxy in front of Cloudflare; it replaces the derived one.
## Models
Model ids are namespaced and passed through unchanged:
* Third-party: `openai/gpt-6-luna`, `anthropic/claude-opus-5` — see the [upstream providers AI Gateway supports](https://developers.cloudflare.com/ai-gateway/usage/providers/).
* Workers AI: `@cf/meta/llama-3.3-70b-instruct-fp8-fast` — see the [Workers AI model catalog](https://developers.cloudflare.com/workers-ai/models/).
Which third-party models a gateway can reach depends on the upstreams Cloudflare has enabled for your account, so verify an id with a real request rather than assuming the catalog.
Third-party models are billed to your Cloudflare account and return `402` (“Insufficient balance”) until it is funded or you configure BYOK. Workers AI models draw on the account’s own allocation instead.
Model sync covers the Workers AI half of the catalog: Everruns reads Cloudflare’s model search endpoint and keeps its text-generation models, which arrive with the context window and tool-calling support Cloudflare advertises. Third-party models are never listed — which ones an account can reach depends on what it can bill — so add those by id. Everruns matches a namespaced id against its model profile registry, so a model it recognizes still gets its capability and cost metadata.
## Why Chat Completions
Cloudflare’s REST API offers four formats. Everruns uses `/ai/v1/chat/completions` because it is the only one that serves the whole catalog and streams:
| Endpoint | Why not |
| ------------------ | ----------------------------------------------------------------------------------- |
| `/ai/v1/responses` | Rejects Workers AI models — they are not translated into the Responses shape |
| `/ai/run` | Cannot stream: with `stream: true` it returns an empty JSON body rather than events |
| `/ai/v1/messages` | Excludes Workers AI models |
The older `gateway.ai.cloudflare.com/.../compat/chat/completions` endpoint is deprecated by Cloudflare for single-model calls and kept only for dynamic routes (`dynamic/{route}`), which this provider does not target.
## Links
* [Cloudflare AI Gateway](https://developers.cloudflare.com/ai-gateway/)
* [AI Gateway REST API](https://developers.cloudflare.com/ai-gateway/usage/rest-api/)
* [Workers AI models](https://developers.cloudflare.com/workers-ai/models/)
* [AI Gateway providers](https://developers.cloudflare.com/ai-gateway/usage/providers/)
* [`everruns-drivers` on crates.io](https://crates.io/crates/everruns-drivers)
* [Migrate between providers](https://everruns.com/docs/how-to/migrate-providers/)
---
# Fireworks AI
> Run Everruns agents on open models hosted by Fireworks AI (Llama, Qwen, DeepSeek, Kimi, GLM, gpt-oss), with automatic model discovery.
Source: .services.ai.azure.com`).
4. Provide credentials for one of the two methods, entered as discrete fields:
* **API key**: your Azure AI Foundry resource key.
* **Entra ID (OAuth)**: a client-credentials service principal: `tenant_id`, `client_id`, and `client_secret` (with optional `scope` and `authority`, which default to the Azure Cognitive Services scope and public Microsoft Entra authority).
5. Save.
Authentication is fail-closed: a stored credential is always required, and OAuth tokens are refreshed transparently for both chat execution and model sync.
## Models
Foundry’s `/models` listing is bare (ids only), so capabilities come from Everruns’ built-in Microsoft MAI model profiles, matched by id. Because Azure deployment names are operator-chosen, a deployment whose name does not match a known profile falls back to a minimal profile.
## Links
* [Azure AI Foundry](https://ai.azure.com/)
* [`everruns-drivers` on crates.io](https://crates.io/crates/everruns-drivers), feature `mai`
* [Migrate between providers](https://everruns.com/docs/how-to/migrate-providers/)
---
# Meta
> Run Everruns agents on Muse Wonder and Muse Spark 1.3 through Meta Model API, including the discounted Contributor tier.
Source: `, which is also the name of the key OpenRouter creates. An admin authorizes once; everyone in the org then uses the models the provider serves against the single stored credential. The key is encrypted at rest and never returned by the API.
> OpenRouter’s callback URL must be HTTPS on port 443 or 3000 for non-localhost deployments.
### API key
Alternatively, paste an OpenRouter API key from the [OpenRouter keys page](https://openrouter.ai/keys).
Either way, save and Everruns discovers available models and their capability profiles automatically.
## Routing controls
OpenRouter-specific routing (model fallbacks, provider ordering, capacity strategy, and presets) is configured per agent and applied only to OpenRouter requests, direct OpenAI or other providers ignore these extensions. BYOK-only routing requires you to list at least one upstream provider, and fails closed if none is configured.
## Server tools
OpenRouter can run **provider-executed server tools**: `web_search`, `web_fetch`, `datetime`, `image_generation`, and more, during a generation. OpenRouter executes them server-side and folds the results into the same answer, so your agent gets built-in web reach without a separate search [integration](https://everruns.com/docs/integrations/) or an extra round-trip through Everruns.
Enable them per agent with the [OpenRouter Server Tools capability](https://everruns.com/docs/capabilities/openrouter-server-tools/). The capability is a harmless no-op on non-OpenRouter providers, so it is safe to leave on for agents that may switch providers. Because the model gains provider-executed web access, the capability is rated High risk, grant it only to agents you trust with outbound web access.
## Actual cost
OpenRouter’s API reports the **real money spent** per generation, not just an estimate. Everruns records this as the generation’s authoritative `actual_cost_usd` (sourced from OpenRouter’s `usage.cost`, reconciled against the [generation endpoint](https://openrouter.ai/docs/api-reference/get-a-generation) when needed) alongside its own estimated cost. Budgets debit the actual cost when present and fall back to the estimate otherwise, so spend tracking and [budgeting](https://everruns.com/docs/capabilities/budgeting/) reflect what OpenRouter actually charged.
## Low balance
When a request does not set a token limit, OpenRouter reserves the model’s full output limit against your credits and rejects the call with HTTP 402 (“can only afford N tokens”) if the balance cannot cover it. Set **Max output tokens** on the agent (`max_output_tokens` in the API, `--max-output-tokens` in the CLI) to a value below that number so each call fits. Everruns sends it as `max_tokens` and never asks for more than the model’s own output limit.
## Logs, traces, and observability
Everruns forwards its session id to OpenRouter, so every generation from one Everruns session groups together in OpenRouter’s dashboard. OpenRouter’s own activity logs show each request’s trace, often enough to debug a run without leaving OpenRouter. When you need richer tracing, OpenRouter can forward your generations to external observability tools such as Braintrust or LangSmith; configure that on the OpenRouter side. This complements Everruns’ own [Framework context inspection](https://everruns.com/docs/framework/agents/#inspect-effective-context) rather than replacing it.
## Links
* [OpenRouter](https://openrouter.ai/)
* [OpenRouter docs](https://openrouter.ai/docs)
* [OpenRouter Server Tools capability](https://everruns.com/docs/capabilities/openrouter-server-tools/)
* [`everruns-drivers` on crates.io](https://crates.io/crates/everruns-drivers), feature `openrouter`
* [Integrations overview](https://everruns.com/docs/integrations/)
* [Migrate between providers](https://everruns.com/docs/how-to/migrate-providers/)
---
# Vercel AI Gateway
> Run Everruns agents through Vercel AI Gateway, reaching many upstream model providers over the Open Responses API with one key and automatic model discovery.
Source: /` | Bundled skill | Automatically included, with supporting assets |
| Other project files | Authoring files or unrelated code/data | Omitted unless selected |
`agent.yaml`, `agent.yml`, `agent.json` and `agent.md` are alternative manifest encodings. Do not put multiple manifest filenames at the same root. ZIP contents must start at the agent root, with no enclosing `my-agent/` directory.
Instructions and metadata do not become session files automatically. To make `instructions.md` readable by a tool, explicitly select it in `files`. Runtime files named `agent.toml`, `instructions.md` or another reserved manifest filename are stored inline on export so authoring metadata cannot overwrite them.
Paths are relative to the working-directory root, independent of the execution provider. There is no `workspace/` wrapper. Agent Files are a starting snapshot; new file trees receive that snapshot once. Existing sessions and attachments to existing trees keep their current files. A provider may use a physical directory such as `/workspace`; that prefix is a runtime alias, not a package layout.
## Minimal manifest
```toml
#:schema https://everruns.com/docs/schemas/agent/v1.json
schema_version = 1
name = "my-agent"
```
Add `instructions.md` beside this file. Or keep a self-contained manifest:
```toml
schema_version = 1
name = "my-agent"
instructions = "Help the user with clear, accurate answers."
```
Use `instructions_file = "prompts/main.md"` for a different source path. Nonempty inline instructions and `instructions_file` cannot be combined.
## Manifest fields
Unknown fields fail validation. TOML keys are case-sensitive. All top-level keys must appear before the first `[table]`: a key after `[model]` belongs to the model table, rather than to the agent.
| Field | Type | Default and rules |
| --------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `schema_version` | Integer | `1`; other versions fail. Include it in new definitions. |
| `name` | String | Required stable address: 1–255 lowercase letters, digits or hyphens, starting and ending with a letter or digit. No resource ID. |
| `display_name` | String | Optional human-readable title; host falls back to `name`. |
| `description` | String | Optional purpose or scope description. |
| `instructions` | String | Inline instructions; folders otherwise read `instructions_file` or `instructions.md`. |
| `instructions_file` | String | Safe package-relative instructions path; mutually exclusive with nonempty `instructions`. |
| `tags` | Array of strings | Empty; order does not affect diffs. |
| `model` | Table | Optional provider/model name pair; destination resolves the pair. |
| `harness` | String | Optional named harness; destination default when omitted. |
| `capabilities` | Array | Empty; stable names or `{ ref, config }` objects. Duplicate names fail. |
| `files` | Array | Explicit relative sources, globs, mappings or inline files; see below. |
| `skills` | Array of strings | Folder auto-discovers `.agents/skills/`; explicit values select directories containing direct skill subfolders. |
| `mcpServers` | Table of named servers | Empty; catalog references or inline MCP declarations. |
| `channels` | Table of named channels | Empty; transport descriptions without credentials or destination IDs. |
| `network_access` | Table | Optional `allowed`/`blocked` lists; host enforces the policy. |
| `max_iterations` | Integer | Runtime default; explicit values must be 1–1000. |
| `parallel_tool_calls` | Boolean | Runtime default; explicitly allow or disable concurrent independent calls. |
| `max_output_tokens` | Integer | Provider default; caps output tokens per model response (at least 1, clamped to the model’s limit). |
| `communication` | String | `direct`; `explicit` makes assistant text private notes and the agent talks through `send_message`. See [Explicit communication](https://everruns.com/docs/features/explicit-communication/). |
| `tools` | Array of tool tables | Empty; only client-side tool schemas, requiring executable host bindings. |
| `intro_markdown` | String | Optional Platform introduction displayed before a conversation. |
| `short_description` | String | Optional short Platform discovery text. |
| `starters` | Array of tables | Empty; Platform conversation starters with required `text` and optional `icon`. |
| `environments` | Table | Optional Platform environment declarations; explicit binding required in other hosts. |
Platform resolves its default model and harness when omitted. Framework code binds a model explicitly. Serve uses its simulator when a model is omitted. Framework file creation recognizes `base`, `conversation`, `worker` and `bashkit-worker` (the deprecated `worker-base` binds Bashkit Worker); custom harnesses require a host binding. Defaults that belong to the host are not frozen into portable exports.
## Select and map files
### Preserve paths
```toml
files = ["runbook.md", "data/**"]
```
Each string selects an exact file, directory or glob relative to the package root. `data/**` includes nested files. `data` also selects the directory’s files. Selected files keep their paths: `data/example.csv` becomes `data/example.csv` in the session. Every declared source must match at least one file.
`files = []` deliberately includes no ordinary files. It does not disable skill discovery. A README, source tree or neighboring agent definition is not included unless selected. Avoid `files = ["."]` in a repository unless every allowed file under that root should be packaged.
### Map a source to another destination
```toml
files = [
{ source = "fixtures", path = "data" },
{ source = "templates/report.md", path = "reports/current.md", is_readonly = false },
]
```
| File mapping key | Type | Default |
| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `source` | String | Required safe relative file, directory or glob |
| `path` | String | Omitted: preserve source paths. For a directory, prepend the destination to its contents. For a single file, use the exact destination. |
| `is_readonly` | Boolean | `true`; false lets the session edit or delete the seeded file |
A mapping of `fixtures` to `data` makes `fixtures/a.csv` land at `data/a.csv`. A custom destination on a glob is an exact destination for every match; use a directory mapping when preserving multiple relative child paths.
### Embed content
```toml
[[files]]
path = "notes.md"
content = "Review notes go here."
is_readonly = false
[[files]]
path = "data/sample.bin"
content = "AP8K"
encoding = "base64"
```
| Inline file key | Type | Default |
| --------------- | ------- | -------------------------------------------------------------- |
| `path` | String | Required destination; prefer relative paths |
| `content` | String | Required text or Base64-encoded bytes |
| `encoding` | String | `text`; only `text` and `base64` are accepted |
| `is_readonly` | Boolean | `false` for inline files; set `true` to protect seeded content |
Source-selected files default to read-only; inline files default to writable. Set `is_readonly` explicitly when permissions matter.
Use either the `files = [...]` form or `[[files]]` tables in one TOML document, not both. Strings and inline mapping objects can be mixed in the array form. Leading `/` and `/workspace/` destination aliases are accepted; exports use relative paths. Destinations cannot traverse outside the file tree, duplicate another destination, or collide with a parent file.
## Bundle skills
Default skill discovery reads `.agents/skills//SKILL.md` and every allowed supporting asset under that skill directory. A skill must be a direct child folder, with valid YAML front matter and a `name` matching its directory:
```markdown
---
name: investigate
description: Investigate an issue using the bundled runbook and checklist.
---
Read runbook.md, then references/checklist.md. Report evidence and uncertainties.
```
Scripts, reference documents and binary assets retain their relative paths. Discovery adds the `skills` capability automatically. Including a script does not execute it; execution requires the corresponding host tool and policy.
For another source location, declare `skills = ["team-skills"]`; each child folder lands at `.agents/skills//`. When complete skill trees are explicitly included through `files`, they retain their declared permissions. Incomplete skill trees and invalid or mismatched `SKILL.md` fail validation.
## Model and capabilities
```toml
capabilities = [
"current_time",
{ ref = "session_file_system", config = {} },
]
[model]
provider = "openai"
model = "your-enabled-model"
```
`provider` and `model` must be nonempty names. Platform validation requires one enabled matching destination model. Account availability may vary. Omit this table to use the destination default rather than pinning a model.
A configured capability has `ref` (required string) and `config` (optional object, default `{}`). Configuration is validated by its host capability schema. Installed skill, MCP and plugin resource IDs are not portable capability declarations; use bundled skills or named MCP dependencies instead.
## MCP server settings
### Use an organization MCP server
```toml
[mcpServers.issues]
use = "catalog:linear"
actsAs = "user"
```
Here **catalog** means the organization’s configured MCP servers. `linear` is the server’s name at the destination; it supplies transport and authentication settings. It is a dependency, not an exported server installation or credential.
### Declare a remote or local server
```toml
[mcpServers.docs]
type = "http"
url = "https://example.com/mcp"
[mcpServers.local]
type = "stdio"
command = "python3"
args = ["-m", "my_mcp_server"]
```
HTTP uses a safe public HTTP(S) URL without embedded credentials. Stdio requires a nonempty command; hosted Platform imports reject local process execution. Framework and serve can bind stdio when their MCP stdio support is enabled.
| Server key | Type | Default and rules |
| -------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `use` | String | Optional `catalog:` reference; cannot be combined with inline `type`. |
| `type` | String | `http`; `http` or `stdio`. |
| `url` | String | Required for inline HTTP; ignored for stdio. |
| `command` | String | Required for stdio. |
| `args` | Array of strings | Empty; arguments for stdio. |
| `headers` | Table of strings | Empty; HTTP request headers. |
| `env` | Table of strings | Empty; stdio environment values. |
| `auth_mode` | String | `none`; `none`, `api_key` or `oauth`. Hosted credentials require destination bindings. |
| `actsAs` | String | `none`; `none`, `user`, `service` or `user_or_service` (the person’s grant, else the agent’s), identifying whose grant to use. |
| `deferred` | Boolean | `false`; `true` lists the server’s tools only when the agent loads them through tool search. |
| `connectInChat` | String | `ask`; `ask` pauses the chat on a Connect card when a sign-in is missing, `never` fails the call with a settings link instead. |
| `oauth_provider_id` | String | Optional named provider requirement; installed MCP resource IDs are rejected. |
| `tool_discovery` | Boolean | `true`; discover server tools. |
| `tool_labels` | Table of strings | Empty; risk label per tool name, `read_only` (never asks for approval) or `changes` (always asks). Wins over the tool’s own hints and a catalog server’s labels. |
| `protocol_mode` | String | `auto`; or pin `2025-03-26`, `2025-06-18`, `2026-07-28`. |
| `elicitation_policy` | String | `url`; `url`, `url_and_form` or `none`. |
Use `${ENV_NAME}` for credential-bearing headers/environment values:
```toml
[mcpServers.docs.headers]
Authorization = "${DOCS_AUTHORIZATION}"
```
Framework resolves placeholders through `package.bind_mcp(...)`; serve resolves explicit named requirements at startup. Platform requires catalog bindings for credentials and never reads arbitrary worker environment variables on import.
## Channel descriptions
```toml
[channels.chat]
type = "ag_ui"
enabled = false
[channels.chat.config]
tool_visibility = "generic"
generic_tool_text = "Working…"
rate_limit_per_minute = 30
```
| Channel key | Type | Default and rules |
| ----------- | ----------- | ------------------------------------------------------------------------------------------------------ |
| Table name | Stable name | Lookup/upsert name at the destination; no channel ID. |
| `type` | String | Required known transport: `ag_ui`, `public_chat`, `slack`, `fcp`, `a2a`, `api`, `schedule`, `webhook`. |
| `enabled` | Boolean | `false`; true requests an enabled draft, not automatic publication. |
| `config` | Table | `{}`; transport-specific declarative settings without credentials or resource IDs. |
Platform imports create `ag_ui`, `public_chat`, `fcp` and `slack` channels. Public Chat also requires its feature flag. Other known types require their host/dedicated APIs; Platform validation rejects unsupported bindings. Schedules remain trigger resources. Framework and serve bind transports separately. See [Channels](https://everruns.com/docs/features/channels/) for transport-specific settings.
Updates upsert declared channels, preserve omitted channels and existing activation/credentials, and require permission to modify live configuration. Packages do not transfer publication, grants, sessions, history or deployment state.
## Optional policies and Platform presentation
```toml
intro_markdown = "Welcome to the incident desk."
short_description = "Investigate incidents with evidence."
starters = [{ text = "Investigate the current incident.", icon = "search" }]
[network_access]
allowed = ["https://everruns.com/docs/**"]
blocked = ["https://example.com/private/**"]
```
`blocked` takes precedence. An empty `allowed` list imposes no allowlist restriction. Host policy can further restrict access. Network configuration is descriptive until an enforcing host binds it.
`sandbox_policy` retains the Platform’s Sandbox policy; see [Sandbox Templates](https://everruns.com/docs/features/sandbox-templates/) for the host configuration. The generic Framework package builder rejects this policy until explicitly bound.
A `tools` declaration contains a `client_side` type, `name`, `description` and object JSON Schema `parameters`. Optional display metadata and execution hints follow the [tool schema in the public agent schema](https://everruns.com/docs/schemas/agent/v1.json). The Framework requires a matching host handler and schema; declarations do not transfer executable closures. Built-in tools are selected through capabilities.
## Validation and limits
| Limit | Value |
| --------------------------------------- | ------------------------- |
| Package bytes | 10 MiB |
| Runtime files | 100 |
| Each asset / instructions | 1 MiB |
| Total decoded runtime file content | 5 MiB |
| Channel descriptions | 32 |
| Native folder nesting / visited entries | 32 levels / 1,024 entries |
Validation rejects unknown fields, unsupported versions, unsafe source paths, traversal, symlinks, duplicate or parent-conflicting destinations, malformed Base64, incomplete skills, literal credentials and nonportable resource IDs. Folder/glob collection skips disallowed hidden paths, including `.env`, `.ssh` and `.git`; explicit credential-file sources fail. Explicit inline content is already authored data and is not a host-file read. Review it before sharing.
Editor schema validation cannot inspect file bytes, symlinks, decoded sizes, credential policy or destination dependencies. Run:
```bash
everruns agents validate ./my-agent
everruns agents validate ./my-agent --remote
```
## Public schema and editor integration
Download the [v1 agent schema](https://everruns.com/docs/schemas/agent/v1.json). It is a standalone JSON Schema for the parsed TOML document, with named definitions for file forms, capabilities, MCP settings and channels. YAML and JSON use the same shape. It is generated from the public manifest types, with portable validation bounds.
Use this header for completion and diagnostics in editors supporting the [Taplo schema directive](https://taplo.tamasfe.dev/configuration/directives.html):
```toml
#:schema https://everruns.com/docs/schemas/agent/v1.json
```
This is a comment, not an agent field. Do not add a `$schema` field to the manifest: unknown keys are rejected. Offline editors can download the schema and use `#:schema ./agent-v1.schema.json` instead.
## Compatibility
Legacy Markdown with YAML front matter still imports; its body becomes instructions. `system_prompt`, `initial_files`, `harness_name` and `mcp_servers` remain input aliases. Unversioned legacy files may contain platform IDs; new versioned definitions and exports omit them. The public schema describes canonical authoring, rather than every legacy input alias.
Old `files/` contents map to the runtime root when `files`/`initial_files` is omitted. Explicit `files = []` disables that discovery. Old `skills/` maps to `.agents/skills/`. If both skill roots exist, explicitly choose one using `skills = [".agents/skills"]`. New exports use root-relative files.
---
# CLI command reference
> Every everruns CLI command, grouped by what it manages, with flags and a worked example.
Source: ` | Why you are making this change. Recorded in the changed entity’s history; give one on every command that changes something. |
| `--context-revision ` | The revision of the entity’s manager notes you read (`everruns context get`). The change is refused if the notes changed since. |
| `-o`, `--output ` | `text` (default), `json` or `yaml`. |
| `-q`, `--quiet` | Print only the essential identifier, for capturing ids in scripts. |
## Session and account
| Command | What it does |
| ----------------- | --------------------------------------------------------- |
| `everruns chat` | Send a message and stream the response |
| `everruns login` | Interactive login (localhost OAuth callback) |
| `everruns logout` | Remove stored credentials |
| `everruns status` | Show current user and org |
| `everruns whoami` | Show who the server says you are, and your token’s access |
## Command groups
| Group | What it manages |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| [`agents`](https://everruns.com/docs/reference/cli/agents/) | Agent definitions and their configuration |
| [`budgets`](https://everruns.com/docs/reference/cli/budgets/) | Spending limits for sessions, agents, users and organizations. |
| [`capabilities`](https://everruns.com/docs/reference/cli/capabilities/) | Capabilities agents can use, including declarative ones you define. |
| [`connections`](https://everruns.com/docs/reference/cli/connections/) | Your LLM provider API keys |
| [`context`](https://everruns.com/docs/reference/cli/context/) | Notes managers keep about an entity, read by agents that manage it. |
| [`credential-bindings`](https://everruns.com/docs/reference/cli/credential-bindings/) | Declare, list and revoke write-only credential bindings. |
| [`docker`](https://everruns.com/docs/reference/cli/docker/) | Run Everruns on this machine with Docker |
| [`durable`](https://everruns.com/docs/reference/cli/durable/) | Durable scheduled tasks and their executions. |
| [`evals`](https://everruns.com/docs/reference/cli/evals/) | Evaluation cases, runs, results and scores. |
| [`files`](https://everruns.com/docs/reference/cli/files/) | Sync files between a local folder and a session |
| [`harnesses`](https://everruns.com/docs/reference/cli/harnesses/) | Reusable base setups (prompt plus capabilities) agents build on. |
| [`health-issues`](https://everruns.com/docs/reference/cli/health-issues/) | Operational problems detected in this installation. |
| [`history`](https://everruns.com/docs/reference/cli/history/) | Recorded changes to entities: list, compare, restore. |
| [`images`](https://everruns.com/docs/reference/cli/images/) | Uploaded images. |
| [`knowledge`](https://everruns.com/docs/reference/cli/knowledge/) | File collections with optional indexed retrieval. |
| [`mcp-servers`](https://everruns.com/docs/reference/cli/mcp-servers/) | Registered MCP servers available to agents and sessions. |
| [`memories`](https://everruns.com/docs/reference/cli/memories/) | Workspace memories in the organization. |
| [`models`](https://everruns.com/docs/reference/cli/models/) | LLM models available to agents, and organization defaults. |
| [`notifications`](https://everruns.com/docs/reference/cli/notifications/) | Your in-app notifications. |
| [`observers`](https://everruns.com/docs/reference/cli/observers/) | Online scoring of live traces. |
| [`orgs`](https://everruns.com/docs/reference/cli/orgs/) | Organizations you belong to, and which one is active |
| [`payments`](https://everruns.com/docs/reference/cli/payments/) | Machine payments: wallets, spend policies and attempts. |
| [`plugin-marketplaces`](https://everruns.com/docs/reference/cli/plugin-marketplaces/) | Sources of installable plugins. |
| [`plugins`](https://everruns.com/docs/reference/cli/plugins/) | Plugins installed in this organization. |
| [`providers`](https://everruns.com/docs/reference/cli/providers/) | LLM providers and their credentials. |
| [`reports`](https://everruns.com/docs/reference/cli/reports/) | Usage and cost reporting: queries, saved reports, catalog. |
| [`resources`](https://everruns.com/docs/reference/cli/resources/) | Access to credentials and connections. |
| [`sandbox-targets`](https://everruns.com/docs/reference/cli/sandbox-targets/) | Sandbox providers this deployment offers. |
| [`sandboxes`](https://everruns.com/docs/reference/cli/sandboxes/) | Sandboxes across providers: state, history, usage. |
| [`sessions`](https://everruns.com/docs/reference/cli/sessions/) | Running and archived sessions, their state and participants |
| [`skills`](https://everruns.com/docs/reference/cli/skills/) | Skill packages and their content. |
| [`system`](https://everruns.com/docs/reference/cli/system/) | Server status. |
| [`tasks`](https://everruns.com/docs/reference/cli/tasks/) | Background tasks across every session in the organization. |
| [`user`](https://everruns.com/docs/reference/cli/user/) | Your own account settings. |
| [`users`](https://everruns.com/docs/reference/cli/users/) | People in the current organization. |
| [`virtual-users`](https://everruns.com/docs/reference/cli/virtual-users/) | Runtime accounts for consumers or services. |
| [`workspaces`](https://everruns.com/docs/reference/cli/workspaces/) | Durable working areas holding the files agents work on. |
---
# everruns agents
> Agent definitions and their configuration. CLI reference for everruns agents: usage, flags and examples.
Source: ` | |
| `--content ` | Inline definition (also supported by Platform Chat and MCP) |
| `--target ` | Explicit existing agent name to update. |
| `--format ` | |
## agents export
Export an agent by name without IDs or credentials.
```bash
everruns agents export [OPTIONS]
```
| Flag | Description |
| ------------------- | ----------------------------------------------------------- |
| `` | Required. |
| `--format ` | One of `markdown`, `toml`, `yaml`, `json`, `zip`, `folder`. |
| `--out ` | |
## agents validate
Validate a package locally, or also check destination dependencies.
```bash
everruns agents validate [OPTIONS]
```
| Flag | Description |
| ---------- | ----------- |
| `` | Required. |
| `--remote` | |
## agents diff
Generate a semantic diff against a local package or a remote agent.
```bash
everruns agents diff [OPTIONS]
```
| Flag | Description |
| --------------------- | ----------- |
| `` | Required. |
| `--against ` | |
| `--target ` | |
## agents create
Create a new agent (upserts if id: is present in frontmatter)
```bash
everruns agents create [OPTIONS]
```
| Flag | Description |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `-f`, `--file ` | TOML/YAML/JSON/Markdown file with agent definition. |
| `--initial-files-dir ` | Directory of files to upload as initial_files (read-only by default) |
| `--writable` | Make initial files writable (default: read-only) |
| `--name ` | Agent name (required if no —file) |
| `--instructions ` | System prompt (required if no —file) |
| `--description ` | Agent description. |
| `--model ` | Default model ID (e.g. mod_xxx) |
| `-H`, `--harness ` | Harness ID or name (e.g. harness_xxx or “generic”). Omit to default to the org’s generic harness. |
| `-t`, `--tag ` | Tag. Repeat for each, or pass one JSON array of strings. Repeatable. |
## agents update
Update an existing agent from a file definition.
```bash
everruns agents update [OPTIONS] [AGENT_ID]
```
| Flag | Description |
| ----------------------------------------- | --------------------------------------------------------------------- |
| `` | Agent ID (e.g. agent_xxx). If omitted, uses id from file frontmatter. |
| `-f`, `--file ` | TOML/YAML/JSON/Markdown file with agent definition. |
| `--initial-files-dir ` | Directory of files to upload as initial_files (read-only by default) |
| `--writable` | Make initial files writable (default: read-only) |
| `--name ` | Agent name. |
| `--instructions ` | System prompt. |
| `--description ` | Agent description. |
| `--model ` | Default model ID (e.g. mod_xxx) |
| `-H`, `--harness ` | Harness ID or name (e.g. harness_xxx or “generic”) |
| `-t`, `--tag ` | Tag. Repeat for each, or pass one JSON array of strings. Repeatable. |
## agents analyze
Run advisory checks (built-in rules plus LLM analysis) against an agent configuration.
```bash
everruns agents analyze [OPTIONS]
```
| Flag | Description |
| --------------------------------- | ----------- |
| `--capabilities ` | |
| `--harness-id ` | |
| `--initial-files ` | |
| `--mcp-servers ` | |
| `--system-prompt ` | |
| `--tools ` | |
Example:
```bash
# Check a draft configuration for problems before creating the agent
everruns agents analyze --system-prompt 'Triage incoming issues' --tools '["bash"]'
```
## agents check-name
Check whether an agent name is available.
```bash
everruns agents check-name [OPTIONS] --name
```
| Flag | Description |
| --------------------------- | ------------------------------ |
| `--exclude-id ` | |
| `--name ` | Required. Human-readable name. |
Example:
```bash
# See whether a name is free before creating an agent
everruns agents check-name --name triage
```
## agents copy
Copy an agent. Generates a unique name.
```bash
everruns agents copy [OPTIONS] [ID]
```
| Flag | Description |
| ----------- | --------------------------- |
| `--id ` | Prefixed public identifier. |
Example:
```bash
# Duplicate an agent to try a change without touching the original
everruns agents copy agent_01h9 --reason 'Trial a stricter prompt'
```
## agents delete
Archive an agent (soft delete). Can be restored.
```bash
everruns agents delete [OPTIONS] [ID]
```
| Flag | Description |
| ----------- | --------------------------- |
| `--id ` | Prefixed public identifier. |
Example:
```bash
# Archive an agent, keeping it restorable
everruns agents delete agent_01h9 --reason 'Replaced by triage-v2'
```
## agents destroy
Permanently delete an archived agent.
```bash
everruns agents destroy [OPTIONS] [ID]
```
| Flag | Description |
| ----------- | --------------------------- |
| `--id ` | Prefixed public identifier. |
Example:
```bash
# Permanently remove an already-archived agent
everruns agents destroy agent_01h9 --reason 'Retired after the archive window'
```
## agents draft
Revise an agent draft from a conversation with the agent builder. Returns the draft only; nothing is created.
```bash
everruns agents draft [OPTIONS] --messages
```
| Flag | Description |
| ----------------------- | -------------------------------------------- |
| `--draft ` | |
| `--messages ` | Required. Conversation so far, oldest first. |
Example:
```bash
# Ask the builder for a first draft
everruns agents draft --messages '[{"role":"user","content":"Triage new GitHub issues every morning"}]'
```
## agents get
Get a single agent by ID or name.
```bash
everruns agents get [OPTIONS] [ID]
```
| Flag | Description |
| ----------- | --------------------------- |
| `--id ` | Prefixed public identifier. |
Example:
```bash
# Show one agent's full configuration
everruns agents get agent_01h9
```
## agents list
List all active agents. Use search for name search, include_archived=true to include archived. Supports pagination (limit/offset).
```bash
everruns agents list [OPTIONS]
```
| Flag | Description |
| -------------------- | ---------------------------------------------- |
| `--include-archived` | |
| `--limit ` | Maximum number of items returned in this page. |
| `--offset ` | Zero-based offset into the result set. |
| `--search ` | |
Example:
```bash
# Find agents by name when you do not know the id
everruns agents list --search triage --limit 20
```
## agents preview
Preview the final agent shape with capabilities applied.
```bash
everruns agents preview [OPTIONS]
```
| Flag | Description |
| --------------------------------- | ----------- |
| `--capabilities ` | |
| `--harness-id ` | |
| `--initial-files ` | |
| `--mcp-servers ` | |
| `--system-prompt ` | |
| `--tools ` | |
Example:
```bash
# See the prompt a draft configuration would produce, without creating it
everruns agents preview --system-prompt 'Triage incoming issues'
```
## agents upsert
Upsert agent — create (201) or update (200) by ID.
```bash
everruns agents upsert [OPTIONS] --name --system-prompt [ID]
```
| Flag | Description |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `--id ` | Client-supplied agent ID (format: agent\_{32-hex}). If not provided, one is auto-generated. |
| `--capabilities ` | Capabilities to enable for this agent with per-agent configuration. Each capability has a \`re… |
| `--communication ` | How an agent talks to the people in its conversations. One of `direct`, `explicit`. |
| `--default-model-id ` | The ID of the default LLM model to use for this agent. If not specified, the system default m… |
| `--description ` | A human-readable description of what the agent does. |
| `--display-name ` | Human-readable display name shown in UI. Falls back to `name` when absent. |
| `-H`, `--harness ` | Addressable harness name. |
| `--harness-id ` | Harness ID used as this agent’s base execution environment. |
| `--initial-files ` | Starter files copied into each new session for this agent. |
| `--intro-markdown ` | Markdown intro shown as an intro box on a fresh Platform Chat thread. Images are allowed. |
| `--max-iterations ` | Maximum number of LLM iterations per turn for this agent. |
| `--max-output-tokens ` | Ceiling on output tokens per model response (sent as `max_tokens`). Omit to use the provider … |
| `--mcpServers ` | |
| `--name ` | Required. Name, unique per org. |
| `--network-access ` | |
| `--parallel-tool-calls` | Request-level parallel tool calling preference (EVE-598). |
| `--sandbox-policy ` | |
| `--service-virtual-user-id ` | |
| `--short-description ` | One-line description in simplified Markdown, shown below the chat title once the intro is hid… |
| `--starters ` | Conversation starters for a fresh Platform Chat thread. |
| `--system-prompt ` | Required. The system prompt that defines the agent’s behavior and capabilities. This is sent as the fir… |
| `--tags ` | Tags for organizing and filtering agents. Comma-separated or a JSON array of strings. Repeatable. |
| `--tools