Create or update agent (upsert)
const url = 'https://app.everruns.com/api/v1/agents/example';const options = { method: 'PUT', headers: {'Content-Type': 'application/json'}, body: '{"capabilities":[{"config":{},"ref":"current_time"},{"config":{},"ref":"web_fetch"}],"default_model_id":"model_01933b5a00007000800000000000001","description":"Handles customer inquiries and support tickets","display_name":"Customer Support Agent","id":"agent_01933b5a00007000800000000000001","initial_files":[{"content":"Always respond in formal English.\n","path":"INSTRUCTIONS.md"}],"max_iterations":20,"mcpServers":{"additionalProperty":{"args":["example"],"auth_mode":"none","command":"example","env":{"additionalProperty":"example"},"headers":{"additionalProperty":"example"},"oauth_provider_id":"example","tool_discovery":true,"type":"http","url":"example"}},"name":"customer-support","network_access":{"allowed":["*.example.com","https://api.acme.com/"],"blocked":["169.254.169.254"]},"system_prompt":"You are a helpful customer support agent. Be polite and professional.","tags":["support","customer-facing"],"tools":[{"description":"Open URL in the user\'s browser","name":"open_url","parameters":{"properties":{"url":{"type":"string"}},"required":["url"],"type":"object"},"type":"client_side"}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --url https://app.everruns.com/api/v1/agents/example \ --header 'Content-Type: application/json' \ --data '{ "capabilities": [ { "config": {}, "ref": "current_time" }, { "config": {}, "ref": "web_fetch" } ], "default_model_id": "model_01933b5a00007000800000000000001", "description": "Handles customer inquiries and support tickets", "display_name": "Customer Support Agent", "id": "agent_01933b5a00007000800000000000001", "initial_files": [ { "content": "Always respond in formal English.\n", "path": "INSTRUCTIONS.md" } ], "max_iterations": 20, "mcpServers": { "additionalProperty": { "args": [ "example" ], "auth_mode": "none", "command": "example", "env": { "additionalProperty": "example" }, "headers": { "additionalProperty": "example" }, "oauth_provider_id": "example", "tool_discovery": true, "type": "http", "url": "example" } }, "name": "customer-support", "network_access": { "allowed": [ "*.example.com", "https://api.acme.com/" ], "blocked": [ "169.254.169.254" ] }, "system_prompt": "You are a helpful customer support agent. Be polite and professional.", "tags": [ "support", "customer-facing" ], "tools": [ { "description": "Open URL in the user'\''s browser", "name": "open_url", "parameters": { "properties": { "url": { "type": "string" } }, "required": [ "url" ], "type": "object" }, "type": "client_side" } ] }'Accepts either an agent ID (e.g. agent_01933b5a...) or a
name (e.g. customer-support). If the agent exists, update it; if not,
create it. Returns 201 on create, 200 on update.
Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Agent ID (prefixed) or name
Request Body required
Section titled “Request Body required ”Request to create a new agent
object
Capabilities to enable for this agent with per-agent configuration.
Each capability has a ref (capability ID) and optional config.
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
Example
[ { "config": {}, "ref": "current_time" }, { "config": {}, "ref": "web_fetch" }]The ID of the default LLM model to use for this agent. If not specified, the system default model will be used.
Example
model_01933b5a00007000800000000000001A human-readable description of what the agent does.
Example
Handles customer inquiries and support ticketsHuman-readable display name shown in UI.
Falls back to name when absent.
Example
Customer Support AgentClient-supplied agent ID (format: agent_{32-hex}). If not provided, one is auto-generated.
Example
agent_01933b5a00007000800000000000001Starter 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.
Example
[ { "content": "Always respond in formal English.\n", "path": "INSTRUCTIONS.md" }]Maximum number of LLM iterations per turn for this agent.
Example
20Remote MCP servers scoped to this agent.
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
Arguments passed to the stdio command.
Authentication mode used when executing tools from this scoped server.
Example
api_keyExecutable to spawn for a stdio transport server.
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.
Whether to discover tool definitions live from this server.
MCP transport type. Only remote HTTP is supported today.
Example
httpURL of the remote MCP server endpoint. Required for HTTP transport; empty/ignored for stdio.
Name, unique per org. Lowercase alphanumeric and hyphens. Format: lowercase alphanumeric and hyphens (e.g. “customer-support”).
Example
customer-supportNetwork access list controlling which hosts/URLs this agent’s sessions can reach.
If set, merged with harness and session layers (allowed: intersect, blocked: union).
Example shape is defined on NetworkAccessList.
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.
Example
{ "allowed": [ "*.example.com", "https://api.acme.com/" ], "blocked": [ "169.254.169.254" ]}The system prompt that defines the agent’s behavior and capabilities. This is sent as the first message in every conversation.
Example
You are a helpful customer support agent. Be polite and professional.Tags for organizing and filtering agents.
Example
[ "support", "customer-facing"]Client-side tools for this agent. These tools are sent to the LLM but 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)
Semantic hints describing the tool’s behavioral properties
object
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
crate::atoms::tool_scheduler for how the act scheduler 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.
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.
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
Semantic hints describing the tool’s behavioral properties
object
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
crate::atoms::tool_scheduler for how the act scheduler 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.
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.
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
Example
[ { "description": "Open URL in the user's browser", "name": "open_url", "parameters": { "properties": { "url": { "type": "string" } }, "required": [ "url" ], "type": "object" }, "type": "client_side" }]Responses
Section titled “ Responses ”Agent updated
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.
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
Timestamp when the agent was created.
Default LLM model ID for this agent. Can be overridden at the session level.
Default immutable version used by deployments that choose the default policy.
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.
Source agent for a forked agent.
Source version for a forked 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.
Maximum number of LLM iterations per turn for this agent.
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
Arguments passed to the stdio command.
Authentication mode used when executing tools from this scoped server.
Executable to spawn for a stdio transport server.
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.
Whether to discover tool definitions live from this server.
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.
Root agent lineage identifier for grouping fork families.
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)
Semantic hints describing the tool’s behavioral properties
object
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
crate::atoms::tool_scheduler for how the act scheduler 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.
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.
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
Semantic hints describing the tool’s behavioral properties
object
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
crate::atoms::tool_scheduler for how the act scheduler 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.
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.
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 (Anthropic-specific)
Number of tokens read from cache (reduces cost)
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 input/prompt tokens
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 documented in specs/api-conventions.md 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. Closed vocabulary documented
in specs/api-conventions.md — 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", "created_at": "2026-04-01T10:00:00Z", "default_model_id": "model_01933b5a00007000800000000000001", "default_version_id": "agentver_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", "forked_from_version_id": "agentver_01933b5a00007000800000000000001", "id": "agent_01933b5a000070008000000000000001", "max_iterations": 50, "mcpServers": { "additionalProperty": { "auth_mode": "none", "type": "http" } }, "name": "customer-support", "network_access": { "allowed": [ "*.example.com", "https://api.acme.com/" ], "blocked": [ "169.254.169.254" ] }, "root_agent_id": "agent_01933b5a00007000800000000000001", "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", "policy": "auto", "type": "builtin" } ], "updated_at": "2026-05-20T14:00:00Z", "allowed_actions": [ { "method": "POST" } ]}Agent created
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.
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
Timestamp when the agent was created.
Default LLM model ID for this agent. Can be overridden at the session level.
Default immutable version used by deployments that choose the default policy.
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.
Source agent for a forked agent.
Source version for a forked 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.
Maximum number of LLM iterations per turn for this agent.
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
Arguments passed to the stdio command.
Authentication mode used when executing tools from this scoped server.
Executable to spawn for a stdio transport server.
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.
Whether to discover tool definitions live from this server.
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.
Root agent lineage identifier for grouping fork families.
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)
Semantic hints describing the tool’s behavioral properties
object
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
crate::atoms::tool_scheduler for how the act scheduler 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.
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.
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
Semantic hints describing the tool’s behavioral properties
object
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
crate::atoms::tool_scheduler for how the act scheduler 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.
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.
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 (Anthropic-specific)
Number of tokens read from cache (reduces cost)
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 input/prompt tokens
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 documented in specs/api-conventions.md 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. Closed vocabulary documented
in specs/api-conventions.md — 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", "created_at": "2026-04-01T10:00:00Z", "default_model_id": "model_01933b5a00007000800000000000001", "default_version_id": "agentver_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", "forked_from_version_id": "agentver_01933b5a00007000800000000000001", "id": "agent_01933b5a000070008000000000000001", "max_iterations": 50, "mcpServers": { "additionalProperty": { "auth_mode": "none", "type": "http" } }, "name": "customer-support", "network_access": { "allowed": [ "*.example.com", "https://api.acme.com/" ], "blocked": [ "169.254.169.254" ] }, "root_agent_id": "agent_01933b5a00007000800000000000001", "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", "policy": "auto", "type": "builtin" } ], "updated_at": "2026-05-20T14:00:00Z", "allowed_actions": [ { "method": "POST" } ]}Invalid input
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
by [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 documented in specs/api-conventions.md 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. Closed vocabulary documented
in specs/api-conventions.md — 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://docs.everruns.com/errors/session_not_found"}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
by [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 documented in specs/api-conventions.md 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. Closed vocabulary documented
in specs/api-conventions.md — 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://docs.everruns.com/errors/session_not_found"}