# PATCH /v1/agents/{agent_id} - Update agent

Source: <https://everruns.com/docs/api/operations/update_agent/>

PATCH

/v1/agents/{agent\_id}

Select code samplecURL (shell:curl)

```js
const url = 'https://app.everruns.com/api/v1/agents/example';
const options = {
  method: 'PATCH',
  headers: {'Content-Type': 'application/json'},
  body: '{"capabilities":[{"config":{},"ref":"current_time"},{"config":{},"ref":"web_fetch"}],"communication":"direct","default_model_id":"model_01933b5a00007000800000000000001","description":"Updated description for the agent","display_name":"Updated Support Agent","harness_id":"harness_01933b5a00007000800000000000001","harness_name":"conversation","initial_files":[{"content":"Always respond in formal English.\n","path":"INSTRUCTIONS.md"}],"intro_markdown":"Hey, I\'m Ava. Ask me anything about your account.","max_iterations":20,"mcpServers":{"additionalProperty":{"actsAs":"none","args":["example"],"auth_mode":"none","command":"example","connectInChat":"ask","deferred":true,"elicitation_policy":"url","env":{"additionalProperty":"example"},"headers":{"additionalProperty":"example"},"oauth_provider_id":"example","protocol_mode":"auto","tool_discovery":true,"tool_labels":{"additionalProperty":"read_only"},"type":"http","url":"example","use":"catalog:linear"}},"name":"updated-support","network_access":{"allowed":["*.example.com","https://api.acme.com/"],"blocked":["169.254.169.254"]},"parallel_tool_calls":true,"sandbox_policy":{"default":"primary","mode":"fixed","templates":{"additionalProperty":{"bootstrap":{"commands":["example"]},"containment":{"escalation":"never","filesystem":{"writable_roots":["example"]},"level":"none","network":{"mode":"deny"}},"durability":"checkpointed","lifecycle":{"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","options":{},"provider":"daytona"},"template_revision_id":"example"}}},"service_virtual_user_id":"example","short_description":"Answers account questions in seconds.","starters":[{"text":"Who does the dishes today?"}],"status":"active","system_prompt":"You are an updated helpful assistant.","tags":["updated-tag"],"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);
}
```

```sh
curl --request PATCH \
  --url https://app.everruns.com/api/v1/agents/example \
  --header 'Content-Type: application/json' \
  --data '{ "capabilities": [ { "config": {}, "ref": "current_time" }, { "config": {}, "ref": "web_fetch" } ], "communication": "direct", "default_model_id": "model_01933b5a00007000800000000000001", "description": "Updated description for the agent", "display_name": "Updated Support Agent", "harness_id": "harness_01933b5a00007000800000000000001", "harness_name": "conversation", "initial_files": [ { "content": "Always respond in formal English.\n", "path": "INSTRUCTIONS.md" } ], "intro_markdown": "Hey, I'\''m Ava. Ask me anything about your account.", "max_iterations": 20, "mcpServers": { "additionalProperty": { "actsAs": "none", "args": [ "example" ], "auth_mode": "none", "command": "example", "connectInChat": "ask", "deferred": true, "elicitation_policy": "url", "env": { "additionalProperty": "example" }, "headers": { "additionalProperty": "example" }, "oauth_provider_id": "example", "protocol_mode": "auto", "tool_discovery": true, "tool_labels": { "additionalProperty": "read_only" }, "type": "http", "url": "example", "use": "catalog:linear" } }, "name": "updated-support", "network_access": { "allowed": [ "*.example.com", "https://api.acme.com/" ], "blocked": [ "169.254.169.254" ] }, "parallel_tool_calls": true, "sandbox_policy": { "default": "primary", "mode": "fixed", "templates": { "additionalProperty": { "bootstrap": { "commands": [ "example" ] }, "containment": { "escalation": "never", "filesystem": { "writable_roots": [ "example" ] }, "level": "none", "network": { "mode": "deny" } }, "durability": "checkpointed", "lifecycle": { "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", "options": {}, "provider": "daytona" }, "template_revision_id": "example" } } }, "service_virtual_user_id": "example", "short_description": "Answers account questions in seconds.", "starters": [ { "text": "Who does the dishes today?" } ], "status": "active", "system_prompt": "You are an updated helpful assistant.", "tags": [ "updated-tag" ], "tools": [ { "description": "Open URL in the user'\''s browser", "name": "open_url", "parameters": { "properties": { "url": { "type": "string" } }, "required": [ "url" ], "type": "object" }, "type": "client_side" } ] }'
```

* Production APIapp.everruns.com/api/v1/agents/{agent\_id}

## Parameters

### Path Parameters

**agent\_id**

required

string

Agent ID (prefixed, e.g., agt\_…)

## Request Bodyrequired

Media typeapplication/json

Request to update an agent. Only provided fields will be updated.

object

**capabilities**

Capabilities to enable for this agent with per-agent configuration. Replaces existing capabilities. Each has a `ref` (capability ID) and optional `config`.

Array\<object> | null

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

**config**

Per-agent configuration for this capability (capability-specific)

**ref**

required

Reference to the capability ID

string

##### Example

```json
[
  {
    "config": {},
    "ref": "current_time"
  },
  {
    "config": {},
    "ref": "web_fetch"
  }
]
```

**communication**

One of:

