Import agent from file or built-in example
PreviewTwo modes:
- From example —
POST /v1/agents/import?from-example={name}(body ignored) - From package — text (Markdown/TOML/YAML/JSON), ZIP, or a PackageInput envelope.
Package mode accepts:
- Markdown with YAML front matter (if starts with —)
- Pure YAML
- Pure JSON
- Plain text (treated as instructions; defaults to name agent)
- TOML and ZIP folders, with complete assets and skill directories
If the file contains an id field and an agent with that ID already exists,
the agent is updated (upsert). Returns 201 on create, 200 on update.
/v1/agents/importSee authentication for credentials and permissions.
Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Import from a built-in example by name (e.g. dad-jokes-agent).
When set, the request body is ignored.
Explicit target agent name for an update. Omit to create a new agent.
Input format: markdown, toml, yaml, json or zip. Omit to detect it.
Request Bodyrequired
Section titled “Request Bodyrequired”Responses
200Agent updated via import
Agent updated via import
Wrapper that adds API and UI links to a serialized resource.
Uses self_url (not url) for the API link to avoid collision with
resources that already have a url field (e.g. McpServer). The
allowed_actions array carries state-aware hypermedia links — empty
(and omitted from the wire shape) until the underlying resource opts
into the convention by overriding ResourceUrlable::allowed_actions.
object
Timestamp when the agent was archived.
Avatar shown wherever the agent appears: the UI, the A2A Agent Card and
its Slack app. Set with PUT /v1/agents/{agent_id}/avatar.
object
Circular avatar (transparent corners), 256 px.
Prefixed public identifier. See ID Schema.
Edge lengths, in pixels, available for both shapes.
Square avatar, 256 px.
Capabilities enabled for this agent with per-agent configuration. Capabilities add tools and system prompt modifications.
Per-agent capability configuration
Associates a capability with an agent, including optional per-agent configuration. The config field allows the same capability to behave differently per-agent.
object
Per-agent configuration for this capability (capability-specific)
Reference to the capability ID
How the agent talks to people. direct (default): its replies are
what it writes. explicit: what it writes is private working notes,
and people see only the messages it sends with send_message. Applies
on every surface: web chat, API, Slack, A2A, AG-UI, MCP.
When a turn about to finish is checked for whether it did what was
asked, and continued automatically when it did not. unattended
(default): sessions started by triggers and schedules, where no person
is watching. always: chat too. off: never.
Timestamp when the agent was created.
Default LLM model ID for this agent. Can be overridden at the session level.
Timestamp when the agent was deleted.
Human-readable description of what the agent does.
Human-readable display name shown in UI (e.g. “Customer Support Agent”).
Falls back to name when absent.
Whether any endpoint on this agent is currently live. Derived from the endpoint rows on read and never stored: a stored flag would be a second writer for state the endpoints already own.
Incident switch: when true, no endpoint on this agent accepts traffic (EVE-1007). Distinct from archiving — it leaves per-endpoint status untouched so clearing it restores exactly the previously live set.
Source agent for a forked agent.
Harness that supplies the base execution environment for this agent.
External identifier (agent_<32-hex>). Shown as “id” in API. Client-supplied or auto-generated.
Starter files copied into each new session for this agent.
Starter file copied into a new session from an agent or harness.
object
File content: plain text or base64-encoded binary.
Content encoding: text or base64.
Prevent session-side edits or deletes when true.
Absolute path within the session workspace. /workspace prefix is accepted.
Optional Markdown intro rendered as an intro box at the top of a fresh Platform Chat thread. Images are allowed. Wins over the harness intro. Hidden once the user inputs.
Built-in agents (Platform Chat) are provisioned by the platform and are read-only: they cannot be modified or deleted via the API. Copy one to get an editable version.
Locale-keyed display overlays; identifiers and execution instructions are unchanged.
object
Display-only translations shared by portable agent files and platform resources. Addresses, tool identifiers and execution instructions never use these values.
object
Localized description (1–2000 characters when set).
Localized display name (1–255 characters when set).
Maximum number of LLM iterations per turn for this agent.
Ceiling on output tokens per model response, sent to the provider as
max_tokens. Unset keeps the provider default. Clamped to the model’s
output limit when known. Lower it when a provider rejects calls because
the balance can only afford fewer tokens.
Remote MCP servers scoped to this agent and inherited by its sessions.
object
Session-, agent-, or harness-scoped remote MCP server configuration.
This intentionally mirrors the mcpServers object shape used by common MCP
client config files while staying within Everruns’ current remote-HTTP-only
support.
object
Identity whose grant this attachment requests.
Arguments passed to the stdio command.
Authentication mode used when executing tools from this scoped server.
Executable to spawn for a stdio transport server.
Whether a missing sign-in may pause the turn with an in-chat Connect
card (ask, the default) or fails the call with a settings link
(never).
Whether the server’s tools are listed only when the model asks for
them through tool search (false, the default, lists them at turn
start).
Searchable server context supplied by its attachment or catalog. It is metadata, not an instruction or a credential.
Which elicitation modes this server may use (url by default).
Environment variables set for the stdio command.
object
Additional HTTP headers sent on MCP requests (HTTP transport only).
object
Provider id used to resolve a user-scoped bearer token.
Protocol-era adoption policy for the MCP client (auto negotiates).
Whether to discover tool definitions live from this server.
Risk labels for this server’s tools, by the tool’s own name:
read_only never asks for approval in the normal mode, changes
always asks. They win over the tool’s annotations and over a catalog
preset’s saved labels. Honored on harness, agent and person-owned
servers; dropped from session-scoped servers.
object
A person’s saved risk label for one MCP tool.
Decision (2026-10-10): a person’s label always wins over the tool’s own
annotations, because a remote server describes itself and a person who
owns the integration knows better. read_only also clears open_world,
since tool approval treats an outward-reaching tool like a destructive one;
without that a read-only MCP tool would still ask every time.
How long one tools/call to this server may take, in milliseconds.
Unset means [MCP_TOOL_TIMEOUT_DEFAULT_MS] (60 s); accepted range is
[MCP_TOOL_TIMEOUT_MIN_MS]..=[MCP_TOOL_TIMEOUT_MAX_MS]. timeout
is accepted as an alias, matching common mcpServers config files.
MCP transport type. Only remote HTTP is supported today.
URL of the remote MCP server endpoint. Required for HTTP transport; empty/ignored for stdio.
Name, unique per org (e.g. “customer-support”).
Network access list controlling which hosts/URLs agent sessions can reach. Merged with harness and session layers (allowed: intersect, blocked: union).
object
Allowed host patterns. If non-empty, only matching URLs are permitted. An empty list means “no restriction from this layer” (inherit parent).
Blocked host patterns. Always denied, even if matched by allowed.
Agent this one was created as part of, shown as “Created here” on that agent’s Agents tab and bundled into its export.
Request-level parallel tool calling preference (EVE-598).
None (default) preserves provider defaults. Some(true) signals the
provider that parallel tool calls are wanted; Some(false) requests at
most one tool call per turn and forces serial execution. Merged across
harness/agent/session layers (overlay wins).
Root agent lineage identifier for grouping fork families.
Policy for selecting the primary Sandbox Template for new Sessions.
object
Template binding inherited when Session creation does not choose one.
Template snapshots addressable by binding name at Session creation.
object
Desired Sandbox configuration authored by a human or application.
Containment and durability may be omitted when the target has exactly one honest answer. Resolution fills those fields before the specification is pinned to a Session.
object
Reproducible commands run when physical compute is initialized.
object
Ordered commands replayed when creating or recovering physical compute.
Requested isolation policy; resolution supplies an honest target default.
object
Whether the runtime may widen containment after Session creation.
Filesystem mutation boundary for command execution.
object
Absolute roots the runtime may mutate; empty means provider default.
Isolation mechanism the provider must supply.
Idle lifecycle policy controlled by Everruns.
object
How long a paused Sandbox is kept, counted from its last activity,
before Everruns deletes it with its files. The Session stays; its next
Sandbox call provisions a fresh one. null keeps paused Sandboxes
until their Session is deleted.
Action Everruns requests after the idle interval.
Inactivity interval before applying idle_action.
Provider-neutral target plus its concrete adapter binding.
object
Credential/transport binding for a registered machine target.
Provider credential source. User and Agent bindings are resolved to an exact virtual user when the Session starts; organization bindings also pin the exact connection.
object
Exact connection for organization grants, which may have several accounts for one provider.
Identity scope from which the provider credential is resolved.
Exact virtual-user owner for user, Agent, and organization grants.
Provider-neutral target class.
Provider-owned, non-secret configuration. Credentials are references, never values in this object.
object
Concrete adapter for target kinds with more than one implementation.
Immutable Sandbox Template revision this specification was copied from. The specification remains complete so Agent snapshots are portable and later template revisions cannot change an existing snapshot.
Org-scoped service account used when a tool acts as the agent.
Optional one-line description in simplified Markdown, shown below the chat title once the intro is hidden. Wins over the harness value.
Conversation starters for a fresh Platform Chat thread. Win over the harness starters when non-empty.
A conversation starter shown on a fresh Platform Chat thread.
Selecting one inserts its text into the composer. icon reuses the
harness icon name set (HarnessIcon); unknown names fall back to the
default glyph.
object
Optional icon name from the harness icon set.
Prompt text inserted into the composer when selected.
Current lifecycle status of the agent.
System prompt that defines the agent’s behavior. Sent as the first message in every conversation.
Tags for organizing and filtering agents.
Client-side tools registered for this agent. These tools are executed by the client, not the server.
Built-in tool - executed by the worker via ToolRegistry
object
Category for tool_search namespace grouping (from parent capability)
Whether this tool’s schema can be deferred via tool_search
Tool description for LLM
Human-readable display name for UI rendering (e.g., “Get Current Time” for get_current_time)
Original full parameter schema saved by DeferSchemaHook before stripping.
Serialized only when present so durable reason-to-act scheduling can
preserve deferred schemas for tool_search in the act phase.
Semantic hints describing the tool’s behavioral properties
object
Declared capability description for source-aware tool discovery. Never populate this with system prompts, conversation state or secrets.
Capability that contributed this tool definition.
Reporting uses this attribution only as metadata. It must never contain tool arguments, results, prompts, or any other sensitive payload.
Human-readable capability name snapshot for reporting.
Scheduling conflict key. Tool calls within the same act batch that share
a non-empty concurrency_class are executed sequentially in arrival
order; calls in different classes (or with no class) run concurrently.
Set this on tools that mutate shared session state so that, e.g., two
file writes or two SQL mutations in one batch do not race. Read-only
tools should leave this None so they always parallelize. See
everruns-engine’s tool scheduler for how the act phase consumes it.
Tool performs significant CPU-bound or otherwise non-yielding work in
process (e.g. an in-process interpreter). When true, the act scheduler
runs the call on its own task (tokio::spawn) so a long CPU burst does
not starve the cooperative polling of I/O-bound tools in the same batch.
Distinct from long_running, which describes wall-clock time for
I/O-bound work (those tools yield at await points and need no offload).
Tool may irreversibly destroy or delete data. Subset of non-readonly — a tool can be non-readonly (writes) without being destructive (e.g., create/update operations).
Calling the tool repeatedly with the same arguments produces the same effect. Safe to retry on transient failures.
Tool may take significant time to complete (> ~5s typical). Useful for clients to show progress indicators and set timeouts.
Host-owned annotations that core does not interpret.
The typed hints above are the vocabulary core itself reasons about. This
is the escape hatch for everything a host wants to carry alongside a
tool — risk tiers for an approval UI, presentation hints, an embedder’s
routing keys — without adding a field to core for each one. Core reads
nothing here and no driver sends it to a provider; it travels with the
definition so a consumer sees it at the point of decision (e.g. a
PreToolUseHook gating on what the tool declared).
The schema belongs to whoever writes it. Never put credentials or other sensitive payload here: like the rest of the definition, it is persisted and surfaced to clients.
Entity noun for operation-based narration (e.g. “agent”, “harness”).
When set, the narration system reads the operation argument and
produces verb-based narration like “Created agent: Neon Cartographer”
instead of the generic “Ran Manage Agents”.
Tool interacts with external entities beyond the local system (network calls, third-party APIs, cloud services).
Tool output should be persisted to session VFS before truncation.
When set, the tool_output_persistence capability (EVE-222, EVE-245) writes
stdout to /outputs/{tool_call_id}.stdout and stderr to
/outputs/{tool_call_id}.stderr, injecting full_output, total_lines,
and output_files into the result.
Tool does not modify any state (read-only queries, lookups). When true: safe to call speculatively, result can be cached.
Tool requires API keys, credentials, or other secrets to function. Useful for UI to show connection prompts and for LLMs to anticipate authentication failures.
Replay-safety class used by the durable Act activity (EVE-530).
Controls what happens when a worker reclaims a stale running claim:
Pure/Idempotent tools are re-executed; AtMostOnce tools are
settled as interrupted to prevent double side-effects.
None is treated conservatively as AtMostOnce.
Tool must stay a direct tool call and never runs from inside a shell
script (tools_in_shell): it pauses or shapes the turn, or its result
only makes sense to the model directly.
Tool supports detached background execution via spawn_background.
When true, the tool may be executed asynchronously outside the current
foreground tool call and report status back later.
Tool name (used by LLM and for registry lookup)
JSON schema for tool parameters
Tool policy (auto or requires_approval)
Client-side tool - executed by the client, not the server
object
Category for tool_search namespace grouping (from parent capability)
Whether this tool’s schema can be deferred via tool_search
Tool description for LLM
Human-readable display name for UI rendering
Original full parameter schema saved by DeferSchemaHook before stripping.
Serialized only when present so durable reason-to-act scheduling can
preserve deferred schemas for tool_search in the act phase.
Semantic hints describing the tool’s behavioral properties
object
Declared capability description for source-aware tool discovery. Never populate this with system prompts, conversation state or secrets.
Capability that contributed this tool definition.
Reporting uses this attribution only as metadata. It must never contain tool arguments, results, prompts, or any other sensitive payload.
Human-readable capability name snapshot for reporting.
Scheduling conflict key. Tool calls within the same act batch that share
a non-empty concurrency_class are executed sequentially in arrival
order; calls in different classes (or with no class) run concurrently.
Set this on tools that mutate shared session state so that, e.g., two
file writes or two SQL mutations in one batch do not race. Read-only
tools should leave this None so they always parallelize. See
everruns-engine’s tool scheduler for how the act phase consumes it.
Tool performs significant CPU-bound or otherwise non-yielding work in
process (e.g. an in-process interpreter). When true, the act scheduler
runs the call on its own task (tokio::spawn) so a long CPU burst does
not starve the cooperative polling of I/O-bound tools in the same batch.
Distinct from long_running, which describes wall-clock time for
I/O-bound work (those tools yield at await points and need no offload).
Tool may irreversibly destroy or delete data. Subset of non-readonly — a tool can be non-readonly (writes) without being destructive (e.g., create/update operations).
Calling the tool repeatedly with the same arguments produces the same effect. Safe to retry on transient failures.
Tool may take significant time to complete (> ~5s typical). Useful for clients to show progress indicators and set timeouts.
Host-owned annotations that core does not interpret.
The typed hints above are the vocabulary core itself reasons about. This
is the escape hatch for everything a host wants to carry alongside a
tool — risk tiers for an approval UI, presentation hints, an embedder’s
routing keys — without adding a field to core for each one. Core reads
nothing here and no driver sends it to a provider; it travels with the
definition so a consumer sees it at the point of decision (e.g. a
PreToolUseHook gating on what the tool declared).
The schema belongs to whoever writes it. Never put credentials or other sensitive payload here: like the rest of the definition, it is persisted and surfaced to clients.
Entity noun for operation-based narration (e.g. “agent”, “harness”).
When set, the narration system reads the operation argument and
produces verb-based narration like “Created agent: Neon Cartographer”
instead of the generic “Ran Manage Agents”.
Tool interacts with external entities beyond the local system (network calls, third-party APIs, cloud services).
Tool output should be persisted to session VFS before truncation.
When set, the tool_output_persistence capability (EVE-222, EVE-245) writes
stdout to /outputs/{tool_call_id}.stdout and stderr to
/outputs/{tool_call_id}.stderr, injecting full_output, total_lines,
and output_files into the result.
Tool does not modify any state (read-only queries, lookups). When true: safe to call speculatively, result can be cached.
Tool requires API keys, credentials, or other secrets to function. Useful for UI to show connection prompts and for LLMs to anticipate authentication failures.
Replay-safety class used by the durable Act activity (EVE-530).
Controls what happens when a worker reclaims a stale running claim:
Pure/Idempotent tools are re-executed; AtMostOnce tools are
settled as interrupted to prevent double side-effects.
None is treated conservatively as AtMostOnce.
Tool must stay a direct tool call and never runs from inside a shell
script (tools_in_shell): it pauses or shapes the turn, or its result
only makes sense to the model directly.
Tool supports detached background execution via spawn_background.
When true, the tool may be executed asynchronously outside the current
foreground tool call and report status back later.
Tool name (used by LLM and for correlation)
JSON schema for tool parameters
Timestamp when the agent was last updated.
Cumulative token usage across all sessions for this agent.
object
Actual cost of this generation in USD, as reported by the provider inline
(e.g. OpenRouter’s usage.cost, which reflects real post-routing/BYOK/cache
pricing). None for providers that do not return a cost.
Number of tokens written to cache, disjoint from input_tokens
Number of tokens read from cache (reduces cost), disjoint from input_tokens
Best-effort USD cost when it cannot be derived from actual/estimated alone: already-aggregated usage, or a generation carrying a cost that belongs to neither slot. Per-generation usage normally leaves this unset and derives the effective cost from actual-else-estimated; the exception is a turn whose compaction cost is folded in, where the combined total has to live here precisely so the generation’s own actual-vs-estimated distinction survives (EVE-895).
Estimated cost of this generation in USD, derived from the model’s static
price-table profile. Computed whenever a profile with cost data exists,
independently of actual_cost_usd, so estimate-vs-actual drift can be
reconciled. None when there is no profile cost data for the model.
Number of non-cached prompt tokens (cached reads/writes are tracked separately; see the disjoint bucket convention on the struct)
Number of output/completion tokens
State-aware hypermedia actions the caller can take on this resource
next (e.g. cancel, events, update). Omitted from the wire
shape when empty so resources that haven’t opted into the
convention don’t grow their payloads.
Agent-actionable link describing a follow-up the caller can take. Used in two contexts:
- Error recovery —
ErrorResponse.allowed_actionscarriesrels likeretry,retry-later,unarchive,get-existingso the agent knows the right next call after a 4xx/429. - Entity hypermedia —
WithUrls<T>.allowed_actionscarries state-awarerels likecancel,events,self,updateon the entity itself so the agent can follow links instead of reconstructing routes from prose.
The shape is intentionally identical across both contexts; the closed
rel vocabulary distinguishes them.
object
Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).
Absolute (preferred) or relative URL the caller may invoke
directly. Always present on entity hypermedia actions
(WithUrls<T>.allowed_actions); optional on error-recovery
actions (ErrorResponse.allowed_actions) where the matching
operation_id is enough and the URI is implicit from the failed
call.
HTTP method to use against href. Required for entity hypermedia
actions; usually omitted on error-recovery actions where the same
operation is retried with its original method.
OpenAPI operationId the caller should invoke. Lets an MCP client
resolve the call without parsing href.
Link relation describing the action. Examples: self, cancel, pause,
resume, events, retry, retry-later, unarchive,
get-existing, delete, update.
OpenAPI $ref to the request-body schema, when the action takes one
(e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling
agent fetch the input shape without scanning the whole spec.
Full API endpoint URL for this resource.
Alias for view_url, used by command and MCP outputs.
Full UI URL for viewing this resource.
Example
{ "archived_at": "2026-05-26T00:00:00Z", "avatar": { "circle_url": "/v1/avatars/avatar_01933b5a000070008000000000000001/circle-256.png", "id": "avatar_01933b5a000070008000000000000001", "sizes": [ 32, 64, 128, 256, 512 ], "url": "/v1/avatars/avatar_01933b5a000070008000000000000001/square-256.png" }, "communication": "direct", "completion_check": "off", "created_at": "2026-04-01T10:00:00Z", "default_model_id": "model_01933b5a00007000800000000000001", "deleted_at": "2026-05-26T00:00:00Z", "description": "Handles refund and shipping questions; escalates billing disputes.", "display_name": "Customer Support Agent", "forked_from_agent_id": "agent_01933b5a00007000800000000000001", "harness_id": "harness_01933b5a00007000800000000000001", "id": "agent_01933b5a000070008000000000000001", "intro_markdown": "Hey, I'm Ava. Ask me anything about your account.", "is_built_in": false, "max_iterations": 50, "max_output_tokens": 4096, "mcpServers": { "additionalProperty": { "actsAs": "none", "auth_mode": "none", "connectInChat": "ask", "elicitation_policy": "url", "protocol_mode": "auto", "tool_labels": { "additionalProperty": "read_only" }, "type": "http", "use": "catalog:linear" } }, "model_role": "research", "name": "customer-support", "network_access": { "allowed": [ "*.example.com", "https://api.acme.com/" ], "blocked": [ "169.254.169.254" ] }, "owner_agent_id": "agent_01933b5a00007000800000000000001", "parallel_tool_calls": true, "root_agent_id": "agent_01933b5a00007000800000000000001", "sandbox_policy": { "default": "primary", "mode": "fixed", "templates": { "additionalProperty": { "containment": { "escalation": "never", "level": "none", "network": { "mode": "deny" } }, "durability": "checkpointed", "lifecycle": { "delete_after_seconds": 259200, "idle_action": "checkpoint_and_stop", "idle_after_seconds": 300 }, "target": { "connection_id": "conn_01933b5a000070008000000000000001", "credential": { "connection_id": "00000000-0000-0000-0000-000000000002", "source": "none", "virtual_user_id": "00000000-0000-0000-0000-000000000001" }, "kind": "host", "provider": "daytona" } } } }, "short_description": "Answers account questions in seconds.", "starters": [ { "icon": "zap", "text": "Triage the newest P1" } ], "status": "active", "system_prompt": "You are a friendly customer support agent for Acme Corp. Verify orders before issuing refunds. Escalate any billing disputes to a human.", "tags": [ "support", "production" ], "tools": [ { "deferrable": "never", "hints": { "side_effect_class": "Pure" }, "policy": "auto", "type": "builtin" } ], "updated_at": "2026-05-20T14:00:00Z", "allowed_actions": [ { "method": "POST" } ]}201Agent imported successfully
Agent imported successfully
Wrapper that adds API and UI links to a serialized resource.
Uses self_url (not url) for the API link to avoid collision with
resources that already have a url field (e.g. McpServer). The
allowed_actions array carries state-aware hypermedia links — empty
(and omitted from the wire shape) until the underlying resource opts
into the convention by overriding ResourceUrlable::allowed_actions.
object
Timestamp when the agent was archived.
Avatar shown wherever the agent appears: the UI, the A2A Agent Card and
its Slack app. Set with PUT /v1/agents/{agent_id}/avatar.
object
Circular avatar (transparent corners), 256 px.
Prefixed public identifier. See ID Schema.
Edge lengths, in pixels, available for both shapes.
Square avatar, 256 px.
Capabilities enabled for this agent with per-agent configuration. Capabilities add tools and system prompt modifications.
Per-agent capability configuration
Associates a capability with an agent, including optional per-agent configuration. The config field allows the same capability to behave differently per-agent.
object
Per-agent configuration for this capability (capability-specific)
Reference to the capability ID
How the agent talks to people. direct (default): its replies are
what it writes. explicit: what it writes is private working notes,
and people see only the messages it sends with send_message. Applies
on every surface: web chat, API, Slack, A2A, AG-UI, MCP.
When a turn about to finish is checked for whether it did what was
asked, and continued automatically when it did not. unattended
(default): sessions started by triggers and schedules, where no person
is watching. always: chat too. off: never.
Timestamp when the agent was created.
Default LLM model ID for this agent. Can be overridden at the session level.
Timestamp when the agent was deleted.
Human-readable description of what the agent does.
Human-readable display name shown in UI (e.g. “Customer Support Agent”).
Falls back to name when absent.
Whether any endpoint on this agent is currently live. Derived from the endpoint rows on read and never stored: a stored flag would be a second writer for state the endpoints already own.
Incident switch: when true, no endpoint on this agent accepts traffic (EVE-1007). Distinct from archiving — it leaves per-endpoint status untouched so clearing it restores exactly the previously live set.
Source agent for a forked agent.
Harness that supplies the base execution environment for this agent.
External identifier (agent_<32-hex>). Shown as “id” in API. Client-supplied or auto-generated.
Starter files copied into each new session for this agent.
Starter file copied into a new session from an agent or harness.
object
File content: plain text or base64-encoded binary.
Content encoding: text or base64.
Prevent session-side edits or deletes when true.
Absolute path within the session workspace. /workspace prefix is accepted.
Optional Markdown intro rendered as an intro box at the top of a fresh Platform Chat thread. Images are allowed. Wins over the harness intro. Hidden once the user inputs.
Built-in agents (Platform Chat) are provisioned by the platform and are read-only: they cannot be modified or deleted via the API. Copy one to get an editable version.
Locale-keyed display overlays; identifiers and execution instructions are unchanged.
object
Display-only translations shared by portable agent files and platform resources. Addresses, tool identifiers and execution instructions never use these values.
object
Localized description (1–2000 characters when set).
Localized display name (1–255 characters when set).
Maximum number of LLM iterations per turn for this agent.
Ceiling on output tokens per model response, sent to the provider as
max_tokens. Unset keeps the provider default. Clamped to the model’s
output limit when known. Lower it when a provider rejects calls because
the balance can only afford fewer tokens.
Remote MCP servers scoped to this agent and inherited by its sessions.
object
Session-, agent-, or harness-scoped remote MCP server configuration.
This intentionally mirrors the mcpServers object shape used by common MCP
client config files while staying within Everruns’ current remote-HTTP-only
support.
object
Identity whose grant this attachment requests.
Arguments passed to the stdio command.
Authentication mode used when executing tools from this scoped server.
Executable to spawn for a stdio transport server.
Whether a missing sign-in may pause the turn with an in-chat Connect
card (ask, the default) or fails the call with a settings link
(never).
Whether the server’s tools are listed only when the model asks for
them through tool search (false, the default, lists them at turn
start).
Searchable server context supplied by its attachment or catalog. It is metadata, not an instruction or a credential.
Which elicitation modes this server may use (url by default).
Environment variables set for the stdio command.
object
Additional HTTP headers sent on MCP requests (HTTP transport only).
object
Provider id used to resolve a user-scoped bearer token.
Protocol-era adoption policy for the MCP client (auto negotiates).
Whether to discover tool definitions live from this server.
Risk labels for this server’s tools, by the tool’s own name:
read_only never asks for approval in the normal mode, changes
always asks. They win over the tool’s annotations and over a catalog
preset’s saved labels. Honored on harness, agent and person-owned
servers; dropped from session-scoped servers.
object
A person’s saved risk label for one MCP tool.
Decision (2026-10-10): a person’s label always wins over the tool’s own
annotations, because a remote server describes itself and a person who
owns the integration knows better. read_only also clears open_world,
since tool approval treats an outward-reaching tool like a destructive one;
without that a read-only MCP tool would still ask every time.
How long one tools/call to this server may take, in milliseconds.
Unset means [MCP_TOOL_TIMEOUT_DEFAULT_MS] (60 s); accepted range is
[MCP_TOOL_TIMEOUT_MIN_MS]..=[MCP_TOOL_TIMEOUT_MAX_MS]. timeout
is accepted as an alias, matching common mcpServers config files.
MCP transport type. Only remote HTTP is supported today.
URL of the remote MCP server endpoint. Required for HTTP transport; empty/ignored for stdio.
Name, unique per org (e.g. “customer-support”).
Network access list controlling which hosts/URLs agent sessions can reach. Merged with harness and session layers (allowed: intersect, blocked: union).
object
Allowed host patterns. If non-empty, only matching URLs are permitted. An empty list means “no restriction from this layer” (inherit parent).
Blocked host patterns. Always denied, even if matched by allowed.
Agent this one was created as part of, shown as “Created here” on that agent’s Agents tab and bundled into its export.
Request-level parallel tool calling preference (EVE-598).
None (default) preserves provider defaults. Some(true) signals the
provider that parallel tool calls are wanted; Some(false) requests at
most one tool call per turn and forces serial execution. Merged across
harness/agent/session layers (overlay wins).
Root agent lineage identifier for grouping fork families.
Policy for selecting the primary Sandbox Template for new Sessions.
object
Template binding inherited when Session creation does not choose one.
Template snapshots addressable by binding name at Session creation.
object
Desired Sandbox configuration authored by a human or application.
Containment and durability may be omitted when the target has exactly one honest answer. Resolution fills those fields before the specification is pinned to a Session.
object
Reproducible commands run when physical compute is initialized.
object
Ordered commands replayed when creating or recovering physical compute.
Requested isolation policy; resolution supplies an honest target default.
object
Whether the runtime may widen containment after Session creation.
Filesystem mutation boundary for command execution.
object
Absolute roots the runtime may mutate; empty means provider default.
Isolation mechanism the provider must supply.
Idle lifecycle policy controlled by Everruns.
object
How long a paused Sandbox is kept, counted from its last activity,
before Everruns deletes it with its files. The Session stays; its next
Sandbox call provisions a fresh one. null keeps paused Sandboxes
until their Session is deleted.
Action Everruns requests after the idle interval.
Inactivity interval before applying idle_action.
Provider-neutral target plus its concrete adapter binding.
object
Credential/transport binding for a registered machine target.
Provider credential source. User and Agent bindings are resolved to an exact virtual user when the Session starts; organization bindings also pin the exact connection.
object
Exact connection for organization grants, which may have several accounts for one provider.
Identity scope from which the provider credential is resolved.
Exact virtual-user owner for user, Agent, and organization grants.
Provider-neutral target class.
Provider-owned, non-secret configuration. Credentials are references, never values in this object.
object
Concrete adapter for target kinds with more than one implementation.
Immutable Sandbox Template revision this specification was copied from. The specification remains complete so Agent snapshots are portable and later template revisions cannot change an existing snapshot.
Org-scoped service account used when a tool acts as the agent.
Optional one-line description in simplified Markdown, shown below the chat title once the intro is hidden. Wins over the harness value.
Conversation starters for a fresh Platform Chat thread. Win over the harness starters when non-empty.
A conversation starter shown on a fresh Platform Chat thread.
Selecting one inserts its text into the composer. icon reuses the
harness icon name set (HarnessIcon); unknown names fall back to the
default glyph.
object
Optional icon name from the harness icon set.
Prompt text inserted into the composer when selected.
Current lifecycle status of the agent.
System prompt that defines the agent’s behavior. Sent as the first message in every conversation.
Tags for organizing and filtering agents.
Client-side tools registered for this agent. These tools are executed by the client, not the server.
Built-in tool - executed by the worker via ToolRegistry
object
Category for tool_search namespace grouping (from parent capability)
Whether this tool’s schema can be deferred via tool_search
Tool description for LLM
Human-readable display name for UI rendering (e.g., “Get Current Time” for get_current_time)
Original full parameter schema saved by DeferSchemaHook before stripping.
Serialized only when present so durable reason-to-act scheduling can
preserve deferred schemas for tool_search in the act phase.
Semantic hints describing the tool’s behavioral properties
object
Declared capability description for source-aware tool discovery. Never populate this with system prompts, conversation state or secrets.
Capability that contributed this tool definition.
Reporting uses this attribution only as metadata. It must never contain tool arguments, results, prompts, or any other sensitive payload.
Human-readable capability name snapshot for reporting.
Scheduling conflict key. Tool calls within the same act batch that share
a non-empty concurrency_class are executed sequentially in arrival
order; calls in different classes (or with no class) run concurrently.
Set this on tools that mutate shared session state so that, e.g., two
file writes or two SQL mutations in one batch do not race. Read-only
tools should leave this None so they always parallelize. See
everruns-engine’s tool scheduler for how the act phase consumes it.
Tool performs significant CPU-bound or otherwise non-yielding work in
process (e.g. an in-process interpreter). When true, the act scheduler
runs the call on its own task (tokio::spawn) so a long CPU burst does
not starve the cooperative polling of I/O-bound tools in the same batch.
Distinct from long_running, which describes wall-clock time for
I/O-bound work (those tools yield at await points and need no offload).
Tool may irreversibly destroy or delete data. Subset of non-readonly — a tool can be non-readonly (writes) without being destructive (e.g., create/update operations).
Calling the tool repeatedly with the same arguments produces the same effect. Safe to retry on transient failures.
Tool may take significant time to complete (> ~5s typical). Useful for clients to show progress indicators and set timeouts.
Host-owned annotations that core does not interpret.
The typed hints above are the vocabulary core itself reasons about. This
is the escape hatch for everything a host wants to carry alongside a
tool — risk tiers for an approval UI, presentation hints, an embedder’s
routing keys — without adding a field to core for each one. Core reads
nothing here and no driver sends it to a provider; it travels with the
definition so a consumer sees it at the point of decision (e.g. a
PreToolUseHook gating on what the tool declared).
The schema belongs to whoever writes it. Never put credentials or other sensitive payload here: like the rest of the definition, it is persisted and surfaced to clients.
Entity noun for operation-based narration (e.g. “agent”, “harness”).
When set, the narration system reads the operation argument and
produces verb-based narration like “Created agent: Neon Cartographer”
instead of the generic “Ran Manage Agents”.
Tool interacts with external entities beyond the local system (network calls, third-party APIs, cloud services).
Tool output should be persisted to session VFS before truncation.
When set, the tool_output_persistence capability (EVE-222, EVE-245) writes
stdout to /outputs/{tool_call_id}.stdout and stderr to
/outputs/{tool_call_id}.stderr, injecting full_output, total_lines,
and output_files into the result.
Tool does not modify any state (read-only queries, lookups). When true: safe to call speculatively, result can be cached.
Tool requires API keys, credentials, or other secrets to function. Useful for UI to show connection prompts and for LLMs to anticipate authentication failures.
Replay-safety class used by the durable Act activity (EVE-530).
Controls what happens when a worker reclaims a stale running claim:
Pure/Idempotent tools are re-executed; AtMostOnce tools are
settled as interrupted to prevent double side-effects.
None is treated conservatively as AtMostOnce.
Tool must stay a direct tool call and never runs from inside a shell
script (tools_in_shell): it pauses or shapes the turn, or its result
only makes sense to the model directly.
Tool supports detached background execution via spawn_background.
When true, the tool may be executed asynchronously outside the current
foreground tool call and report status back later.
Tool name (used by LLM and for registry lookup)
JSON schema for tool parameters
Tool policy (auto or requires_approval)
Client-side tool - executed by the client, not the server
object
Category for tool_search namespace grouping (from parent capability)
Whether this tool’s schema can be deferred via tool_search
Tool description for LLM
Human-readable display name for UI rendering
Original full parameter schema saved by DeferSchemaHook before stripping.
Serialized only when present so durable reason-to-act scheduling can
preserve deferred schemas for tool_search in the act phase.
Semantic hints describing the tool’s behavioral properties
object
Declared capability description for source-aware tool discovery. Never populate this with system prompts, conversation state or secrets.
Capability that contributed this tool definition.
Reporting uses this attribution only as metadata. It must never contain tool arguments, results, prompts, or any other sensitive payload.
Human-readable capability name snapshot for reporting.
Scheduling conflict key. Tool calls within the same act batch that share
a non-empty concurrency_class are executed sequentially in arrival
order; calls in different classes (or with no class) run concurrently.
Set this on tools that mutate shared session state so that, e.g., two
file writes or two SQL mutations in one batch do not race. Read-only
tools should leave this None so they always parallelize. See
everruns-engine’s tool scheduler for how the act phase consumes it.
Tool performs significant CPU-bound or otherwise non-yielding work in
process (e.g. an in-process interpreter). When true, the act scheduler
runs the call on its own task (tokio::spawn) so a long CPU burst does
not starve the cooperative polling of I/O-bound tools in the same batch.
Distinct from long_running, which describes wall-clock time for
I/O-bound work (those tools yield at await points and need no offload).
Tool may irreversibly destroy or delete data. Subset of non-readonly — a tool can be non-readonly (writes) without being destructive (e.g., create/update operations).
Calling the tool repeatedly with the same arguments produces the same effect. Safe to retry on transient failures.
Tool may take significant time to complete (> ~5s typical). Useful for clients to show progress indicators and set timeouts.
Host-owned annotations that core does not interpret.
The typed hints above are the vocabulary core itself reasons about. This
is the escape hatch for everything a host wants to carry alongside a
tool — risk tiers for an approval UI, presentation hints, an embedder’s
routing keys — without adding a field to core for each one. Core reads
nothing here and no driver sends it to a provider; it travels with the
definition so a consumer sees it at the point of decision (e.g. a
PreToolUseHook gating on what the tool declared).
The schema belongs to whoever writes it. Never put credentials or other sensitive payload here: like the rest of the definition, it is persisted and surfaced to clients.
Entity noun for operation-based narration (e.g. “agent”, “harness”).
When set, the narration system reads the operation argument and
produces verb-based narration like “Created agent: Neon Cartographer”
instead of the generic “Ran Manage Agents”.
Tool interacts with external entities beyond the local system (network calls, third-party APIs, cloud services).
Tool output should be persisted to session VFS before truncation.
When set, the tool_output_persistence capability (EVE-222, EVE-245) writes
stdout to /outputs/{tool_call_id}.stdout and stderr to
/outputs/{tool_call_id}.stderr, injecting full_output, total_lines,
and output_files into the result.
Tool does not modify any state (read-only queries, lookups). When true: safe to call speculatively, result can be cached.
Tool requires API keys, credentials, or other secrets to function. Useful for UI to show connection prompts and for LLMs to anticipate authentication failures.
Replay-safety class used by the durable Act activity (EVE-530).
Controls what happens when a worker reclaims a stale running claim:
Pure/Idempotent tools are re-executed; AtMostOnce tools are
settled as interrupted to prevent double side-effects.
None is treated conservatively as AtMostOnce.
Tool must stay a direct tool call and never runs from inside a shell
script (tools_in_shell): it pauses or shapes the turn, or its result
only makes sense to the model directly.
Tool supports detached background execution via spawn_background.
When true, the tool may be executed asynchronously outside the current
foreground tool call and report status back later.
Tool name (used by LLM and for correlation)
JSON schema for tool parameters
Timestamp when the agent was last updated.
Cumulative token usage across all sessions for this agent.
object
Actual cost of this generation in USD, as reported by the provider inline
(e.g. OpenRouter’s usage.cost, which reflects real post-routing/BYOK/cache
pricing). None for providers that do not return a cost.
Number of tokens written to cache, disjoint from input_tokens
Number of tokens read from cache (reduces cost), disjoint from input_tokens
Best-effort USD cost when it cannot be derived from actual/estimated alone: already-aggregated usage, or a generation carrying a cost that belongs to neither slot. Per-generation usage normally leaves this unset and derives the effective cost from actual-else-estimated; the exception is a turn whose compaction cost is folded in, where the combined total has to live here precisely so the generation’s own actual-vs-estimated distinction survives (EVE-895).
Estimated cost of this generation in USD, derived from the model’s static
price-table profile. Computed whenever a profile with cost data exists,
independently of actual_cost_usd, so estimate-vs-actual drift can be
reconciled. None when there is no profile cost data for the model.
Number of non-cached prompt tokens (cached reads/writes are tracked separately; see the disjoint bucket convention on the struct)
Number of output/completion tokens
State-aware hypermedia actions the caller can take on this resource
next (e.g. cancel, events, update). Omitted from the wire
shape when empty so resources that haven’t opted into the
convention don’t grow their payloads.
Agent-actionable link describing a follow-up the caller can take. Used in two contexts:
- Error recovery —
ErrorResponse.allowed_actionscarriesrels likeretry,retry-later,unarchive,get-existingso the agent knows the right next call after a 4xx/429. - Entity hypermedia —
WithUrls<T>.allowed_actionscarries state-awarerels likecancel,events,self,updateon the entity itself so the agent can follow links instead of reconstructing routes from prose.
The shape is intentionally identical across both contexts; the closed
rel vocabulary distinguishes them.
object
Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).
Absolute (preferred) or relative URL the caller may invoke
directly. Always present on entity hypermedia actions
(WithUrls<T>.allowed_actions); optional on error-recovery
actions (ErrorResponse.allowed_actions) where the matching
operation_id is enough and the URI is implicit from the failed
call.
HTTP method to use against href. Required for entity hypermedia
actions; usually omitted on error-recovery actions where the same
operation is retried with its original method.
OpenAPI operationId the caller should invoke. Lets an MCP client
resolve the call without parsing href.
Link relation describing the action. Examples: self, cancel, pause,
resume, events, retry, retry-later, unarchive,
get-existing, delete, update.
OpenAPI $ref to the request-body schema, when the action takes one
(e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling
agent fetch the input shape without scanning the whole spec.
Full API endpoint URL for this resource.
Alias for view_url, used by command and MCP outputs.
Full UI URL for viewing this resource.
Example
{ "archived_at": "2026-05-26T00:00:00Z", "avatar": { "circle_url": "/v1/avatars/avatar_01933b5a000070008000000000000001/circle-256.png", "id": "avatar_01933b5a000070008000000000000001", "sizes": [ 32, 64, 128, 256, 512 ], "url": "/v1/avatars/avatar_01933b5a000070008000000000000001/square-256.png" }, "communication": "direct", "completion_check": "off", "created_at": "2026-04-01T10:00:00Z", "default_model_id": "model_01933b5a00007000800000000000001", "deleted_at": "2026-05-26T00:00:00Z", "description": "Handles refund and shipping questions; escalates billing disputes.", "display_name": "Customer Support Agent", "forked_from_agent_id": "agent_01933b5a00007000800000000000001", "harness_id": "harness_01933b5a00007000800000000000001", "id": "agent_01933b5a000070008000000000000001", "intro_markdown": "Hey, I'm Ava. Ask me anything about your account.", "is_built_in": false, "max_iterations": 50, "max_output_tokens": 4096, "mcpServers": { "additionalProperty": { "actsAs": "none", "auth_mode": "none", "connectInChat": "ask", "elicitation_policy": "url", "protocol_mode": "auto", "tool_labels": { "additionalProperty": "read_only" }, "type": "http", "use": "catalog:linear" } }, "model_role": "research", "name": "customer-support", "network_access": { "allowed": [ "*.example.com", "https://api.acme.com/" ], "blocked": [ "169.254.169.254" ] }, "owner_agent_id": "agent_01933b5a00007000800000000000001", "parallel_tool_calls": true, "root_agent_id": "agent_01933b5a00007000800000000000001", "sandbox_policy": { "default": "primary", "mode": "fixed", "templates": { "additionalProperty": { "containment": { "escalation": "never", "level": "none", "network": { "mode": "deny" } }, "durability": "checkpointed", "lifecycle": { "delete_after_seconds": 259200, "idle_action": "checkpoint_and_stop", "idle_after_seconds": 300 }, "target": { "connection_id": "conn_01933b5a000070008000000000000001", "credential": { "connection_id": "00000000-0000-0000-0000-000000000002", "source": "none", "virtual_user_id": "00000000-0000-0000-0000-000000000001" }, "kind": "host", "provider": "daytona" } } } }, "short_description": "Answers account questions in seconds.", "starters": [ { "icon": "zap", "text": "Triage the newest P1" } ], "status": "active", "system_prompt": "You are a friendly customer support agent for Acme Corp. Verify orders before issuing refunds. Escalate any billing disputes to a human.", "tags": [ "support", "production" ], "tools": [ { "deferrable": "never", "hints": { "side_effect_class": "Pure" }, "policy": "auto", "type": "builtin" } ], "updated_at": "2026-05-20T14:00:00Z", "allowed_actions": [ { "method": "POST" } ]}400Invalid format or input exceeds limits
Invalid format or input exceeds limits
Standard error response.
Wire shape is RFC 9457 Problem Details:
every error response includes title and status, and may include
detail, code, allowed_actions, retry_after_seconds, instance,
and type. The content type is rewritten to application/problem+json
with the application/problem+json content type.
object
Recovery actions the caller can take next.
Agent-actionable link describing a follow-up the caller can take. Used in two contexts:
- Error recovery —
ErrorResponse.allowed_actionscarriesrels likeretry,retry-later,unarchive,get-existingso the agent knows the right next call after a 4xx/429. - Entity hypermedia —
WithUrls<T>.allowed_actionscarries state-awarerels likecancel,events,self,updateon the entity itself so the agent can follow links instead of reconstructing routes from prose.
The shape is intentionally identical across both contexts; the closed
rel vocabulary distinguishes them.
object
Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).
Absolute (preferred) or relative URL the caller may invoke
directly. Always present on entity hypermedia actions
(WithUrls<T>.allowed_actions); optional on error-recovery
actions (ErrorResponse.allowed_actions) where the matching
operation_id is enough and the URI is implicit from the failed
call.
HTTP method to use against href. Required for entity hypermedia
actions; usually omitted on error-recovery actions where the same
operation is retried with its original method.
OpenAPI operationId the caller should invoke. Lets an MCP client
resolve the call without parsing href.
Link relation describing the action. Examples: self, cancel, pause,
resume, events, retry, retry-later, unarchive,
get-existing, delete, update.
OpenAPI $ref to the request-body schema, when the action takes one
(e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling
agent fetch the input shape without scanning the whole spec.
Stable, machine-readable error code (snake_case).
Human-readable explanation specific to this occurrence.
Request URI for this occurrence.
Seconds the caller should wait before retrying (429 / transient 503).
HTTP status code; mirrors the response status line.
Short, human-readable summary of the problem (e.g. “Not Found”).
RFC 9457 problem type URI. Optional; identifies the problem class.
Example
{ "allowed_actions": [ { "method": "POST" } ], "code": "session_not_found", "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.", "instance": "/v1/sessions/session_01933b5a000070008000000000000001", "retry_after_seconds": 30, "status": 404, "title": "Session not found", "type": "https://everruns.com/docs/errors/session_not_found"}403High-risk capabilities require admin role
High-risk capabilities require admin role
Standard error response.
Wire shape is RFC 9457 Problem Details:
every error response includes title and status, and may include
detail, code, allowed_actions, retry_after_seconds, instance,
and type. The content type is rewritten to application/problem+json
with the application/problem+json content type.
object
Recovery actions the caller can take next.
Agent-actionable link describing a follow-up the caller can take. Used in two contexts:
- Error recovery —
ErrorResponse.allowed_actionscarriesrels likeretry,retry-later,unarchive,get-existingso the agent knows the right next call after a 4xx/429. - Entity hypermedia —
WithUrls<T>.allowed_actionscarries state-awarerels likecancel,events,self,updateon the entity itself so the agent can follow links instead of reconstructing routes from prose.
The shape is intentionally identical across both contexts; the closed
rel vocabulary distinguishes them.
object
Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).
Absolute (preferred) or relative URL the caller may invoke
directly. Always present on entity hypermedia actions
(WithUrls<T>.allowed_actions); optional on error-recovery
actions (ErrorResponse.allowed_actions) where the matching
operation_id is enough and the URI is implicit from the failed
call.
HTTP method to use against href. Required for entity hypermedia
actions; usually omitted on error-recovery actions where the same
operation is retried with its original method.
OpenAPI operationId the caller should invoke. Lets an MCP client
resolve the call without parsing href.
Link relation describing the action. Examples: self, cancel, pause,
resume, events, retry, retry-later, unarchive,
get-existing, delete, update.
OpenAPI $ref to the request-body schema, when the action takes one
(e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling
agent fetch the input shape without scanning the whole spec.
Stable, machine-readable error code (snake_case).
Human-readable explanation specific to this occurrence.
Request URI for this occurrence.
Seconds the caller should wait before retrying (429 / transient 503).
HTTP status code; mirrors the response status line.
Short, human-readable summary of the problem (e.g. “Not Found”).
RFC 9457 problem type URI. Optional; identifies the problem class.
Example
{ "allowed_actions": [ { "method": "POST" } ], "code": "session_not_found", "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.", "instance": "/v1/sessions/session_01933b5a000070008000000000000001", "retry_after_seconds": 30, "status": 404, "title": "Session not found", "type": "https://everruns.com/docs/errors/session_not_found"}404Example not found
Example not found
Standard error response.
Wire shape is RFC 9457 Problem Details:
every error response includes title and status, and may include
detail, code, allowed_actions, retry_after_seconds, instance,
and type. The content type is rewritten to application/problem+json
with the application/problem+json content type.
object
Recovery actions the caller can take next.
Agent-actionable link describing a follow-up the caller can take. Used in two contexts:
- Error recovery —
ErrorResponse.allowed_actionscarriesrels likeretry,retry-later,unarchive,get-existingso the agent knows the right next call after a 4xx/429. - Entity hypermedia —
WithUrls<T>.allowed_actionscarries state-awarerels likecancel,events,self,updateon the entity itself so the agent can follow links instead of reconstructing routes from prose.
The shape is intentionally identical across both contexts; the closed
rel vocabulary distinguishes them.
object
Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).
Absolute (preferred) or relative URL the caller may invoke
directly. Always present on entity hypermedia actions
(WithUrls<T>.allowed_actions); optional on error-recovery
actions (ErrorResponse.allowed_actions) where the matching
operation_id is enough and the URI is implicit from the failed
call.
HTTP method to use against href. Required for entity hypermedia
actions; usually omitted on error-recovery actions where the same
operation is retried with its original method.
OpenAPI operationId the caller should invoke. Lets an MCP client
resolve the call without parsing href.
Link relation describing the action. Examples: self, cancel, pause,
resume, events, retry, retry-later, unarchive,
get-existing, delete, update.
OpenAPI $ref to the request-body schema, when the action takes one
(e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling
agent fetch the input shape without scanning the whole spec.
Stable, machine-readable error code (snake_case).
Human-readable explanation specific to this occurrence.
Request URI for this occurrence.
Seconds the caller should wait before retrying (429 / transient 503).
HTTP status code; mirrors the response status line.
Short, human-readable summary of the problem (e.g. “Not Found”).
RFC 9457 problem type URI. Optional; identifies the problem class.
Example
{ "allowed_actions": [ { "method": "POST" } ], "code": "session_not_found", "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.", "instance": "/v1/sessions/session_01933b5a000070008000000000000001", "retry_after_seconds": 30, "status": 404, "title": "Session not found", "type": "https://everruns.com/docs/errors/session_not_found"}500Internal server error
Internal server error
Standard error response.
Wire shape is RFC 9457 Problem Details:
every error response includes title and status, and may include
detail, code, allowed_actions, retry_after_seconds, instance,
and type. The content type is rewritten to application/problem+json
with the application/problem+json content type.
object
Recovery actions the caller can take next.
Agent-actionable link describing a follow-up the caller can take. Used in two contexts:
- Error recovery —
ErrorResponse.allowed_actionscarriesrels likeretry,retry-later,unarchive,get-existingso the agent knows the right next call after a 4xx/429. - Entity hypermedia —
WithUrls<T>.allowed_actionscarries state-awarerels likecancel,events,self,updateon the entity itself so the agent can follow links instead of reconstructing routes from prose.
The shape is intentionally identical across both contexts; the closed
rel vocabulary distinguishes them.
object
Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).
Absolute (preferred) or relative URL the caller may invoke
directly. Always present on entity hypermedia actions
(WithUrls<T>.allowed_actions); optional on error-recovery
actions (ErrorResponse.allowed_actions) where the matching
operation_id is enough and the URI is implicit from the failed
call.
HTTP method to use against href. Required for entity hypermedia
actions; usually omitted on error-recovery actions where the same
operation is retried with its original method.
OpenAPI operationId the caller should invoke. Lets an MCP client
resolve the call without parsing href.
Link relation describing the action. Examples: self, cancel, pause,
resume, events, retry, retry-later, unarchive,
get-existing, delete, update.
OpenAPI $ref to the request-body schema, when the action takes one
(e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling
agent fetch the input shape without scanning the whole spec.
Stable, machine-readable error code (snake_case).
Human-readable explanation specific to this occurrence.
Request URI for this occurrence.
Seconds the caller should wait before retrying (429 / transient 503).
HTTP status code; mirrors the response status line.
Short, human-readable summary of the problem (e.g. “Not Found”).
RFC 9457 problem type URI. Optional; identifies the problem class.
Example
{ "allowed_actions": [ { "method": "POST" } ], "code": "session_not_found", "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.", "instance": "/v1/sessions/session_01933b5a000070008000000000000001", "retry_after_seconds": 30, "status": 404, "title": "Session not found", "type": "https://everruns.com/docs/errors/session_not_found"}