# GET /v1/agents/{agent_id}/export - Export agent in Markdown format with YAML front matter
Source:
GET
/v1/agents/{agent\_id}/export
Select code samplecURL (shell:curl)
```js
const url = 'https://app.everruns.com/api/v1/agents/example/export';
const options = {method: 'GET'};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
```sh
curl --request GET \
--url https://app.everruns.com/api/v1/agents/example/export
```
* Production APIapp.everruns.com/api/v1/agents/{agent\_id}/export
## Parameters
### Path Parameters
**agent\_id**
required
string
Agent name or ID
### Query Parameters
**format**
string
Markdown (default), json, yaml, toml, or zip.
## Responses
### 200
Portable agent definition (format selects text or ZIP)
Media typeapplication/json
Authored values only: no organisation, agent, model, harness or channel IDs.
object
**capabilities**
Named capabilities, optionally with configuration; the host validates availability.
Array
One of:
* string
string
* object
A capability requirement identified by a stable reference and optional settings.
object
**config**
Configuration validated against the destination capability schema.
**ref**
required
Built-in or catalog capability name. Destination resource IDs are rejected.
string
**channels**
Named channel descriptions, upserted without removing omitted destination channels.
object
***key***
additional properties
Portable channel intent. Authentication and installation are host bindings. Channels default to disabled; enabled intent still requires host publication.
object
**config**
Declarative transport settings, excluding credentials and destination resource IDs.
**enabled**
Request an enabled draft; false by default. Publication remains a host operation.
boolean
**type**
required
Ingress transport type, such as ag\_ui, public\_chat, fcp or slack.
string
**communication**
One of:
* string
How the agent talks: `direct` (its text is the reply) or `explicit` (its text is working notes; it talks through `send_message`). Omission means `direct`.
string
Allowed values: direct explicit
* null
null
**description**
Optional description of the agent’s purpose.
string | null
**display\_name**
Human-readable agent label. Defaults to the stable name at the host.
string | null
**files**
Starting files or package-relative sources. Sources retain their relative paths.
Array
One of:
* string
string
* object
A package-relative file or glob and its working-directory destination.
object
**is\_readonly**
Whether the initial workspace file is read-only. Defaults to true.
boolean
**path**
Working-directory destination; omitted paths preserve the package source.
string | null
**source**
required
Relative file path or glob confined to the package directory.
string
* 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
**harness**
Named harness requirement. Omission uses the host’s default harness.
string | null
**instructions**
Authored instructions. Legacy system\_prompt input is also accepted.
string
**instructions\_file**
Package-relative instructions source. Folder loading defaults to instructions.md.
string | null
**intro\_markdown**
Optional Markdown introduction shown before the conversation starts.
string | null
**max\_iterations**
Optional tool-loop iteration limit. Omission keeps the host default.
integer | null
**mcpServers**
Named scoped MCP definitions. Credential placeholders require explicit host bindings.
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\
**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
**model**
One of:
* object
Provider and model names. Omission uses the host’s default model.
object
**model**
required
Provider-native model name, rather than a platform model ID.
string
**provider**
required
Stable provider name, such as openai or anthropic.
string
* null
null
**name**
Stable agent name used for destination lookup; resource IDs are not portable.
string
**network\_access**
One of:
* object
Optional outbound network policy enforced by the host.
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\
**blocked**
Blocked host patterns. Always denied, even if matched by `allowed`.
Array\
* null
null
**parallel\_tool\_calls**
Whether independent tool calls may run concurrently. Omission keeps the host default.
boolean | null
**sandbox\_policy**
Platform-specific Sandbox policy. Other hosts must explicitly bind or reject it rather than silently discarding execution requirements.
**schema\_version**
Portable format version. Currently 1; omitted values default to 1.
integer format: int32
**short\_description**
Optional short description for agent discovery surfaces.
string | null
**skills**
Package-relative skill folders including SKILL.md and supporting assets.
Array\
**starters**
Suggested opening messages in the platform’s starter format.
Array
**tags**
Discovery tags, compared as an unordered set.
Array\
**tools**
Tool schemas whose executable implementations must be bound by the host.
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
##### Example
```json
{
"communication": "direct",
"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"
}
},
"network_access": {
"allowed": [
"*.example.com",
"https://api.acme.com/"
],
"blocked": [
"169.254.169.254"
]
},
"tools": [
{
"deferrable": "never",
"hints": {
"side_effect_class": "Pure"
},
"policy": "auto",
"type": "builtin"
}
]
}
```
### 400
Invalid agent ID
### 404
Agent not found
### 500
Internal server error