* string

  How the agent talks to people: `direct` or `explicit`. Omit to leave unchanged.

  string

  Allowed values: direct explicit

* null

  null

**default\_model\_id**

The ID of the default LLM model to use for this agent.

string | null

##### Example

```plaintext
model_01933b5a00007000800000000000001
```

**description**

A human-readable description of what the agent does.

string | null

##### Example

```plaintext
Updated description for the agent
```

**display\_name**

Human-readable display name shown in UI.

string | null

##### Example

```plaintext
Updated Support Agent
```

**harness\_id**

Harness ID used as this agent’s base execution environment. Omit to leave unchanged.

string | null

##### Example

```plaintext
harness_01933b5a00007000800000000000001
```

**harness\_name**

Addressable harness name. Alternative to `harness_id`; omit to leave unchanged.

string | null

##### Example

```plaintext
conversation
```

**initial\_files**

Starter files copied into each new session for this agent.

Array\<object> | null

Starter file copied into a new session from an agent or harness.

object

**content**

required

File content: plain text or base64-encoded binary.

string

**encoding**

Content encoding: `text` or `base64`.

string

**is\_readonly**

Prevent session-side edits or deletes when true.

boolean

**path**

required

Absolute path within the session workspace. `/workspace` prefix is accepted.

string

##### Example

```json
[
  {
    "content": "Always respond in formal English.\n",
    "path": "INSTRUCTIONS.md"
  }
]
```

**intro\_markdown**

Markdown intro for fresh Platform Chat threads. Outer `None` leaves unchanged; inner `None` clears.

string | null

##### Example

```plaintext
Hey, I'm Ava. Ask me anything about your account.
```

**max\_iterations**

Maximum number of LLM iterations per turn for this agent.

integer | null

##### Example

```json
20
```

**mcpServers**

One of:

