Skip to content
Everruns Everruns

Create a new agent

POST
/v1/agents

Request Body required

Section titled “Request Body required ”

Request to create a new agent

object
capabilities

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

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
Example
[
  {
    "config": {},
    "ref": "current_time"
  },
  {
    "config": {},
    "ref": "web_fetch"
  }
]
default_model_id

The ID of the default LLM model to use for this agent. If not specified, the system default model will be used.

string | null
Example
model_01933b5a00007000800000000000001
description

A human-readable description of what the agent does.

string | null
Example
Handles customer inquiries and support tickets
id

Client-supplied agent ID (format: agent_{32-hex}). If not provided, one is auto-generated.

string | null
Example
agent_01933b5a00007000800000000000001
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
name
required

The name of the agent. Used for display purposes.

string
Example
Customer Support Agent
system_prompt
required

The system prompt that defines the agent’s behavior and capabilities. This is sent as the first message in every conversation.

string
Example
You are a helpful customer support agent. Be polite and professional.
tags

Tags for organizing and filtering agents.

Array<string>
Example
[
  "support",
  "customer-facing"
]
tools

Client-side tools for this agent. These tools are sent to the LLM but 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
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
open_world

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

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

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Agent created successfully

Agent configuration for agentic loop. An agent defines the behavior and capabilities of an AI assistant.

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
Example
model_01933b5a00007000800000000000001
deleted_at

Timestamp when the agent was deleted.

string | null format: date-time
description

Human-readable description of what the agent does.

string | null
id
required

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

string
Example
agent_01933b5a000070008000000000000001
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
name
required

Display name of the agent.

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:

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
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
open_world

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

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

400

Section titled “400 ”

Input exceeds allowed limits

Standard error response for API endpoints.

object
error
required

Error message describing what went wrong.

string

500

Section titled “500 ”

Internal server error

Standard error response for API endpoints.

object
error
required

Error message describing what went wrong.

string