Agents
Load, start, stop and inspect agents: status, config, tools, metadata, local tables, logs and usage.
On this page
List loaded agents
/agentsResponses
| Status | Description | Body | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Loaded agents | AgentList · array<AgentSummary> | |||||||||||||||
| |||||||||||||||||
Errors 401 · 403
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/agents" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Load an agent from an .adf file
/agents/loadLoading an already-loaded file returns its existing reference. Direct loads bypass the review gate unless requireReview is true. A load is a deliberate start: it reopens the runtime gate an emergency stop closed.
Request bodyapplication/json · LoadAgentBody · required
| Field | Type | Description |
|---|---|---|
filePathrequired | string | Absolute path of the .adf file |
requireReview | boolean | Enforce the review gate for this load (direct loads bypass it by default) |
Responses
| Status | Description | Body | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | The loaded agent | AgentRef | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paramsarray<object> | 2 fields of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
keyrequired | string | |
valuerequired | string |
provider_paramsinstructionsrequiredcontextrequiredcompact_threshold, max_request_media_files, max_request_media_mb, compaction_model, audit, dynamic_instructions
toolsrequiredTool declarations
5 fields of tools
namerequired | string | |
enabledrequired | boolean | |
visible | boolean | |
restricted | boolean | |
locked | boolean |
triggersrequiredon_startup, on_inbox, on_outbox, on_file_change, on_chat, on_timer, on_tool_call, on_task_create, on_task_complete, on_logs, on_llm_call
3 fields of triggers
enabledrequired | boolean | ||||||||||||||||||||||||||||||||||
targetsrequired | array<TriggerTarget> | ||||||||||||||||||||||||||||||||||
11 fields of | |||||||||||||||||||||||||||||||||||
scoperequired | string | |
lambda | string | System scope: |
command | string | System scope: shell command (alternative to lambda) |
warm | boolean | |
filter | object | |
debounce_ms | integer | |
interval_ms | integer | |
batch_ms | integer | |
batch_count | integer | |
locked | boolean | |
loop | string | Cognition loop this target wakes; absent = main |
lockedsecurityrequiredlimitsrequiredmessagingrequiredmode (proactive | respond_only | listen_only), receive, network, …
mcp2 fields of mcp
serversrequired | array<McpServerConfig> | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
20 fields of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
namerequired | string | ||||||||||
transportrequired | string | ||||||||||
command | string | ||||||||||
args | array<string> | ||||||||||
url | string | ||||||||||
oauth | boolean | ||||||||||
headers | map<string, string> | ||||||||||
header_env | array<object> | ||||||||||
bearer_token_env_var | string | ||||||||||
env | map<string, string> | ||||||||||
env_keys | array<string> | ||||||||||
env_schema | array<object> | ||||||||||
npm_package | string | ||||||||||
pypi_package | string | ||||||||||
source | string | ||||||||||
available_tools | array<object> | ||||||||||
tool_call_timeout_ms | integer | ||||||||||
restricted | boolean | ||||||||||
run_location | string | ||||||||||
credential_files | array<object> | ||||||||||
3 fields of | |||||||||||
pathrequired | string | |
required | boolean | |
write_back | boolean |
new_tools_restrictedadaptersChannel adapters by type
4 fields of adapters
enabledrequired | boolean | ||||
config | object | Adapter-specific settings (no secrets: tokens are credentials) | |||
policy | object | ||||
limits | object | ||||
1 field of | |||||
max_attachment_size | integer | Bytes |
providers8 fields of providers
idrequired | string |
| ||||||
typerequired | string | |||||||
namerequired | string | |||||||
baseUrlrequired | string | |||||||
preset | string | |||||||
defaultModel | string | |||||||
params | array<object> | |||||||
2 fields of | ||||||||
keyrequired | string | |
valuerequired | string |
requestDelayMsloopsInner (side) loops; main is implicit
8 fields of loops
namerequired | string | |
goalrequired | string | Becomes the loop's instructions |
enabledrequired | boolean | |
autostart | boolean | |
autonomous | boolean | |
model | object | |
compact_threshold | integer | null | |
tools | array<string> | Absolute allow-list, intersected with the host's enabled tools |
ws_connectionsservinglocked_fieldsmetadatarequiredcreated_at, updated_at, author, tags, version
runningGET /agents/{id} only: false for an open document (a file a client holds open without running it; design D4).
Errors 400 · 401 · 403 · 409 · 500
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |||||||||||||||||||||||||||||||
| 401 | Missing or wrong bearer token (unauthorized) | |||||||||||||||||||||||||||||||
| 403 | The .adf must be reviewed on this machine before it loads (AGENT_REVIEW_REQUIRED), or the request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin) | ReviewRequiredResponse | ErrorResponse | ||||||||||||||||||||||||||||||
Option 2object | Every error body. Some routes add fields (e.g. 2 fields of | |||||||||||||||||||||||||||||||
errorrequired | string | Human-readable message |
code | string | Stable machine-readable code. Every error body has one: route-specific where listed, else the status default (400 bad_request, 403 forbidden, 404 not_found, 405 not_supported, 409 conflict, 500 internal_error, 502 upstream_error, 503 unavailable) |
agent_leased, with holder), or another loaded file has the same agent id (duplicate_agent_id, with agentId, filePath and loadedFilePath; stop that agent, or clone this file and load the clone, which gets an id of its own)Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/agents/load" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"filePath":"/home/me/agents/agent-1.adf"}'Create an agent from a template, then load it
/agents/createStudio's "new agent", headless: template instance → sealed identity with owner/runtime stamps and attestations → marked reviewed → directory tracked → loaded (and started with start: true). Needs a ready owner identity; 409 identity_not_ready carries identity so a client can offer create / restore / unlock. load_failed (422) means the file was created, reviewed and tracked but could not load (e.g. no provider configured): fix it, then POST /agents/load. With load: false and the header X-ADF-Client-Session, the new file is held open (not running) by that client session, which must be live (404 session_not_found otherwise); a holder body field is refused (400).
Header parameters
| Name | Type | Description |
|---|---|---|
X-ADF-Client-Session | string | The requesting client session (POST /client/sessions). With load: false it holds the new file as an open document. |
Request bodyapplication/json · CreateAgentBody · optional
| Field | Type | Description |
|---|---|---|
name | string | File name (<= 64 chars). Omitted: a generated adjective-plant name. |
directory | string | Absolute, existing directory. Default: settings.agentsFolder, else ~/Documents/adf-agents. |
template | string | Template id (GET /templates). Default: settings.defaultTemplateId, else |
provider | string | App provider id (must exist in settings.providers) |
model | string | |
start | boolean | |
identityDraftId | string | An identity draft (POST /identity/drafts): the new agent gets its DID. Consumed; an unknown or expired draft falls back to a fresh identity, reported in |
load | boolean | false: create the file and load nothing (Studio's FILE_CREATE, MESH_FOUND_AGENT). With |
replace | boolean | true: a file of that name exists and the user chose to replace it (Studio's save dialog asked): the new agent is written over it. Refused (409 |
Responses
| Status | Description | Body | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 201 | Created: loaded (started when start), left closed (load: false), or held open (load: false + holder) | CreateAgentResponse | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
identityDraftstring | What became of identityDraftId; unknown and adopt_failed mint a fresh DID warningsarray<string> | Sentences to show (a draft identity that was not used) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
Errors 400 · 401 · 403 · 404 · 409 · 422 · 500 · 503
| 400 | Invalid field (bad_request) | AgentCreateErrorResponse | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
runtimeobject | Whose runtime identity the daemon uses. 6 fields of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
staterequired | string | |
sourcerequired | string | |
reasonrequired | string | null | |
daemonRuntimeDidrequired | string | null | The daemon's own runtime DID |
daemonEncPublicKeyrequired | string | null | Base64 raw X25519 public key of the daemon's runtime-enc-key (what Studio lists in trustedDaemonEncKeys) |
messagerequired | string | One sentence for the UI |
storagerequiredbackupConfirmedrequiredpassphraseRequiredrequiredFile storage not unlocked: create/restore/unlock take a passphrase
keychainProblemThe daemon could not read this machine's OS keychain at start and runs on its passphrase file: why and what to do; null otherwise. Create, restore, import and trust-daemon answer 409 keychain_unavailable meanwhile (set ADF_SECRET_STORE=file to use the file on purpose).
messagerequiredWhat to do next
unauthorized)host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_originidentity_not_ready), the name is taken in that directory (name_taken), or a confirmed replace names a file another runtime runs (agent_leased)identity_not_readyname_takenagent_leasedtemplate_missing, template_unreviewed, template_invalid) or the new file could not load (load_failed)Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/agents/create" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"agent-1","template":"standard","start":true}'{
"agentId": "Xk3v9QpLm2",
"name": "agent-1",
"filePath": "/home/me/Documents/adf-agents/agent-1.adf",
"did": "did:key:z6Mk…",
"loaded": true,
"started": true
}Scan folders and autostart their reviewed agents
/agents/autostartSame rules as daemon boot: autostart agents that are reviewed and not password-protected; others are reported in skipped.
Request bodyapplication/json · AutostartBody · required
| Field | Type | Description |
|---|---|---|
trackedDirsrequired | array<string> | |
maxDepth | integer |
Responses
| Status | Description | Body | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | What was started, skipped and failed | AutostartReport | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
skippedrequiredarray<object> | 5 fields of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
filePathrequired | string | |
namerequired | string | |
reasonrequired | string | |
agentId | string | |
message | string | leased_elsewhere: which process on this machine runs the agent and what to do. |
failedrequired3 fields of failed
filePathrequired | string | |
namerequired | string | |
errorrequired | string |
Errors 400 · 401 · 403 · 500
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/agents/autostart" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"trackedDirs":["/home/me/agents"],"maxDepth":5}'{
"scanned": 2,
"started": [
{
"agentId": "Xk3v9QpLm2",
"filePath": "/home/me/agents/agent-1.adf",
"name": "agent-1",
"startupTriggered": true
}
],
"skipped": [
{
"filePath": "/home/me/agents/agent-2.adf",
"name": "agent-2",
"reason": "unreviewed"
}
],
"failed": []
}Review information for an .adf file
/agents/reviewStudio's FILE_CHECK_REVIEW: identity scenario, provider usability (the automatic provider check, honouring providerChecksEnabled), willRelocate and relocateTo. An open or running file is read through its own workspace.
Query parameters
| Name | Type | Description |
|---|---|---|
filePathrequired | string | Absolute path of the .adf file |
Responses
| Status | Description | Body | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Review summary | ReviewInfo | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
mcpServersrequiredarray<object> | triggersrequiredarray<object> | 3 fields of | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
typerequired | string | |
enabledrequired | boolean | |
targetCountrequired | integer |
codeExecutionrequiredmessagingrequired1 field of messaging
moderequired | string |
networkrequiredsecurityrequiredneedsReviewStudio's FILE_CHECK_REVIEW: not reviewed yet
claimedAccept only: the file was claimed (a fresh identity under this owner)
didAccept only: the agent DID afterwards
configThe agent's ADF v0.2 config (adf_config). Only the most used fields are listed; the full shape is the ADF spec's AgentConfig. Secret values never appear here.
lockedFieldsAccept only: the security-sensitive fields this accept locked against the agent's own edits
Errors 400 · 401 · 403 · 500
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/agents/review?filePath=/home/me/agents/agent-2.adf" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Mark an .adf file's agent as reviewed
/agents/review/acceptStudio's FILE_REVIEW_ACCEPT: optional model override, claim (or the identity provisioning deferred at open), auto-locked security fields, the reviewed mark. Move an untracked file into the agents folder afterwards with POST /files/relocate. Refused with 409 agent_leased while another runtime runs the file.
Request bodyapplication/json · ReviewAcceptBody · required
| Field | Type | Description | ||||||
|---|---|---|---|---|---|---|---|---|
filePathrequired | string | |||||||
claim | boolean | Claim & Open: a fresh identity under this owner. A legacy file password must be unlocked first (409 password_required). | ||||||
model | object | The model chosen in the review dialog (provider must be configured; 400 provider_unknown) | ||||||
2 fields of | ||||||||
providerrequired | string | |
model_idrequired | string |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Reviewed | ReviewInfo |
Fields as in ReviewInfo above. | ||
Errors 400 · 401 · 403 · 409 · 500
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 409 | The resource is in a state that does not allow this now | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/agents/review/accept" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"filePath":"/home/me/agents/agent-2.adf"}'A running agent's or open document's reference (id, file, config)
/agents/{id}Every /agents/{id} resource route (config, document, files, chat, inbox, outbox, timers, logs, tables, identity, meta, tasks) also reaches an open document: a file a client session holds open without running it (design D4). Runtime actions on one that is not running (chat, trigger, abort, interrupt, compact, loop changes, display state, approvals, asks, suspend) answer 409 agent_not_running. Writes through it are refused with 409 agent_leased while another runtime runs its file. While an open document's file is being moved (accept-relocate) every /agents/{id} route answers 409 file_moving.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Agent reference | AgentRef |
Fields as in AgentRef above. | ||
Errors 401 · 403 · 404
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/agents/agent-1" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Agent runtime status
/agents/{id}/statusPath parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Responses
| Status | Description | Body | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Status | AgentStatus | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
refusalsmap<string, string> | Why each modality not in support is refused, keyed image, audio or video. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Errors 401 · 403 · 404
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/agents/agent-1/status" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"{
"id": "Xk3v9QpLm2",
"filePath": "/home/me/agents/agent-1.adf",
"name": "agent-1",
"handle": "agent-1",
"autostart": true,
"runtimeState": "idle",
"targetState": null,
"loopCount": 1
}Agent vitals
/agents/{id}/vitalsStudio's overview card for one agent: header facts (context size, next wake, 7-day cost, model, age) and four levelled stats: Reach, Access and Autonomy (levels from config points, with the factors behind them) and Experience (a level from maturity counts). {id} names a loaded agent (id, handle or name, as every /agents/{id} route) or, when no loaded agent matches, a tracked agent that is not loaded (agent id or handle from its file). A loaded agent is read from its open workspace (live: true); any other file is read with a readonly open. Results are cached: a live agent's for at most 2 s and until its database changes, any other file's until its mtime or size changes. force=1 skips the cache. agentsSpawned counts tracked agents whose parent DID names this agent, from a fleet scan at most 30 s old (force=1 rescans). contextTokens and contextThreshold are present only for a loaded agent whose executor has reported usage; cost7dUsd only when some adf_loop row of the last 7 local days has a price (the row's recorded cost_usd; rows from before 2026-08-27 without one are priced from Studio's pricing table).
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Query parameters
| Name | Type | Description |
|---|---|---|
force | string | Skip the cache: |
Responses
| Status | Description | Body | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Vitals | AgentVitals | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
statsrequiredobject | 4 fields of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
reachrequired | object | Reach, Access or Autonomy: a capped level on a 1-20 scale. fill = clamp(points / max, 0, 1); level = 1 + round(19 * fill), so an empty config is Lv 1 and a maxed-out one Lv 20. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
9 fields of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
levelrequired | integer | ||||||||||||||||
pointsrequired | number | Points behind the level, after mitigations | |||||||||||||||
maxrequired | number | Points of a maxed-out config for this stat | |||||||||||||||
fillrequired | number | points / max, clamped: how much of the possible power the agent has | |||||||||||||||
openrequired | number | Points whose capability runs without approval (mitigations come off these first) | |||||||||||||||
gatedrequired | number | Points whose capability needs approval | |||||||||||||||
highrequired | boolean | True when open / max >= 0.6 (open level 12 or more): much of this runs without anyone asking | |||||||||||||||
rawPointsrequired | number | Sum of factor points, mitigations included | |||||||||||||||
factorsrequired | array<AgentStatFactor> | ||||||||||||||||
5 fields of | |||||||||||||||||
idrequired | string | Stable id, e.g. |
labelrequired | string | |
pointsrequired | number | Points this factor adds; negative for mitigations; 0 for an item past its kind's cap (7th MCP server, 4th chat adapter), listed but not counted |
gatedrequired | boolean | True when the capability needs human approval |
configPathrequired | string | Config path (or table) that controls this factor |
accessrequiredReach, Access or Autonomy: a capped level on a 1-20 scale. fill = clamp(points / max, 0, 1); level = 1 + round(19 * fill), so an empty config is Lv 1 and a maxed-out one Lv 20. max is the sum of every capped positive factor of the stat (counts such as MCP servers and chat adapters only count their heaviest few). Gated points count toward the level. points is open + gated.
autonomyrequiredReach, Access or Autonomy: a capped level on a 1-20 scale. fill = clamp(points / max, 0, 1); level = 1 + round(19 * fill), so an empty config is Lv 1 and a maxed-out one Lv 20. max is the sum of every capped positive factor of the stat (counts such as MCP servers and chat adapters only count their heaviest few). Gated points count toward the level. points is open + gated.
experiencerequiredExperience. xpForLevel(L) = 5 * (L - 1)^2.25; level = largest L with xpForLevel(L) <= score.
7 fields of experience · AgentExperienceStat
levelrequired | integer | ||||||||||||||||
progressrequired | number | Progress within the current level | |||||||||||||||
scorerequired | number | Total XP (sum of signal XP) | |||||||||||||||
levelStartrequired | number | XP at which the current level starts | |||||||||||||||
nextLevelAtrequired | number | XP at which the next level starts | |||||||||||||||
breakdownrequired | array<object> | ||||||||||||||||
4 fields of | |||||||||||||||||
idrequired | string | |
labelrequired | string | |
valuerequired | number | Raw count |
xprequired | number | XP this signal adds |
nextLevelrequiredWhat one more level takes (xp = nextLevelAt - score), in units of the cheapest signals
5 fields of nextLevel
xprequired | number | |
contextsrequired | integer | Contexts of work worth the remaining XP |
memoryTokensrequired | integer | Memory tokens worth the remaining XP |
skillsrequired | integer | Skills worth the remaining XP |
hintrequired | string |
maturityrequiredRaw maturity counts read from the agent's file.
9 fields of maturity · AgentMaturity
contextsWorkedrequired | number | Contexts of work over every loop (main, side, deleted): archived loop snapshots in adf_audit (one context at half the loop's compaction threshold or more, else its share) or live compaction summaries when loop audit is off, plus each live loop's current fill as a 0..1 share of its compaction threshold |
filesWrittenrequired | integer | adf_files rows changed after the agent was created, |
memoryTokensrequired | integer | Approximate tokens in |
localTablesrequired | integer |
|
localRowsrequired | integer | Rows across |
skillsrequired | integer | Distinct skills the agent installed or changed |
agentsSpawnedrequired | integer | null | Tracked agents whose adf_parent_did names this agent; null when no fleet scan has run |
messagesrequired | integer | Loop messages ever written, every loop current and past (adf_loop's shared AUTOINCREMENT high-water mark; compaction, clears and loop deletion do not lower it) |
ageDaysrequired | number | Days since adf_created_at |
Errors 400 · 401 · 403 · 404 · 409 · 500
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 409 | The agent is loaded without an .adf file; vitals are read from the file | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/agents/agent-1/vitals" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Agent activity
/agents/{id}/activityThe lower sections of Studio's agent overview: the next three timer wakes (raw lambda and input, or loop and prompt), 14 local days of messages and cost per day, and what the file holds (mind/ files and skills with approximate tokens, local_* tables with rows). {id} resolves as in GET /agents/{id}/vitals. Everything is read from the .adf file. Messages per day: adf_loop rows of every role by created_at, plus compacted rows archived in adf_audit (metadata only, never the archived data): each archive's entry_count is spread evenly over an estimated span ending at its created_at and at most 24 h long, and days that include such counts have estimated: true. Cost per day: the sum of the day's priced loop rows; costPartial when some call had no recorded price or was compacted. The first read scans the window's loop rows once; later reads add only new rows. Skills follow the vitals rule: written more than 10 s after adf_created_at, skills-registry.json excluded. Cached like vitals (and per local day); force=1 skips the cache. Pending approvals, asks and unread counts are not here: read GET /agents/{id}/asks and GET /agents/{id}/inbox.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Query parameters
| Name | Type | Description |
|---|---|---|
force | string | Skip the cache: |
Responses
| Status | Description | Body | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Activity | AgentActivity | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
dailyrequiredarray<AgentActivityDay> | 14 local days, oldest first; the last is today 5 fields of | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
daterequired | string | Local YYYY-MM-DD |
messagesrequired | integer | adf_loop rows of every role created that day, plus the day's estimated share of compacted rows archived in adf_audit |
estimated | boolean | Some of the day's messages are compacted history whose timing is estimated (spread evenly over a span ending at the archive's creation) |
costUsd | number | USD of the day's priced adf_loop rows (cost_usd in the row's usage record); absent when none had a price |
costPartial | boolean | Some calls that day had no recorded price, or were compacted (their cost is not recorded); costUsd is a lower bound |
contentsrequiredWhat the file holds, in three groups. Tokens are approximate (bytes / 4, rounded) and given for mind and skills only: table data is rarely read into context.
3 fields of contents
mindrequired | object | Files under mind/ | |||||||||||||||||||||||||||
4 fields of | |||||||||||||||||||||||||||||
filesrequired | integer | |||||||||||||
tokensrequired | integer | SUM(size) / 4, rounded, the seeded mind/log.md header taken off that file | ||||||||||||
updatedThisWeekrequired | integer | mind/ files whose updated_at is within the last 7 days | ||||||||||||
stratarequired | object | Current mind/ tokens (size / 4, rounded, the seeded mind/log.md header taken off that file) split by each file's updated_at. A boundary belongs to the younger band. | ||||||||||||
4 fields of | ||||||||||||||
olderrequired | integer | Last updated more than 90 days ago |
quarterrequired | integer | Last updated more than 30 and at most 90 days ago |
monthrequired | integer | Last updated more than 7 and at most 30 days ago |
weekrequired | integer | Last updated at most 7 days ago |
skillsrequiredSkills the agent installed or changed (the Experience stat rule)
2 fields of skills
countrequired | integer | |
tokensrequired | integer | Size of every file under those skills' directories / 4; registry entries without files add 0 |
tablesrequiredlocal_* tables (at most 50 read)
2 fields of tables
countrequired | integer | |
rowsrequired | integer | Total rows |
Errors 400 · 401 · 403 · 404 · 409 · 500
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 409 | The agent is loaded without an .adf file; activity is read from the file | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/agents/agent-1/activity" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Start an agent, loading it from a tracked folder when needed
/agents/{id}/startid may also name an agent that is not loaded: an .adf path, or an id / handle / name found in the tracked folders. The daemon loads it (review gate applies: 403) and starts it; loaded says whether it did. startupTriggered is true when the agent's start state fired its startup event. An identifier that matches several files answers 409 ambiguous_agent with the candidates: start one by its file path. No body. With preflight=1 (a client-initiated start, as Studio's AGENT_START; autostart never asks for it) an agent that is not loaded yet has its provider checked first: a provider this daemon does not have answers 409 provider_missing, a failing check of a provider that needs a key it does not have 409 provider_unconfigured, any other failing check 409 provider_check_failed. Nothing is loaded then. When the agent's own provider key is stored but locked here (password or envelope), the check is skipped, the start goes on and the answer carries preflight: {code: credentials_locked, message}. A file with the same agent id as a loaded agent answers 409 duplicate_agent_id (see POST /agents/load).
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Query parameters
| Name | Type | Description |
|---|---|---|
preflight | string |
|
hasUserMessage | string |
|
Responses
| Status | Description | Body | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Started | StartAgentResponse | |||||||||||||||
| |||||||||||||||||
Errors 401 · 403 · 404 · 409 · 500
| 401 | Missing or wrong bearer token (unauthorized) | ||||||||||||||||||||||||||||||||||||||||
| 403 | The .adf must be reviewed on this machine before it loads (AGENT_REVIEW_REQUIRED), or the request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin) | ReviewRequiredResponse | ErrorResponse | |||||||||||||||||||||||||||||||||||||||
Option 2object | Every error body. Some routes add fields (e.g. 2 fields of | ||||||||||||||||||||||||||||||||||||||||
errorrequired | string | Human-readable message |
code | string | Stable machine-readable code. Every error body has one: route-specific where listed, else the status default (400 bad_request, 403 forbidden, 404 not_found, 405 not_supported, 409 conflict, 500 internal_error, 502 upstream_error, 503 unavailable) |
ambiguous_agent), the preflight provider check failed (provider_missing, provider_unconfigured, provider_check_failed), another process runs the agent (agent_leased), another loaded file has the same agent id (duplicate_agent_id) or the agent is being stopped while it starts (agent_not_running)Option 1 | object | Every error body. Some routes add fields (e.g. | |||||||||||||||||||||
3 fields of | |||||||||||||||||||||||
errorrequired | string | Human-readable message | |||||||||
code | string | Stable machine-readable code. Every error body has one: route-specific where listed, else the status default (400 bad_request, 403 forbidden, 404 not_found, 405 not_supported, 409 conflict, 500 internal_error, 502 upstream_error, 503 unavailable) | |||||||||
candidatesrequired | array<object> | ||||||||||
3 fields of | |||||||||||
namerequired | string | |
handlerequired | string | null | |
filePathrequired | string |
Option 2Every error body. Some routes add fields (e.g. identity, coveredBy, agentId).
2 fields of Option 2 · ErrorResponse
errorrequired | string | Human-readable message |
code | string | Stable machine-readable code. Every error body has one: route-specific where listed, else the status default (400 bad_request, 403 forbidden, 404 not_found, 405 not_supported, 409 conflict, 500 internal_error, 502 upstream_error, 503 unavailable) |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/agents/agent-1/start" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"{
"success": true,
"loaded": false,
"startupTriggered": true,
"agent": {
"id": "Xk3v9QpLm2",
"filePath": "/home/me/agents/agent-1.adf",
"name": "agent-1",
"autostart": true,
"runtimeState": "idle",
"targetState": null,
"loopCount": 1
}
}Stop and unload an agent
/agents/{id}/stopImmediate (the owner's Off): a running turn ends at once and starts no further tool, every host shell the agent started is killed, then the agent is unloaded (its file stays on disk). No body.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Responses
| Status | Description | Body | |||
|---|---|---|---|---|---|
| 200 | Stopped and unloaded | SuccessResponse | |||
| |||||
Errors 401 · 403 · 404 · 500
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/agents/agent-1/stop" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"{
"success": true
}Unload an agent (alias of stop)
/agents/{id}/unloadNo body.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Responses
| Status | Description | Body | |||
|---|---|---|---|---|---|
| 200 | Unloaded | SuccessResponse | |||
| |||||
Errors 401 · 403 · 404 · 500
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/agents/agent-1/unload" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"{
"success": true
}Abort the current turn without unloading
/agents/{id}/abortA hard stop: the executor of main (or the named inner loop) is left stopped and runs no further turns, triggers or timers until the agent is reloaded. To end a turn and keep working, use /interrupt. Chats still queued behind the turn are discarded, never silently: a chat.discarded event names their turnIds and a System notice lands in the loop. Unknown loop 404; a loop with no running executor 409.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Query parameters
| Name | Type | Description |
|---|---|---|
loop | string | Cognition loop to address. Absent = main. Unknown loops answer 404. |
Request bodyapplication/json · LoopBody · optional
Optional; ?loop= wins.
| Field | Type | Description |
|---|---|---|
loop | string | Cognition loop; absent = main. The |
Responses
| Status | Description | Body | ||||||
|---|---|---|---|---|---|---|---|---|
| 200 | Aborted | AbortResponse | ||||||
| ||||||||
Errors 401 · 403 · 404 · 409 · 500
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 409 | The resource is in a state that does not allow this now | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/agents/agent-1/abort" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Interrupt the running turn and leave the loop idle
/agents/{id}/interruptEnds main's (or the named loop's) running turn and sets that executor idle; it keeps accepting chats, triggers and timers. The model request is cancelled (text it already streamed is saved as the model's reply, its blocks marked interrupted), running tools get the abort (host shells are killed, MCP requests cancelled), the turn's pending approval or question ends with no decision, every tool call without a result gets an interrupted one, and the loop shows "Turn interrupted". Unlike /abort it never stops the executor, and chats queued behind the turn are kept and run next. Studio's Stop and the terminal app's Esc call it. interrupted is false when nothing was running; 409 when the loop is stopped or errored.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Query parameters
| Name | Type | Description |
|---|---|---|
loop | string | Cognition loop to address. Absent = main. Unknown loops answer 404. |
Request bodyapplication/json · LoopBody · optional
Optional; ?loop= wins.
| Field | Type | Description |
|---|---|---|
loop | string | Cognition loop; absent = main. The |
Responses
| Status | Description | Body | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Interrupted (or nothing to interrupt) | InterruptResponse | |||||||||
| |||||||||||
Errors 401 · 403 · 404 · 409 · 500
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 409 | The resource is in a state that does not allow this now | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/agents/agent-1/interrupt" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'{
"success": true,
"interrupted": true,
"loop": "main"
}Move the running agent's display state
/agents/{id}/stateFleet-map semantics, not persisted to the .adf: a config.state change via PUT …/config does not move the running agent; this does. off stops and unloads the agent, as Studio does (also when the agent switches itself off): the answer is 200, the unload follows within moments, and from then on its /agents/{id}/* routes answer 404 until it is started again (POST /agents/{id}/start or /agents/load).
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Request bodyapplication/json · DisplayStateBody · required
| Field | Type | Description |
|---|---|---|
staterequired | string | Display (fleet-map) state of an agent |
Responses
| Status | Description | Body | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | State set | DisplayStateResponse | |||||||||
| |||||||||||
Errors 400 · 401 · 403 · 404 · 500
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/agents/agent-1/state" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"state":"idle"}'Read the agent config
/agents/{id}/configPath parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Responses
| Status | Description | Body | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Config | AgentConfigResponse | |||||||||
| |||||||||||
Errors 401 · 403 · 404
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/agents/agent-1/config" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Replace the agent config
/agents/{id}/configValidated against the ADF config schema, persisted and applied to the running executor, trigger evaluator and loops. A changed state does not move the running agent (it is the persisted start state); use POST …/state. Owner locks (locked, locked_fields) bind the agent's own sys_update_config, not this route.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Query parameters
| Name | Type | Description |
|---|---|---|
baseRevision | integer | W3-F: write only over this revision of the resource (from a read or the last write). Another current revision answers 409 |
Header parameters
| Name | Type | Description |
|---|---|---|
If-Match | string | W3-F: the base revision, as |
Request bodyapplication/json · AgentConfig · required
The agent's ADF v0.2 config (adf_config). Only the most used fields are listed; the full shape is the ADF spec's AgentConfig. Secret values never appear here.
Fields as in AgentConfig above.
Responses
| Status | Description | Body | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Saved | AgentConfigUpdateResponse | |||||||||||||||||||||
| |||||||||||||||||||||||
Errors 400 · 401 · 403 · 404 · 409 · 500
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | ||||||||||||||||||||||||||||||||||
| 401 | Missing or wrong bearer token (unauthorized) | ||||||||||||||||||||||||||||||||||
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | ||||||||||||||||||||||||||||||||||
| 404 | Unknown agent (or the named resource: loop, task, file, …) | ||||||||||||||||||||||||||||||||||
| 409 | W3-F: the resource changed since the write's base revision (stale_revision); nothing was written. A write to a document another runtime holds answers 409 agent_leased (or file_moving during a move) instead. | StaleRevisionError | |||||||||||||||||||||||||||||||||
sizeinteger | null | Current size in bytes (null for config) hashrequiredstring | sha1 of the current content ( | |||||||||||||||||||||||||||||||||
| 500 | Unexpected runtime failure | ||||||||||||||||||||||||||||||||||
Error bodies use the error format.
Example
curl -X PUT "http://127.0.0.1:7385/agents/agent-1/config" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"adf_version": "0.2",
"id": "string",
"name": "string",
"description": "string",
"state": "active",
"autonomous": true,
"model": {
"provider": "anthropic",
"model_id": "claude-sonnet-4-5"
},
"instructions": "string",
"context": {},
"tools": [],
"triggers": {},
"security": {},
"limits": {},
"messaging": {},
"metadata": {}
}'The agent's tool catalog
/agents/{id}/toolsEvery built-in tool the main registry holds, every MCP tool its servers advertise and every declared tool, sorted by name, with declared state and description (what sys_get_config gives the agent). Read-only: change tools with PUT …/config.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Responses
| Status | Description | Body | |||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Tools | AgentToolsResponse | |||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||
Errors 401 · 403 · 404 · 500
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/agents/agent-1/tools" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"List metadata entries (adf_meta)
/agents/{id}/metaPath parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Responses
| Status | Description | Body | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Entries | MetaResponse | ||||||||||||||||||
| ||||||||||||||||||||
Errors 401 · 403 · 404
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/agents/agent-1/meta" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Set a metadata value
/agents/{id}/meta/{key}Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
keyrequired | string | Metadata key |
Request bodyapplication/json · MetaSetBody · required
| Field | Type | Description |
|---|---|---|
valuerequired | string | |
protection | string |
Responses
| Status | Description | Body | ||||||
|---|---|---|---|---|---|---|---|---|
| 200 | Saved | AgentSuccess | ||||||
| ||||||||
Errors 400 · 401 · 403 · 404 · 500
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X PUT "http://127.0.0.1:7385/agents/agent-1/meta/KEY" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"value":"42"}'{
"agentId": "Xk3v9QpLm2",
"success": true
}Delete a metadata value
/agents/{id}/meta/{key}Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
keyrequired | string | Metadata key |
Responses
| Status | Description | Body | ||||||
|---|---|---|---|---|---|---|---|---|
| 200 | success is false when nothing was deleted | AgentSuccess | ||||||
| ||||||||
Errors 401 · 403 · 404 · 500
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X DELETE "http://127.0.0.1:7385/agents/agent-1/meta/KEY" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"{
"agentId": "Xk3v9QpLm2",
"success": true
}Set a metadata key's protection
/agents/{id}/meta/{key}/protectionPath parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
keyrequired | string | Metadata key |
Request bodyapplication/json · MetaProtectionBody · required
| Field | Type | Description |
|---|---|---|
protectionrequired | string |
Responses
| Status | Description | Body | ||||||
|---|---|---|---|---|---|---|---|---|
| 200 | Saved | AgentSuccess | ||||||
| ||||||||
Errors 400 · 401 · 403 · 404 · 500
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X PATCH "http://127.0.0.1:7385/agents/agent-1/meta/KEY/protection" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"protection":"none"}'{
"agentId": "Xk3v9QpLm2",
"success": true
}List the agent's local tables
/agents/{id}/tablesPath parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Responses
| Status | Description | Body | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Tables | TablesResponse | |||||||||||||||
| |||||||||||||||||
Errors 401 · 403 · 404
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/agents/agent-1/tables" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Read rows of a local table
/agents/{id}/tables/{table}Only local_* tables and adf_audit are readable (anything else: 400 "Invalid table name"); read the inbox and outbox through their own routes. limit default 100 (1–1000), offset default 0.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
tablerequired | string | Local table name ( |
Query parameters
| Name | Type | Description |
|---|---|---|
limit | integer | Maximum rows to return |
offset | integer | Rows to skip |
Responses
| Status | Description | Body | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Rows | TableQueryResponse | |||||||||
| |||||||||||
Errors 400 · 401 · 403 · 404 · 500
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/agents/agent-1/tables/TABLE" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Drop a local table
/agents/{id}/tables/{table}Only local_* tables can be dropped.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
tablerequired | string | Local table name ( |
Responses
| Status | Description | Body | ||||||
|---|---|---|---|---|---|---|---|---|
| 200 | Dropped | AgentSuccess | ||||||
| ||||||||
Errors 401 · 403 · 404 · 500
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X DELETE "http://127.0.0.1:7385/agents/agent-1/tables/TABLE" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"{
"agentId": "Xk3v9QpLm2",
"success": true
}Recent agent logs (adf_logs)
/agents/{id}/logslimit default 50 (clamped 1–500).
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Query parameters
| Name | Type | Description |
|---|---|---|
limit | integer | Maximum rows to return |
origin | string | Only this origin (e.g. |
event | string | Only this event name |
Responses
| Status | Description | Body | |||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Log rows, newest last | AgentLogsResponse | |||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||
Errors 400 · 401 · 403 · 404
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/agents/agent-1/logs" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Clear the agent's logs
/agents/{id}/logsPath parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Responses
| Status | Description | Body | ||||||
|---|---|---|---|---|---|---|---|---|
| 200 | Cleared | AgentSuccess | ||||||
| ||||||||
Errors 401 · 403 · 404 · 500
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 500 | Unexpected runtime failure |
Error bodies use the error format.
Example
curl -X DELETE "http://127.0.0.1:7385/agents/agent-1/logs" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"{
"agentId": "Xk3v9QpLm2",
"success": true
}Log rows after an id (tail)
/agents/{id}/logs/afterPath parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Query parameters
| Name | Type | Description |
|---|---|---|
afterIdrequired | integer | Return rows with id greater than this |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Newer rows | AgentLogsResponse |
Fields as in AgentLogsResponse above. | ||
Errors 400 · 401 · 403 · 404
| 400 | Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/agents/agent-1/logs/after?afterId=AFTER_ID" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Token usage from the agent's persisted loop rows
/agents/{id}/usageA rollup of adf_loop.tokens (compaction summary rows included). It excludes model_invoke and any provider call that created no loop row; the per-call usage/cost channel is the llm.completed umbilical event. input already includes cacheRead and cacheWrite; total = input + output.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Responses
| Status | Description | Body | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Usage | AgentUsageResponse | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
byModelrequiredarray<object> | 7 fields of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
inputrequired | integer | |
outputrequired | integer | |
cacheReadrequired | integer | |
cacheWriterequired | integer | |
totalrequired | integer | |
modelrequired | string | |
rowsrequired | integer |
Errors 401 · 403 · 404
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/agents/agent-1/usage" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Header read: document, config, status text
/agents/{id}/headerStudio's DOC_GET_HEADER in one call, for a running agent or an open document.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Responses
| Status | Description | Body | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Header | AgentHeaderResponse | ||||||||||||
| ||||||||||||||
Errors 401 · 403 · 404
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/agents/agent-1/header" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Batch read: header, token figures and the last 200 chat entries
/agents/{id}/batchStudio's DOC_GET_BATCH in one call (a file switch), for a running agent or an open document.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Responses
| Status | Description | Body | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Batch | AgentBatchResponse | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
llmMessagesrequiredarray<any> | earlierCountrequiredinteger | totalrequiredinteger | configRevisioninteger | W3-F: the revision of documentRevisioninteger | W3-F: the revision of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Errors 401 · 403 · 404
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/agents/agent-1/batch" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Fold the WAL into the .adf (save)
/agents/{id}/checkpointStudio's FILE_SAVE. SQLite persists every write; this folds the write-ahead log into the file.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Loaded agent: its id, handle or name. |
Responses
| Status | Description | Body | |||
|---|---|---|---|---|---|
| 200 | Checkpointed | SuccessResponse | |||
| |||||
Errors 401 · 403 · 404 · 409
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown agent (or the named resource: loop, task, file, …) | |
| 409 | The resource is in a state that does not allow this now |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/agents/agent-1/checkpoint" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"{
"success": true
}