* object

  Remote MCP servers scoped to this agent.

  object

  ***key***

  additional properties

  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

  **actsAs**

  Identity whose grant this attachment requests.

  string

  Allowed values: none service user user\_or\_service

  ##### Example

  ```plaintext
  service
  ```

  **args**

  Arguments passed to the stdio `command`.

  Array\<string>

  **auth\_mode**

  Authentication mode used when executing tools from this scoped server.

  string

  Allowed values: none api\_key oauth

  ##### Example

  ```plaintext
  api_key
  ```

  **command**

  Executable to spawn for a stdio transport server.

  string | null

  **connectInChat**

  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`).

  string

  Allowed values: ask never

  ##### Example

  ```plaintext
  ask
  ```

  **deferred**

  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).

  boolean

  **elicitation\_policy**

  Which elicitation modes this server may use (`url` by default).

  string

  Allowed values: url url\_and\_form none

  ##### Example

  ```plaintext
  url
  ```

  **env**

  Environment variables set for the stdio `command`.

  object

  ***key***

  additional properties

  string

  **headers**

  Additional HTTP headers sent on MCP requests (HTTP transport only).

  object

  ***key***

  additional properties

  string

  **oauth\_provider\_id**

  Provider id used to resolve a user-scoped bearer token.

  string | null

  **protocol\_mode**

  Protocol-era adoption policy for the MCP client (`auto` negotiates).

  string

  Allowed values: auto 2025-03-26 2025-06-18 2026-07-28

  ##### Example

  ```plaintext
  auto
  ```

  **tool\_discovery**

  Whether to discover tool definitions live from this server.

  boolean

  **tool\_labels**

  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

  ***key***

  additional properties

  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.

  string

  Allowed values: read\_only changes

  **type**

  MCP transport type. Only remote HTTP is supported today.

  string

  Allowed values: http stdio

  ##### Example

  ```plaintext
  http
  ```

  **url**

  URL of the remote MCP server endpoint. Required for HTTP transport; empty/ignored for stdio.

  string

  **use**

  One of:

  * string

    Organization catalog preset that supplies transport and authentication policy.

    string

    ##### Example

    ```plaintext
    catalog:linear
    ```

  * null

    null

* null

  Organization catalog preset that supplies transport and authentication policy.

  string

  ##### Example

  ```plaintext
  catalog:linear
  ```

* string

  null

* null

  null

**name**

Name, unique per org. Lowercase alphanumeric and hyphens.

string | null

##### Example

```plaintext
updated-support
```

**network\_access**

One of:

* object

  Network access list controlling which hosts/URLs this agent’s sessions can reach. Send `{}` (empty object) to clear restrictions. Omit to leave unchanged. Example shape is defined on `NetworkAccessList`.

  object

  **allowed**

  Allowed host patterns. If non-empty, only matching URLs are permitted. An empty list means “no restriction from this layer” (inherit parent).

  Array\<string>

  **blocked**

  Blocked host patterns. Always denied, even if matched by `allowed`.

  Array\<string>

  ##### Example

  ```json
  {
    "allowed": [
      "*.example.com",
      "https://api.acme.com/"
    ],
    "blocked": [
      "169.254.169.254"
    ]
  }
  ```

* null

  null

**parallel\_tool\_calls**

Request-level parallel tool calling preference (EVE-598). `true` signals the provider that parallel tool calls are wanted; `false` requests at most one tool call per turn and forces serial execution. Omit to leave unchanged.

boolean | null

##### Example

```json
true
```

**sandbox\_policy**

One of:

* object

  Replace or clear the Agent’s Sandbox policy.

  object

  **default**

  required

  Template binding inherited when Session creation does not choose one.

  string

  ##### Example

  ```plaintext
  primary
  ```

  **mode**

  One of:

  * string

    Who may choose the primary Sandbox for a Session. Older rows omit this field; one template then means `fixed`, while several mean `selectable`.

    string

    Allowed values: fixed selectable configurable

  * null

    null

  **templates**

  Template snapshots addressable by binding name at Session creation.

  object

  ***key***

  additional properties

  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

  **bootstrap**

  Reproducible commands run when physical compute is initialized.

  object

  **commands**

  Ordered commands replayed when creating or recovering physical compute.

  Array\<string>

  **containment**

  One of:

  * object

    Requested isolation policy; resolution supplies an honest target default.

    object

    **escalation**

    Whether the runtime may widen containment after Session creation.

    string

    Allowed values: never approval auto

    **filesystem**

    Filesystem mutation boundary for command execution.

    object

    **writable\_roots**

    Absolute roots the runtime may mutate; empty means provider default.

    Array\<string>

    **level**

    required

    Isolation mechanism the provider must supply.

    string

    Allowed values: none native isolated

    **network**

    One of:

    * object

      object

      **mode**

      required

      string

      Allowed values: deny

    * object

      object

      **allowed\_hosts**

      required

      Array\<string>

      **mode**

      required

      string

      Allowed values: allowlist

    * object

      object

      **mode**

      required

      string

      Allowed values: allow

  * null

    object

    **mode**

    required

    string

    Allowed values: deny

  * object

    object

    **allowed\_hosts**

    required

    Array\<string>

    **mode**

    required

    string

    Allowed values: allowlist

  * object

    object

    **mode**

    required

    string

    Allowed values: allow

  * object

    null

  **durability**

  One of:

  * string

    Requested recovery guarantee; resolution supplies a target default.

    string

    Allowed values: checkpointed provider\_snapshot none

  * null

    null

  **lifecycle**

  Idle lifecycle policy controlled by Everruns.

  object

  **idle\_action**

  Action Everruns requests after the idle interval.

  string

  Allowed values: checkpoint\_and\_stop stop keep\_running

  **idle\_after\_seconds**

  Inactivity interval before applying `idle_action`.

  integer format: int64

  ##### Example

  ```json
  300
  ```

  **target**

  required

  Provider-neutral target plus its concrete adapter binding.

  object

  **connection\_id**

  Credential/transport binding for a registered machine target.

  string | null

  ##### Example

  ```plaintext
  conn_01933b5a000070008000000000000001
  ```

  **credential**

  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

  **connection\_id**

  Exact connection for organization grants, which may have several accounts for one provider.

  string | null format: uuid

  ##### Example

  ```plaintext
  00000000-0000-0000-0000-000000000002
  ```

  **source**

  required

  Identity scope from which the provider credential is resolved.

  string

  Allowed values: none session\_user agent organization

  **virtual\_user\_id**

  Exact virtual-user owner for user, Agent, and organization grants.

  string | null format: uuid

  ##### Example

  ```plaintext
  00000000-0000-0000-0000-000000000001
  ```

  **kind**

  required

  Provider-neutral target class.

  string

  Allowed values: host machine vfs container managed

  **options**

  Provider-owned, non-secret configuration. Credentials are references, never values in this object.

  object

  **provider**

  Concrete adapter for target kinds with more than one implementation.

  string | null

  ##### Example

  ```plaintext
  daytona
  ```

  **template\_revision\_id**

  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.

  string | null

* null

  Who may choose the primary Sandbox for a Session. Older rows omit this field; one template then means `fixed`, while several mean `selectable`.

  string

  Allowed values: fixed selectable configurable

* string

  null

* null

  Requested isolation policy; resolution supplies an honest target default.

  object

  **escalation**

  Whether the runtime may widen containment after Session creation.

  string

  Allowed values: never approval auto

  **filesystem**

  Filesystem mutation boundary for command execution.

  object

  **writable\_roots**

  Absolute roots the runtime may mutate; empty means provider default.

  Array\<string>

  **level**

  required

  Isolation mechanism the provider must supply.

  string

  Allowed values: none native isolated

  **network**

  One of:

  * object

    object

    **mode**

    required

    string

    Allowed values: deny

  * object

    object

    **allowed\_hosts**

    required

    Array\<string>

    **mode**

    required

    string

    Allowed values: allowlist

  * object

    object

    **mode**

    required

    string

    Allowed values: allow

* object

  object

  **mode**

  required

  string

  Allowed values: deny

* null

  object

  **allowed\_hosts**

  required

  Array\<string>

  **mode**

  required

  string

  Allowed values: allowlist

* object

  object

  **mode**

  required

  string

  Allowed values: allow

* object

  null

* object

  Requested recovery guarantee; resolution supplies a target default.

  string

  Allowed values: checkpointed provider\_snapshot none

* string

  null

* null

  null

**service\_virtual\_user\_id**

string | null

**short\_description**

One-line description in simplified Markdown. Outer `None` leaves unchanged; inner `None` clears.

string | null

##### Example

```plaintext
Answers account questions in seconds.
```

**starters**

Conversation starters as `[{"text": "..."}]`; omit to keep, `[]` to clear. An optional `icon` reuses the harness icon name set.

Array\<object> | null

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

**icon**

Optional icon name from the harness icon set.

string | null

##### Example

```plaintext
zap
```

**text**

required

Prompt text inserted into the composer when selected.

string

##### Example

```plaintext
Triage the newest P1
```

##### Example

```json
[
  {
    "text": "Who does the dishes today?"
  }
]
```

**status**

One of:

* string

  The status of the agent. Set to “archived” to soft-delete.

  string

  Allowed values: active archived deleted

  ##### Example

  ```plaintext
  active
  ```

* null

  null

**system\_prompt**

The system prompt that defines the agent’s behavior and capabilities.

string | null

##### Example

```plaintext
You are an updated helpful assistant.
```

**tags**

Tags for organizing and filtering agents.

Array\<string> | null

##### Example

```json
[
  "updated-tag"
]
```

**tools**

Client-side tools for this agent. Replaces existing tools if provided.

Array | null

One of:

* object

  Built-in tool - executed by the worker via ToolRegistry

  object

  **category**

  Category for tool\_search namespace grouping (from parent capability)

  string | null

  **deferrable**

  Whether this tool’s schema can be deferred via tool\_search

  string

  Allowed values: never automatic always

  **description**

  required

  Tool description for LLM

  string

  **display\_name**

  Human-readable display name for UI rendering (e.g., “Get Current Time” for `get_current_time`)

  string | null

  **full\_parameters**

  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.

  **hints**

  Semantic hints describing the tool’s behavioral properties

  object

  **capability\_id**

  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.

  string | null

  **capability\_name**

  Human-readable capability name snapshot for reporting.

  string | null

  **concurrency\_class**

  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.

  string | null

  **cpu\_bound**

  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).

  boolean | null

  **destructive**

  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).

  boolean | null

  **idempotent**

  Calling the tool repeatedly with the same arguments produces the same effect. Safe to retry on transient failures.

  boolean | null

  **long\_running**

  Tool may take significant time to complete (> \~5s typical). Useful for clients to show progress indicators and set timeouts.

  boolean | null

  **metadata**

  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.

  **narration\_noun**

  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”.

  string | null

  **open\_world**

  Tool interacts with external entities beyond the local system (network calls, third-party APIs, cloud services).

  boolean | null

  **persist\_output**

  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.

  boolean | null

  **readonly**

  Tool does not modify any state (read-only queries, lookups). When true: safe to call speculatively, result can be cached.

  boolean | null

  **requires\_secrets**

  Tool requires API keys, credentials, or other secrets to function. Useful for UI to show connection prompts and for LLMs to anticipate authentication failures.

  boolean | null

  **side\_effect\_class**

  One of:

  * string

    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`.

    string

    Allowed values: Pure Idempotent AtMostOnce

  * null

    null

  **stays\_direct**

  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.

  boolean | null

  **supports\_background**

  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.

  boolean | null

  **name**

  required

  Tool name (used by LLM and for registry lookup)

  string

  **parameters**

  required

  JSON schema for tool parameters

  **policy**

  Tool policy (auto or requires\_approval)

  string

  Allowed values: auto requires\_approval client\_side

  **type**

  required

  string

  Allowed values: builtin

