Skip to content
Everruns Everruns

Copy an agent

POST
/v1/agents/{agent_id}/copy
 
curl --request POST \
  --url https://app.everruns.com/api/v1/agents/example/copy

Creates a new agent with the same configuration as the source agent. The new agent’s name will be “{original name} (copy)”.

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
agent_id
required
string

Source agent ID to copy

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Agent copied successfully

Media type application/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
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
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
default_version_id

Default immutable version used by deployments that choose the default policy.

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
forked_from_agent_id

Source agent for a forked agent.

string | null
forked_from_version_id

Source version for a forked agent.

string | null
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
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
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 o_auth
command

Executable to spawn for a stdio transport server.

string | null
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
tool_discovery

Whether to discover tool definitions live from this server.

boolean
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
name
required

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

string
network_access
One of:
null
root_agent_id

Root agent lineage identifier for grouping fork families.

string | null
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:

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
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 crate::atoms::tool_scheduler for how the act scheduler 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
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
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
updated_at
required

Timestamp when the agent was last updated.

string format: date-time
usage
One of:
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 rels 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 rels 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 documented in specs/api-conventions.md 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. Closed vocabulary documented in specs/api-conventions.md — 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 
{
  "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"
    }
  ]
}

400

Section titled “400 ”

Invalid agent ID

Media type application/json

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
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 rels 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 rels 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 documented in specs/api-conventions.md 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. Closed vocabulary documented in specs/api-conventions.md — 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 
{
  "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"
}

404

Section titled “404 ”

Source agent not found

Media type application/json

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
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 rels 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 rels 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 documented in specs/api-conventions.md 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. Closed vocabulary documented in specs/api-conventions.md — 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 
{
  "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"
}

500

Section titled “500 ”

Internal server error

Media type application/json

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
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 rels 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 rels 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 documented in specs/api-conventions.md 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. Closed vocabulary documented in specs/api-conventions.md — 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 
{
  "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"
}