Skip to content
Everruns

POST /v1/agents - 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
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"
]

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

Display name of the agent.

string
status
required

Current lifecycle status of the agent.

string
Allowed values: active archived
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>
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