* object

  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`.

  string

  Allowed values: Pure Idempotent AtMostOnce

* string

  null

* null

  Client-side tool - executed by the client, not the server

  object

  **category**

  Category for tool\_search namespace grouping (from parent capability)

  string | null

  **deferrable**

  Whether this tool’s schema can be deferred via tool\_search

  string

  Allowed values: never automatic always

  **description**

  required

  Tool description for LLM

  string

  **display\_name**

  Human-readable display name for UI rendering

  string | null

  **full\_parameters**

  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.

  **hints**

  Semantic hints describing the tool’s behavioral properties

  object

  **capability\_id**

  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.

  string | null

  **capability\_name**

  Human-readable capability name snapshot for reporting.

  string | null

  **concurrency\_class**

  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.

  string | null

  **cpu\_bound**

  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).

  boolean | null

  **destructive**

  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).

  boolean | null

  **idempotent**

  Calling the tool repeatedly with the same arguments produces the same effect. Safe to retry on transient failures.

  boolean | null

  **long\_running**

  Tool may take significant time to complete (> \~5s typical). Useful for clients to show progress indicators and set timeouts.

  boolean | null

  **metadata**

  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.

  **narration\_noun**

  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”.

  string | null

  **open\_world**

  Tool interacts with external entities beyond the local system (network calls, third-party APIs, cloud services).

  boolean | null

  **persist\_output**

  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.

  boolean | null

  **readonly**

  Tool does not modify any state (read-only queries, lookups). When true: safe to call speculatively, result can be cached.

  boolean | null

  **requires\_secrets**

  Tool requires API keys, credentials, or other secrets to function. Useful for UI to show connection prompts and for LLMs to anticipate authentication failures.

  boolean | null

  **side\_effect\_class**

  One of:

  * string

    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`.

    string

    Allowed values: Pure Idempotent AtMostOnce

  * null

    null

  **stays\_direct**

  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.

  boolean | null

  **supports\_background**

  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.

  boolean | null

  **name**

  required

  Tool name (used by LLM and for correlation)

  string

  **parameters**

  required

  JSON schema for tool parameters

  **type**

  required

  string

  Allowed values: client\_side

