Get agent by ID or name
GET /v1/agents/{agent_id}
Accepts either an agent ID (e.g. agent_01933b5a...) or a
name (e.g. customer-support). Names are resolved within the caller’s org.
Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Agent ID (prefixed) or name
Responses
Section titled “ Responses ”Agent found
Wrapper that adds self_url and view_url 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).
object
Timestamp when the agent was archived.
Capabilities enabled for this agent with per-agent configuration. Capabilities add tools and system prompt modifications.
Per-agent capability configuration
Associates a capability with an agent, including optional per-agent configuration. The config field allows the same capability to behave differently per-agent.
object
Per-agent configuration for this capability (capability-specific)
Reference to the capability ID
Timestamp when the agent was created.
Default LLM model ID for this agent. Can be overridden at the session level.
Example
model_01933b5a00007000800000000000001Timestamp when the agent was deleted.
Human-readable description of what the agent does.
Human-readable display name shown in UI (e.g. “Customer Support Agent”).
Falls back to name when absent.
External identifier (agent_<32-hex>). Shown as “id” in API. Client-supplied or auto-generated.
Example
agent_01933b5a000070008000000000000001Starter files copied into each new session for this agent.
Starter file copied into a new session from an agent or harness.
object
File content: plain text or base64-encoded binary.
Content encoding: text or base64.
Prevent session-side edits or deletes when true.
Absolute path within the session workspace. /workspace prefix is accepted.
Maximum number of LLM iterations per turn for this agent.
Remote MCP servers scoped to this agent and inherited by its sessions.
object
Session-, agent-, or harness-scoped remote MCP server configuration.
This intentionally mirrors the mcpServers object shape used by common MCP
client config files while staying within Everruns’ current remote-HTTP-only
support.
object
Authentication mode used when executing tools from this scoped server.
Additional HTTP headers sent on MCP requests.
object
Provider id used to resolve a user-scoped bearer token.
Whether to discover tool definitions live from this server.
MCP transport type. Only remote HTTP is supported today.
URL of the remote MCP server endpoint.
Name, unique per org (e.g. “customer-support”).
Network access list controlling which hosts/URLs agent sessions can reach. Merged with harness and session layers (allowed: intersect, blocked: union).
object
Allowed host patterns. If non-empty, only matching URLs are permitted. An empty list means “no restriction from this layer” (inherit parent).
Blocked host patterns. Always denied, even if matched by allowed.
Current lifecycle status of the agent.
System prompt that defines the agent’s behavior. Sent as the first message in every conversation.
Tags for organizing and filtering agents.
Client-side tools registered for this agent. These tools are executed by the client, not the server.
Built-in tool - executed by the worker via ToolRegistry
object
Category for tool_search namespace grouping (from parent capability)
Whether this tool’s schema can be deferred via tool_search
Tool description for LLM
Human-readable display name for UI rendering (e.g., “Get Current Time” for get_current_time)
Semantic hints describing the tool’s behavioral properties
object
Tool may irreversibly destroy or delete data. Subset of non-readonly — a tool can be non-readonly (writes) without being destructive (e.g., create/update operations).
Calling the tool repeatedly with the same arguments produces the same effect. Safe to retry on transient failures.
Tool may take significant time to complete (> ~5s typical). Useful for clients to show progress indicators and set timeouts.
Entity noun for operation-based narration (e.g. “agent”, “harness”).
When set, the narration system reads the operation argument and
produces verb-based narration like “Created agent: Neon Cartographer”
instead of the generic “Ran Manage Agents”.
Tool interacts with external entities beyond the local system (network calls, third-party APIs, cloud services).
Tool output should be persisted to session VFS before truncation.
When set, the tool_output_persistence capability (EVE-222, EVE-245) writes
stdout to /.outputs/{tool_call_id}.stdout and stderr to
/.outputs/{tool_call_id}.stderr, injecting full_output, total_lines,
and output_files into the result.
Tool does not modify any state (read-only queries, lookups). When true: safe to call speculatively, result can be cached.
Tool requires API keys, credentials, or other secrets to function. Useful for UI to show connection prompts and for LLMs to anticipate authentication failures.
Tool supports detached background execution via spawn_background.
When true, the tool may be executed asynchronously outside the current
foreground tool call and report status back later.
Tool name (used by LLM and for registry lookup)
JSON schema for tool parameters
Tool policy (auto or requires_approval)
Client-side tool - executed by the client, not the server
object
Category for tool_search namespace grouping (from parent capability)
Whether this tool’s schema can be deferred via tool_search
Tool description for LLM
Human-readable display name for UI rendering
Semantic hints describing the tool’s behavioral properties
object
Tool may irreversibly destroy or delete data. Subset of non-readonly — a tool can be non-readonly (writes) without being destructive (e.g., create/update operations).
Calling the tool repeatedly with the same arguments produces the same effect. Safe to retry on transient failures.
Tool may take significant time to complete (> ~5s typical). Useful for clients to show progress indicators and set timeouts.
Entity noun for operation-based narration (e.g. “agent”, “harness”).
When set, the narration system reads the operation argument and
produces verb-based narration like “Created agent: Neon Cartographer”
instead of the generic “Ran Manage Agents”.
Tool interacts with external entities beyond the local system (network calls, third-party APIs, cloud services).
Tool output should be persisted to session VFS before truncation.
When set, the tool_output_persistence capability (EVE-222, EVE-245) writes
stdout to /.outputs/{tool_call_id}.stdout and stderr to
/.outputs/{tool_call_id}.stderr, injecting full_output, total_lines,
and output_files into the result.
Tool does not modify any state (read-only queries, lookups). When true: safe to call speculatively, result can be cached.
Tool requires API keys, credentials, or other secrets to function. Useful for UI to show connection prompts and for LLMs to anticipate authentication failures.
Tool supports detached background execution via spawn_background.
When true, the tool may be executed asynchronously outside the current
foreground tool call and report status back later.
Tool name (used by LLM and for correlation)
JSON schema for tool parameters
Timestamp when the agent was last updated.
Cumulative token usage across all sessions for this agent.
object
Number of tokens written to cache (Anthropic-specific)
Number of tokens read from cache (reduces cost)
Number of input/prompt tokens
Number of output/completion tokens
Full API endpoint URL for this resource.
Full UI URL for viewing this resource.
Invalid agent ID
Agent not found
Internal server error