* string

  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`.

  string

  Allowed values: Pure Idempotent AtMostOnce

* null

  null

##### Example

```json
[
  {
    "description": "Open URL in the user's browser",
    "name": "open_url",
    "parameters": {
      "properties": {
        "url": {
          "type": "string"
        }
      },
      "required": [
        "url"
      ],
      "type": "object"
    },
    "type": "client_side"
  }
]
```

## Responses

### 200

Agent updated successfully

Media typeapplication/json

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

**archived\_at**

Timestamp when the agent was archived.

string | null format: date-time

**avatar**

One of:

* object

  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

  **circle\_url**

  required

  Circular avatar (transparent corners), 256 px.

  string

  **id**

  required

  Prefixed public identifier. See [ID Schema](https://everruns.com/docs/advanced/id-schema/).

  string

  **sizes**

  required

  Edge lengths, in pixels, available for both shapes.

  Array\<integer>

  **url**

  required

  Square avatar, 256 px.

  string

* null

  null

**capabilities**

Capabilities enabled for this agent with per-agent configuration. Capabilities add tools and system prompt modifications.

Array\<object>

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

**config**

Per-agent configuration for this capability (capability-specific)

**ref**

required

Reference to the capability ID

string

**communication**

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.

string

Allowed values: direct explicit

**created\_at**

required

Timestamp when the agent was created.

string format: date-time

**default\_model\_id**

Default LLM model ID for this agent. Can be overridden at the session level.

string | null

**deleted\_at**

Timestamp when the agent was deleted.

string | null format: date-time

**description**

Human-readable description of what the agent does.

string | null

**display\_name**

Human-readable display name shown in UI (e.g. “Customer Support Agent”). Falls back to `name` when absent.

string | null

**exposed**

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.

boolean

**exposures\_suspended**

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.

boolean

**forked\_from\_agent\_id**

Source agent for a forked agent.

string | null

**harness\_id**

required

Harness that supplies the base execution environment for this agent.

string

**id**

required

External identifier (agent\_<32-hex>). Shown as “id” in API. Client-supplied or auto-generated.

string

**initial\_files**

Starter files copied into each new session for this agent.

Array\<object>

Starter file copied into a new session from an agent or harness.

object

**content**

required

File content: plain text or base64-encoded binary.

string

**encoding**

Content encoding: `text` or `base64`.

string

**is\_readonly**

Prevent session-side edits or deletes when true.

boolean

**path**

required

Absolute path within the session workspace. `/workspace` prefix is accepted.

string

**intro\_markdown**

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.

string | null

**is\_built\_in**

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.

boolean

**max\_iterations**

Maximum number of LLM iterations per turn for this agent.

integer | null

**mcpServers**

Remote MCP servers scoped to this agent and inherited by its sessions.

object

***key***

additional properties

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

**actsAs**

Identity whose grant this attachment requests.

string

Allowed values: none service user user\_or\_service

**args**

Arguments passed to the stdio `command`.

Array\<string>

**auth\_mode**

Authentication mode used when executing tools from this scoped server.

string

Allowed values: none api\_key oauth

**command**

Executable to spawn for a stdio transport server.

string | null

**connectInChat**

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`).

string

Allowed values: ask never

**deferred**

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).

boolean

**elicitation\_policy**

Which elicitation modes this server may use (`url` by default).

string

Allowed values: url url\_and\_form none

**env**

Environment variables set for the stdio `command`.

object

***key***

additional properties

string

**headers**

Additional HTTP headers sent on MCP requests (HTTP transport only).

object

***key***

additional properties

string

**oauth\_provider\_id**

Provider id used to resolve a user-scoped bearer token.

string | null

**protocol\_mode**

Protocol-era adoption policy for the MCP client (`auto` negotiates).

string

Allowed values: auto 2025-03-26 2025-06-18 2026-07-28

**tool\_discovery**

Whether to discover tool definitions live from this server.

boolean

**tool\_labels**

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

***key***

additional properties

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.

string

Allowed values: read\_only changes

**type**

MCP transport type. Only remote HTTP is supported today.

string

Allowed values: http stdio

**url**

URL of the remote MCP server endpoint. Required for HTTP transport; empty/ignored for stdio.

string

**use**

One of:

* string

  Organization catalog preset that supplies transport and authentication policy.

  string

* null

  null

**name**

required

Name, unique per org (e.g. “customer-support”).

string

**network\_access**

One of:

* object

  Network access list controlling which hosts/URLs agent sessions can reach. Merged with harness and session layers (allowed: intersect, blocked: union).

  object

  **allowed**

  Allowed host patterns. If non-empty, only matching URLs are permitted. An empty list means “no restriction from this layer” (inherit parent).

  Array\<string>

  **blocked**

  Blocked host patterns. Always denied, even if matched by `allowed`.

  Array\<string>

* null

  null

**parallel\_tool\_calls**

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).

boolean | null

**root\_agent\_id**

Root agent lineage identifier for grouping fork families.

string | null

**sandbox\_policy**

One of:

* object

  Policy for selecting the primary Sandbox Template for new Sessions.

  object

  **default**

  required

  Template binding inherited when Session creation does not choose one.

  string

  **mode**

  One of:

  * string

    Who may choose the primary Sandbox for a Session. Older rows omit this field; one template then means `fixed`, while several mean `selectable`.

    string

    Allowed values: fixed selectable configurable

  * null

    null

  **templates**

  Template snapshots addressable by binding name at Session creation.

  object

  ***key***

  additional properties

  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

  **bootstrap**

  Reproducible commands run when physical compute is initialized.

  object

  **commands**

  Ordered commands replayed when creating or recovering physical compute.

  Array\<string>

  **containment**

  One of:

  * object

    Requested isolation policy; resolution supplies an honest target default.

    object

    **escalation**

    Whether the runtime may widen containment after Session creation.

    string

    Allowed values: never approval auto

    **filesystem**

    Filesystem mutation boundary for command execution.

    object

    **writable\_roots**

    Absolute roots the runtime may mutate; empty means provider default.

    Array\<string>

    **level**

    required

    Isolation mechanism the provider must supply.

    string

    Allowed values: none native isolated

    **network**

    One of:

    * object

      object

      **mode**

      required

      string

      Allowed values: deny

    * object

      object

      **allowed\_hosts**

      required

      Array\<string>

      **mode**

      required

      string

      Allowed values: allowlist

    * object

      object

      **mode**

      required

      string

      Allowed values: allow

  * null

    object

    **mode**

    required

    string

    Allowed values: deny

  * object

    object

    **allowed\_hosts**

    required

    Array\<string>

    **mode**

    required

    string

    Allowed values: allowlist

  * object

    object

    **mode**

    required

    string

    Allowed values: allow

  * object

    null

  **durability**

  One of:

  * string

    Requested recovery guarantee; resolution supplies a target default.

    string

    Allowed values: checkpointed provider\_snapshot none

  * null

    null

  **lifecycle**

  Idle lifecycle policy controlled by Everruns.

  object

  **idle\_action**

  Action Everruns requests after the idle interval.

  string

  Allowed values: checkpoint\_and\_stop stop keep\_running

  **idle\_after\_seconds**

  Inactivity interval before applying `idle_action`.

  integer format: int64

  **target**

  required

  Provider-neutral target plus its concrete adapter binding.

  object

  **connection\_id**

  Credential/transport binding for a registered machine target.

  string | null

  **credential**

  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

  **connection\_id**

  Exact connection for organization grants, which may have several accounts for one provider.

  string | null format: uuid

  **source**

  required

  Identity scope from which the provider credential is resolved.

  string

  Allowed values: none session\_user agent organization

  **virtual\_user\_id**

  Exact virtual-user owner for user, Agent, and organization grants.

  string | null format: uuid

  **kind**

  required

  Provider-neutral target class.

  string

  Allowed values: host machine vfs container managed

  **options**

  Provider-owned, non-secret configuration. Credentials are references, never values in this object.

  object

  **provider**

  Concrete adapter for target kinds with more than one implementation.

  string | null

  **template\_revision\_id**

  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.

  string | null

* null

  Who may choose the primary Sandbox for a Session. Older rows omit this field; one template then means `fixed`, while several mean `selectable`.

  string

  Allowed values: fixed selectable configurable

* string

  null

* null

  Requested isolation policy; resolution supplies an honest target default.

  object

  **escalation**

  Whether the runtime may widen containment after Session creation.

  string

  Allowed values: never approval auto

  **filesystem**

  Filesystem mutation boundary for command execution.

  object

  **writable\_roots**

  Absolute roots the runtime may mutate; empty means provider default.

  Array\<string>

  **level**

  required

  Isolation mechanism the provider must supply.

  string

  Allowed values: none native isolated

  **network**

  One of:

  * object

    object

    **mode**

    required

    string

    Allowed values: deny

  * object

    object

    **allowed\_hosts**

    required

    Array\<string>

    **mode**

    required

    string

    Allowed values: allowlist

  * object

    object

    **mode**

    required

    string

    Allowed values: allow

* object

  object

  **mode**

  required

  string

  Allowed values: deny

* null

  object

  **allowed\_hosts**

  required

  Array\<string>

  **mode**

  required

  string

  Allowed values: allowlist

* object

  object

  **mode**

  required

  string

  Allowed values: allow

* object

  null

* object

  Requested recovery guarantee; resolution supplies a target default.

  string

  Allowed values: checkpointed provider\_snapshot none

* string

  null

* null

  null

**service\_virtual\_user\_id**

Org-scoped service account used when a tool acts as the agent.

string | null

**short\_description**

Optional one-line description in simplified Markdown, shown below the chat title once the intro is hidden. Wins over the harness value.

string | null

**starters**

Conversation starters for a fresh Platform Chat thread. Win over the harness starters when non-empty.

Array\<object>

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

**icon**

Optional icon name from the harness icon set.

string | null

**text**

required

Prompt text inserted into the composer when selected.

string

**status**

required

Current lifecycle status of the agent.

string

Allowed values: active archived deleted

**system\_prompt**

required

System prompt that defines the agent’s behavior. Sent as the first message in every conversation.

string

**tags**

Tags for organizing and filtering agents.

Array\<string>

**tools**

Client-side tools registered for this agent. These tools are executed by the client, not the server.

Array

One of:

* object

  Built-in tool - executed by the worker via ToolRegistry

  object

  **category**

  Category for tool\_search namespace grouping (from parent capability)

  string | null

  **deferrable**

  Whether this tool’s schema can be deferred via tool\_search

  string

  Allowed values: never automatic always

  **description**

  required

  Tool description for LLM

  string

  **display\_name**

  Human-readable display name for UI rendering (e.g., “Get Current Time” for `get_current_time`)

  string | null

  **full\_parameters**

  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.

  **hints**

  Semantic hints describing the tool’s behavioral properties

  object

  **capability\_id**

  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.

  string | null

  **capability\_name**

  Human-readable capability name snapshot for reporting.

  string | null

  **concurrency\_class**

  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.

  string | null

  **cpu\_bound**

  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).

  boolean | null

  **destructive**

  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).

  boolean | null

  **idempotent**

  Calling the tool repeatedly with the same arguments produces the same effect. Safe to retry on transient failures.

  boolean | null

  **long\_running**

  Tool may take significant time to complete (> \~5s typical). Useful for clients to show progress indicators and set timeouts.

  boolean | null

  **metadata**

  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.

  **narration\_noun**

  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”.

  string | null

  **open\_world**

  Tool interacts with external entities beyond the local system (network calls, third-party APIs, cloud services).

  boolean | null

  **persist\_output**

  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.

  boolean | null

  **readonly**

  Tool does not modify any state (read-only queries, lookups). When true: safe to call speculatively, result can be cached.

  boolean | null

  **requires\_secrets**

  Tool requires API keys, credentials, or other secrets to function. Useful for UI to show connection prompts and for LLMs to anticipate authentication failures.

  boolean | null

  **side\_effect\_class**

  One of:

  * string

    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`.

    string

    Allowed values: Pure Idempotent AtMostOnce

  * null

    null

  **stays\_direct**

  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.

  boolean | null

  **supports\_background**

  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.

  boolean | null

  **name**

  required

  Tool name (used by LLM and for registry lookup)

  string

  **parameters**

  required

  JSON schema for tool parameters

  **policy**

  Tool policy (auto or requires\_approval)

  string

  Allowed values: auto requires\_approval client\_side

  **type**

  required

  string

  Allowed values: builtin

* object

  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`.

  string

  Allowed values: Pure Idempotent AtMostOnce

* string

  null

* null

  Client-side tool - executed by the client, not the server

  object

  **category**

  Category for tool\_search namespace grouping (from parent capability)

  string | null

  **deferrable**

  Whether this tool’s schema can be deferred via tool\_search

  string

  Allowed values: never automatic always

  **description**

  required

  Tool description for LLM

  string

  **display\_name**

  Human-readable display name for UI rendering

  string | null

  **full\_parameters**

  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.

  **hints**

  Semantic hints describing the tool’s behavioral properties

  object

  **capability\_id**

  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.

  string | null

  **capability\_name**

  Human-readable capability name snapshot for reporting.

  string | null

  **concurrency\_class**

  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.

  string | null

  **cpu\_bound**

  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).

  boolean | null

  **destructive**

  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).

  boolean | null

  **idempotent**

  Calling the tool repeatedly with the same arguments produces the same effect. Safe to retry on transient failures.

  boolean | null

  **long\_running**

  Tool may take significant time to complete (> \~5s typical). Useful for clients to show progress indicators and set timeouts.

  boolean | null

  **metadata**

  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.

  **narration\_noun**

  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”.

  string | null

  **open\_world**

  Tool interacts with external entities beyond the local system (network calls, third-party APIs, cloud services).

  boolean | null

  **persist\_output**

  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.

  boolean | null

  **readonly**

  Tool does not modify any state (read-only queries, lookups). When true: safe to call speculatively, result can be cached.

  boolean | null

  **requires\_secrets**

  Tool requires API keys, credentials, or other secrets to function. Useful for UI to show connection prompts and for LLMs to anticipate authentication failures.

  boolean | null

  **side\_effect\_class**

  One of:

  * string

    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`.

    string

    Allowed values: Pure Idempotent AtMostOnce

  * null

    null

  **stays\_direct**

  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.

  boolean | null

  **supports\_background**

  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.

  boolean | null

  **name**

  required

  Tool name (used by LLM and for correlation)

  string

  **parameters**

  required

  JSON schema for tool parameters

  **type**

  required

  string

  Allowed values: client\_side

* string

  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`.

  string

  Allowed values: Pure Idempotent AtMostOnce

* null

  null

**updated\_at**

required

Timestamp when the agent was last updated.

string format: date-time

**usage**

One of:

* object

  Cumulative token usage across all sessions for this agent.

  object

  **actual\_cost\_usd**

  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 | null format: double

  **cache\_creation\_tokens**

  Number of tokens written to cache, disjoint from `input_tokens`

  integer | null format: int32

  **cache\_read\_tokens**

  Number of tokens read from cache (reduces cost), disjoint from `input_tokens`

  integer | null format: int32

  **effective\_cost\_usd**

  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).

  number | null format: double

  **estimated\_cost\_usd**

  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 | null format: double

  **input\_tokens**

  required

  Number of non-cached prompt tokens (cached reads/writes are tracked separately; see the disjoint bucket convention on the struct)

  integer format: int32

  **output\_tokens**

  required

  Number of output/completion tokens

  integer format: int32

* null

  null

**allowed\_actions**

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.

Array\<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

* **Error recovery** — `ErrorResponse.allowed_actions` carries `rel`s like `retry`, `retry-later`, `unarchive`, `get-existing` so the agent knows the right next call after a 4xx/429.
* **Entity hypermedia** — `WithUrls<T>.allowed_actions` carries state-aware `rel`s like `cancel`, `events`, `self`, `update` on 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

**hint**

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null

**href**

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.

string | null

**method**

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.

string | null

**operation\_id**

OpenAPI `operationId` the caller should invoke. Lets an MCP client resolve the call without parsing `href`.

string | null

**rel**

required

Link relation describing the action. Examples: `self`, `cancel`, `pause`, `resume`, `events`, `retry`, `retry-later`, `unarchive`, `get-existing`, `delete`, `update`.

string

**schema\_ref**

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.

string | null

**self\_url**

required

Full API endpoint URL for this resource.

string

**ui\_link**

required

Alias for `view_url`, used by command and MCP outputs.

string

**view\_url**

required

Full UI URL for viewing this resource.

string

##### Example

```json
{
  "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",
  "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,
  "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"
    }
  },
  "name": "customer-support",
  "network_access": {
    "allowed": [
      "*.example.com",
      "https://api.acme.com/"
    ],
    "blocked": [
      "169.254.169.254"
    ]
  },
  "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": {
          "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"
    }
  ]
}
```

### 400

Invalid agent ID or input exceeds allowed limits

Media typeapplication/json

Standard error response.

Wire shape is [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457): 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

**allowed\_actions**

Recovery actions the caller can take next.

Array\<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

* **Error recovery** — `ErrorResponse.allowed_actions` carries `rel`s like `retry`, `retry-later`, `unarchive`, `get-existing` so the agent knows the right next call after a 4xx/429.
* **Entity hypermedia** — `WithUrls<T>.allowed_actions` carries state-aware `rel`s like `cancel`, `events`, `self`, `update` on 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

**hint**

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null

**href**

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.

string | null

**method**

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.

string | null

**operation\_id**

OpenAPI `operationId` the caller should invoke. Lets an MCP client resolve the call without parsing `href`.

string | null

**rel**

required

Link relation describing the action. Examples: `self`, `cancel`, `pause`, `resume`, `events`, `retry`, `retry-later`, `unarchive`, `get-existing`, `delete`, `update`.

string

**schema\_ref**

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.

string | null

**code**

Stable, machine-readable error code (snake\_case).

string | null

**detail**

Human-readable explanation specific to this occurrence.

string | null

**instance**

Request URI for this occurrence.

string | null

**retry\_after\_seconds**

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32

**status**

required

HTTP status code; mirrors the response status line.

integer format: int32

**title**

required

Short, human-readable summary of the problem (e.g. “Not Found”).

string

**type**

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null

##### Example

```json
{
  "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"
}
```

### 404

Agent not found

Media typeapplication/json

Standard error response.

Wire shape is [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457): 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

**allowed\_actions**

Recovery actions the caller can take next.

Array\<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

* **Error recovery** — `ErrorResponse.allowed_actions` carries `rel`s like `retry`, `retry-later`, `unarchive`, `get-existing` so the agent knows the right next call after a 4xx/429.
* **Entity hypermedia** — `WithUrls<T>.allowed_actions` carries state-aware `rel`s like `cancel`, `events`, `self`, `update` on 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

**hint**

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null

**href**

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.

string | null

**method**

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.

string | null

**operation\_id**

OpenAPI `operationId` the caller should invoke. Lets an MCP client resolve the call without parsing `href`.

string | null

**rel**

required

Link relation describing the action. Examples: `self`, `cancel`, `pause`, `resume`, `events`, `retry`, `retry-later`, `unarchive`, `get-existing`, `delete`, `update`.

string

**schema\_ref**

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.

string | null

**code**

Stable, machine-readable error code (snake\_case).

string | null

**detail**

Human-readable explanation specific to this occurrence.

string | null

**instance**

Request URI for this occurrence.

string | null

**retry\_after\_seconds**

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32

**status**

required

HTTP status code; mirrors the response status line.

integer format: int32

**title**

required

Short, human-readable summary of the problem (e.g. “Not Found”).

string

**type**

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null

##### Example

```json
{
  "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"
}
```

### 500

Internal server error

Media typeapplication/json

Standard error response.

Wire shape is [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457): 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

**allowed\_actions**

Recovery actions the caller can take next.

Array\<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

* **Error recovery** — `ErrorResponse.allowed_actions` carries `rel`s like `retry`, `retry-later`, `unarchive`, `get-existing` so the agent knows the right next call after a 4xx/429.
* **Entity hypermedia** — `WithUrls<T>.allowed_actions` carries state-aware `rel`s like `cancel`, `events`, `self`, `update` on 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

**hint**

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null

**href**

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.

string | null

**method**

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.

string | null

**operation\_id**

OpenAPI `operationId` the caller should invoke. Lets an MCP client resolve the call without parsing `href`.

string | null

**rel**

required

Link relation describing the action. Examples: `self`, `cancel`, `pause`, `resume`, `events`, `retry`, `retry-later`, `unarchive`, `get-existing`, `delete`, `update`.

string

**schema\_ref**

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.

string | null

**code**

Stable, machine-readable error code (snake\_case).

string | null

**detail**

Human-readable explanation specific to this occurrence.

string | null

**instance**

Request URI for this occurrence.

string | null

**retry\_after\_seconds**

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32

**status**

required

HTTP status code; mirrors the response status line.

integer format: int32

**title**

required

Short, human-readable summary of the problem (e.g. “Not Found”).

string

**type**

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null

##### Example

```json
{
  "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"
}
```