On this page

List loaded agents

GET/agents

Operation listAgentsAuthBearer token

Responses

StatusDescriptionBody
200Loaded agentsAgentList · array<AgentSummary>
idrequiredstring
filePathrequiredstring | null
namerequiredstring
handlestring
autostartrequiredboolean
Errors 401 · 403
401Missing or wrong bearer token (unauthorized)
403The 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

Request
curl "http://127.0.0.1:7385/agents" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Load an agent from an .adf file

POST/agents/load

Operation loadAgentAuthBearer token

Loading 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

FieldTypeDescription
filePathrequiredstring

Absolute path of the .adf file

requireReviewboolean

Enforce the review gate for this load (direct loads bypass it by default)

Responses

StatusDescriptionBody
200The loaded agentAgentRef
idrequiredstring
filePathrequiredstring | null
configrequiredobject

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.

25 fields of config · AgentConfig
adf_versionrequiredstring

Value 0.2

idrequiredstring

Agent id (stable, the daemon addresses the agent by it)

namerequiredstring
descriptionrequiredstring
handlestring
iconstring
staterequiredstring

Display (fleet-map) state of an agent

One of active, idle, hibernate, suspended, off

autonomousrequiredboolean
autostartboolean
modelrequiredobject
9 fields of model · ModelConfig
providerrequiredstring

Provider id (app provider or one of the agent's own providers)

model_idrequiredstring
temperaturenumber | null
max_tokensinteger | null
top_pnumber | null
reasoningobject

Provider-agnostic reasoning ("thinking") config

multimodalobject
3 fields of multimodal
imageboolean
audioboolean
videoboolean
paramsarray<object>
2 fields of params
keyrequiredstring
valuerequiredstring
provider_paramsobject
instructionsrequiredstring
contextrequiredobject

compact_threshold, max_request_media_files, max_request_media_mb, compaction_model, audit, dynamic_instructions

toolsrequiredarray<object>

Tool declarations

5 fields of tools
namerequiredstring
enabledrequiredboolean
visibleboolean
restrictedboolean
lockedboolean
triggersrequiredmap<string, TriggerConfig>

on_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
enabledrequiredboolean
targetsrequiredarray<TriggerTarget>
11 fields of targets
scoperequiredstring

One of agent, system

lambdastring

System scope: path/file.ts:functionName

commandstring

System scope: shell command (alternative to lambda)

warmboolean
filterobject
debounce_msinteger
interval_msinteger
batch_msinteger
batch_countinteger
lockedboolean
loopstring

Cognition loop this target wakes; absent = main

lockedboolean
securityrequiredobject
limitsrequiredobject
messagingrequiredobject

mode (proactive | respond_only | listen_only), receive, network, …

mcpobject
2 fields of mcp
serversrequiredarray<McpServerConfig>
20 fields of servers
namerequiredstring
transportrequiredstring

One of stdio, http

commandstring
argsarray<string>
urlstring
oauthboolean
headersmap<string, string>
header_envarray<object>
bearer_token_env_varstring
envmap<string, string>
env_keysarray<string>
env_schemaarray<object>
npm_packagestring
pypi_packagestring
sourcestring
available_toolsarray<object>
tool_call_timeout_msinteger
restrictedboolean
run_locationstring

One of host, shared

credential_filesarray<object>
3 fields of credential_files
pathrequiredstring
requiredboolean
write_backboolean
new_tools_restrictedboolean
adaptersmap<string, AdapterInstanceConfig>

Channel adapters by type

4 fields of adapters
enabledrequiredboolean
configobject

Adapter-specific settings (no secrets: tokens are credentials)

policyobject
limitsobject
1 field of limits
max_attachment_sizeinteger

Bytes

providersarray<AgentProviderConfig>
8 fields of providers
idrequiredstring

anthropic, openai, … or custom:<id>

typerequiredstring

One of anthropic, openai, openai-compatible, openrouter

namerequiredstring
baseUrlrequiredstring
presetstring
defaultModelstring
paramsarray<object>
2 fields of params
keyrequiredstring
valuerequiredstring
requestDelayMsinteger
loopsarray<LoopConfig>

Inner (side) loops; main is implicit

8 fields of loops
namerequiredstring

pattern: ^[a-z0-9][a-z0-9_-]{0,31}$

goalrequiredstring

Becomes the loop's instructions

enabledrequiredboolean
autostartboolean
autonomousboolean
modelobject

Fields as in ModelConfig above.

compact_thresholdinteger | null
toolsarray<string>

Absolute allow-list, intersected with the host's enabled tools

ws_connectionsarray<object>
servingobject
locked_fieldsarray<string>
metadatarequiredobject

created_at, updated_at, author, tags, version

runningboolean

GET /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
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The .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 1object

The .adf has not been reviewed on this machine; review it (GET /agents/review) and accept (POST /agents/review/accept) first.

4 fields of Option 1 · ReviewRequiredResponse
errorrequiredstring
coderequiredstring

Value AGENT_REVIEW_REQUIRED

agentIdrequiredstring
filePathrequiredstring
Option 2object

Every error body. Some routes add fields (e.g. identity, coveredBy, agentId).

2 fields of Option 2 · ErrorResponse
errorrequiredstring

Human-readable message

codestring

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)

409Not loaded: another process runs the agent (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)
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

POST/agents/create

Operation createAgentAuthBearer token

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

NameTypeDescription
X-ADF-Client-Sessionstring

The requesting client session (POST /client/sessions). With load: false it holds the new file as an open document.

Request bodyapplication/json · CreateAgentBody · optional

FieldTypeDescription
namestring

File name (<= 64 chars). Omitted: a generated adjective-plant name.

directorystring

Absolute, existing directory. Default: settings.agentsFolder, else ~/Documents/adf-agents.

templatestring

Template id (GET /templates). Default: settings.defaultTemplateId, else standard.

providerstring

App provider id (must exist in settings.providers)

modelstring
startboolean

default: false

identityDraftIdstring

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 identityDraft and warnings.

loadboolean

false: create the file and load nothing (Studio's FILE_CREATE, MESH_FOUND_AGENT). With holder, the file is held as an open document.

default: true

replaceboolean

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 name_taken) while that file runs or is open. Without the owner identity the agent is still made, its identity not sealed to an owner; warnings says so.

default: false

Responses

StatusDescriptionBody
201Created: loaded (started when start), left closed (load: false), or held open (load: false + holder)CreateAgentResponse
agentIdrequiredstring
namerequiredstring
filePathrequiredstring
didrequiredstring
startedrequiredboolean
loadedrequiredboolean

Loaded in the runtime (false with load: false)

documentobject

An open document (design D4): an .adf held open by client sessions, with or without a runtime on it.

8 fields of document · OpenDocument
agentIdrequiredstring
filePathrequiredstring
namerequiredstring
runningrequiredboolean
needsPasswordrequiredboolean

Legacy whole-file password, not unlocked: prompt, then POST /agents/{id}/identity/password/unlock

holdersrequiredinteger
nameChangedFromstring
readOnlystring

Another runtime runs the file: it opened read-only (no open step wrote it), writes are refused; the sentence names the holder

identityDraftstring

What became of identityDraftId; unknown and adopt_failed mint a fresh DID

One of adopted, unknown, adopt_failed

warningsarray<string>

Sentences to show (a draft identity that was not used)

Errors 400 · 401 · 403 · 404 · 409 · 422 · 500 · 503
400Invalid field (bad_request)AgentCreateErrorResponse
errorrequiredstring
coderequiredstring

One of bad_request, identity_not_ready, name_taken, template_missing, template_unreviewed, template_invalid, password_required, wrong_password, load_failed, agent_leased

identityobject
10 fields of identity · IdentityStatus
statusrequiredstring

One of none, locked, restore-needed, ready

ownerDidrequiredstring | null
runtimeDidrequiredstring | null

The runtime DID the daemon signs and stamps with: ADF Studio's when runtime.state is adopted, else the daemon's own

trustobject

K12: whether the owner trusts this daemon's key (trustedDaemonEncKeys). not-applicable: the daemon reads the OS keychain and shares ADF Studio's runtime identity instead.

3 fields of trust · DaemonTrustStatus
staterequiredstring

One of trusted, not-trusted, not-applicable

labelrequiredstring | null

Slot label daemon:<fingerprint> of the daemon key; null without a key file.

messagerequiredstring
runtimeobject

Whose runtime identity the daemon uses. adopted: ADF Studio's, from a verified OS keychain entry for this settings file. absent: no such entry. rejected: an entry exists but failed verification (reason). unavailable: no usable OS keychain. In every state but adopted the daemon runs as its own runtime, and Studio-made agents' credentials unlock through the trusted-daemon key daemonEncPublicKey.

6 fields of runtime · DaemonRuntimeAdoption
staterequiredstring

One of adopted, absent, rejected, unavailable

sourcerequiredstring

One of studio, daemon

reasonrequiredstring | null

One of malformed, unsupported_version, no_owner, owner_mismatch, bad_signing_key, subject_mismatch, bad_delegation, runtime_did_mismatch, enc_key_mismatch, scope_mismatch, null

daemonRuntimeDidrequiredstring | null

The daemon's own runtime DID

daemonEncPublicKeyrequiredstring | null

Base64 raw X25519 public key of the daemon's runtime-enc-key (what Studio lists in trustedDaemonEncKeys)

messagerequiredstring

One sentence for the UI

storagerequiredstring

One of keychain, file

backupConfirmedrequiredboolean
passphraseRequiredrequiredboolean

File storage not unlocked: create/restore/unlock take a passphrase

keychainProblemstring | null

The 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).

messagerequiredstring

What to do next

401Missing or wrong bearer token (unauthorized)
403The 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
404X-ADF-Client-Session names no live client session
409Owner identity not ready (identity_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_leasedAgentCreateErrorResponse
422The template was refused (template_missing, template_unreviewed, template_invalid) or the new file could not load (load_failed)AgentCreateErrorResponse
500Unexpected runtime failure
503The subsystem is not configured on this daemon

Error bodies use the error format.

Example

Request
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}'
Response 201
{
  "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

POST/agents/autostart

Operation autostartAgentsAuthBearer token

Same rules as daemon boot: autostart agents that are reviewed and not password-protected; others are reported in skipped.

Request bodyapplication/json · AutostartBody · required

FieldTypeDescription
trackedDirsrequiredarray<string>
maxDepthinteger

Responses

StatusDescriptionBody
200What was started, skipped and failedAutostartReport
scannedrequiredinteger

.adf files found

startedrequiredarray<object>
4 fields of started
agentIdrequiredstring
filePathrequiredstring
namerequiredstring
startupTriggeredrequiredboolean
skippedrequiredarray<object>
5 fields of skipped
filePathrequiredstring
namerequiredstring
reasonrequiredstring

One of already_loaded, not_autostart, password_protected, unreviewed, leased_elsewhere

agentIdstring
messagestring

leased_elsewhere: which process on this machine runs the agent and what to do.

failedrequiredarray<object>
3 fields of failed
filePathrequiredstring
namerequiredstring
errorrequiredstring
Errors 400 · 401 · 403 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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}'
Response 200
{
  "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

GET/agents/review

Operation getAgentReviewAuthBearer token

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

NameTypeDescription
filePathrequiredstring

Absolute path of the .adf file

example: /home/me/agents/agent-2.adf

Responses

StatusDescriptionBody
200Review summaryReviewInfo
agentIdrequiredstring
filePathrequiredstring
reviewedrequiredboolean
summaryrequiredobject

What the agent can do, as the review dialog shows it (Studio's AgentConfigSummary).

13 fields of summary · ReviewSummary
namerequiredstring
descriptionrequiredstring
iconstring
identityrequiredobject

agentDid, fileOwnerDid, ownerIsYou, scenario (mine | recognized | foreign | unclaimed), needsClaim, …

computeTierrequiredstring

One of shared, isolated, host

autostartrequiredboolean
toolsrequiredarray<object>
3 fields of tools
namerequiredstring
enabledrequiredboolean
notablerequiredboolean
mcpServersrequiredarray<object>
triggersrequiredarray<object>
3 fields of triggers
typerequiredstring
enabledrequiredboolean
targetCountrequiredinteger
codeExecutionrequiredboolean
messagingrequiredobject
1 field of messaging
moderequiredstring
networkrequiredobject
securityrequiredobject
needsReviewboolean

Studio's FILE_CHECK_REVIEW: not reviewed yet

claimedboolean

Accept only: the file was claimed (a fresh identity under this owner)

didstring | null

Accept only: the agent DID afterwards

configobject

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.

lockedFieldsarray<string>

Accept only: the security-sensitive fields this accept locked against the agent's own edits

Errors 400 · 401 · 403 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

POST/agents/review/accept

Operation acceptAgentReviewAuthBearer token

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

FieldTypeDescription
filePathrequiredstring
claimboolean

Claim & Open: a fresh identity under this owner. A legacy file password must be unlocked first (409 password_required).

modelobject

The model chosen in the review dialog (provider must be configured; 400 provider_unknown)

2 fields of model
providerrequiredstring
model_idrequiredstring

Responses

StatusDescriptionBody
200ReviewedReviewInfo

Fields as in ReviewInfo above.

Errors 400 · 401 · 403 · 409 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
409The resource is in a state that does not allow this now
500Unexpected runtime failure

Error bodies use the error format.

Example

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

GET/agents/{id}

Operation getAgentAuthBearer token

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

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Responses

StatusDescriptionBody
200Agent referenceAgentRef

Fields as in AgentRef above.

Errors 401 · 403 · 404
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/agents/agent-1" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Agent runtime status

GET/agents/{id}/status

Operation getAgentStatusAuthBearer token

Path parameters

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Responses

StatusDescriptionBody
200StatusAgentStatus
idrequiredstring
filePathrequiredstring | null
namerequiredstring
handlestring
autostartrequiredboolean
runtimeStaterequiredstring

Executor state: idle, thinking, tool_use, awaiting_approval, awaiting_ask, suspended, error, stopped: or a display state (active, hibernate, off)

targetStaterequiredstring | null
loopCountrequiredinteger

Persisted entries in main's loop stream

degradedstring

Set when the agent loaded but cannot fully function (CREDENTIALS_LOCKED: its credentials envelope is locked); cleared once the owner identity unlocks it

runningboolean

GET /agents/{id}/status: false for an open document that is not running (runtimeState stopped).

sessionIdstring

GET /agents/{id}/status of a running agent: its runtime session id (Studio's AGENT_START answers it).

loopStatesmap<string, string>

GET /agents/{id}/status of a running agent: each inner loop's display state (active, idle, suspended, error, off), keyed by loop name. Main is not in it (runtimeState is main's). A loop that accepted a dispatch but has not started thinking reads active.

mediamap<string, object>

GET /agents/{id}/status of a running agent: each loop's effective media (main and live inner loops, keyed by loop name): what its provider connector carries, narrowed by the agent's model.multimodal toggles. POST /agents/{id}/chat refuses the rest with 400 media_unsupported.

2 fields of media
supportobject
3 fields of support
imageboolean
audioboolean
videoboolean
refusalsmap<string, string>

Why each modality not in support is refused, keyed image, audio or video.

Errors 401 · 403 · 404
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/agents/agent-1/status" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"
Response 200
{
  "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

GET/agents/{id}/vitals

Operation getAgentVitalsAuthBearer token

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

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Query parameters

NameTypeDescription
forcestring

Skip the cache: 1 or true. 0 and false are accepted and change nothing.

One of 1, 0, true, false

Responses

StatusDescriptionBody
200VitalsAgentVitals
filePathrequiredstring
computedAtrequirednumber

When the stats and counts were computed (ms epoch)

liverequiredboolean

True when read from the workspace of a loaded agent

handlerequiredstring
namestring
didstring
agentIdstring
modelstring
createdAtstring

adf_created_at (ISO 8601)

ageDaysrequirednumber
statusstring

The agent's own status line (adf_meta status); absent when unset

descriptionstring

config.description, as on the ALF card; absent when blank

publicrequiredboolean

config.serving.public.enabled, the ALF card's public

ownerVerifiedrequiredboolean

An owner attestation about the current DID is stored, unexpired and its signature verifies (whether or not the card publishes it)

contextTokensinteger

Last API-reported context size (loaded agents only)

contextThresholdinteger

Compact threshold (present with contextTokens)

nextWakeAtnumber

Earliest next_wake_at among non-expired timers (ms epoch)

cost7dUsdnumber

USD over the last 7 local days, summed from the agent's priced adf_loop rows (the activity read's daily cost)

cost7dPartialboolean

True when some calls in the window had no recorded price or were compacted (cost7dUsd is a lower bound)

metricsrequiredarray<object>

adf_meta rows whose key starts with metric:, by key, at most 20. A value is a plain string, or a JSON object {"value": number|string, "label"?, "unit"?, "min"?, "max"?, "target"?}; parsed fields are returned beside raw. A value that is not such an object is returned as value = raw. Not part of any stat.

8 fields of metrics
namerequiredstring

Key without the metric: prefix

labelrequiredstring

The object's label when given, else name

valuerequirednumber | string

The object's value, or the raw string when the stored value is not a metric object

unitstring
minnumber

Bar start when max is set (default 0)

maxnumber
targetnumber
rawrequiredstring

The stored adf_meta value as is

statsrequiredobject
4 fields of stats
reachrequiredobject

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

9 fields of reach · AgentPowerStat
levelrequiredinteger

range: 1–20

pointsrequirednumber

Points behind the level, after mitigations

range: ≥ 0

maxrequirednumber

Points of a maxed-out config for this stat

> 0

fillrequirednumber

points / max, clamped: how much of the possible power the agent has

range: 0–1

openrequirednumber

Points whose capability runs without approval (mitigations come off these first)

gatedrequirednumber

Points whose capability needs approval

highrequiredboolean

True when open / max >= 0.6 (open level 12 or more): much of this runs without anyone asking

rawPointsrequirednumber

Sum of factor points, mitigations included

factorsrequiredarray<AgentStatFactor>
5 fields of factors
idrequiredstring

Stable id, e.g. tool:compute_exec, mcp:github, visibility

labelrequiredstring
pointsrequirednumber

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

gatedrequiredboolean

True when the capability needs human approval

configPathrequiredstring

Config path (or table) that controls this factor

accessrequiredobject

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

Fields as in AgentPowerStat above.

autonomyrequiredobject

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

Fields as in AgentPowerStat above.

experiencerequiredobject

Experience. xpForLevel(L) = 5 * (L - 1)^2.25; level = largest L with xpForLevel(L) <= score.

7 fields of experience · AgentExperienceStat
levelrequiredinteger

range: ≥ 1

progressrequirednumber

Progress within the current level

range: 0–1

scorerequirednumber

Total XP (sum of signal XP)

levelStartrequirednumber

XP at which the current level starts

nextLevelAtrequirednumber

XP at which the next level starts

breakdownrequiredarray<object>
4 fields of breakdown
idrequiredstring

One of contextsWorked, memoryTokens, skills, localTables, localRows, filesWritten, agentsSpawned, messages, ageDays

labelrequiredstring
valuerequirednumber

Raw count

xprequirednumber

XP this signal adds

nextLevelrequiredobject

What one more level takes (xp = nextLevelAt - score), in units of the cheapest signals

5 fields of nextLevel
xprequirednumber
contextsrequiredinteger

Contexts of work worth the remaining XP

memoryTokensrequiredinteger

Memory tokens worth the remaining XP

skillsrequiredinteger

Skills worth the remaining XP

hintrequiredstring
maturityrequiredobject

Raw maturity counts read from the agent's file.

9 fields of maturity · AgentMaturity
contextsWorkedrequirednumber

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

range: ≥ 0

filesWrittenrequiredinteger

adf_files rows changed after the agent was created, mind/ excluded

memoryTokensrequiredinteger

Approximate tokens in mind/ files: total bytes, less the seeded mind/log.md header, / 4

localTablesrequiredinteger

local_* tables

localRowsrequiredinteger

Rows across local_* tables (the first 50 by name)

skillsrequiredinteger

Distinct skills the agent installed or changed

agentsSpawnedrequiredinteger | null

Tracked agents whose adf_parent_did names this agent; null when no fleet scan has run

messagesrequiredinteger

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)

ageDaysrequirednumber

Days since adf_created_at

Errors 400 · 401 · 403 · 404 · 409 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
409The agent is loaded without an .adf file; vitals are read from the file
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/agents/agent-1/vitals" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Agent activity

GET/agents/{id}/activity

Operation getAgentActivityAuthBearer token

The 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

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Query parameters

NameTypeDescription
forcestring

Skip the cache: 1 or true. 0 and false are accepted and change nothing.

One of 1, 0, true, false

Responses

StatusDescriptionBody
200ActivityAgentActivity
filePathrequiredstring
computedAtrequirednumber

When this read was computed (ms epoch)

liverequiredboolean

True when read from the workspace of a loaded agent

upcomingrequiredarray<AgentUpcomingWake>

Next non-expired timers, soonest first

items: ≤ 3

7 fields of upcoming
idrequiredinteger
atrequirednumber

next_wake_at (ms epoch)

scoperequiredstring

system runs a lambda; agent wakes a loop

One of system, agent

lambdastring

system: lambda reference, e.g. lib/sync.ts:run

inputstring

system: payload passed to the lambda

length: ≤ 1000

loopstring

agent: loop the wake dispatches to (main when the timer names none)

promptstring

agent: payload the loop wakes with

length: ≤ 1000

dailyrequiredarray<AgentActivityDay>

14 local days, oldest first; the last is today

items: 14–14

5 fields of daily
daterequiredstring

Local YYYY-MM-DD

messagesrequiredinteger

adf_loop rows of every role created that day, plus the day's estimated share of compacted rows archived in adf_audit

estimatedboolean

Some of the day's messages are compacted history whose timing is estimated (spread evenly over a span ending at the archive's creation)

costUsdnumber

USD of the day's priced adf_loop rows (cost_usd in the row's usage record); absent when none had a price

costPartialboolean

Some calls that day had no recorded price, or were compacted (their cost is not recorded); costUsd is a lower bound

contentsrequiredobject

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

Files under mind/

4 fields of mind
filesrequiredinteger
tokensrequiredinteger

SUM(size) / 4, rounded, the seeded mind/log.md header taken off that file

updatedThisWeekrequiredinteger

mind/ files whose updated_at is within the last 7 days

stratarequiredobject

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

Last updated more than 90 days ago

quarterrequiredinteger

Last updated more than 30 and at most 90 days ago

monthrequiredinteger

Last updated more than 7 and at most 30 days ago

weekrequiredinteger

Last updated at most 7 days ago

skillsrequiredobject

Skills the agent installed or changed (the Experience stat rule)

2 fields of skills
countrequiredinteger
tokensrequiredinteger

Size of every file under those skills' directories / 4; registry entries without files add 0

tablesrequiredobject

local_* tables (at most 50 read)

2 fields of tables
countrequiredinteger

range: ≤ 50

rowsrequiredinteger

Total rows

Errors 400 · 401 · 403 · 404 · 409 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
409The agent is loaded without an .adf file; activity is read from the file
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

POST/agents/{id}/start

Operation startAgentAuthBearer token

id 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

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Query parameters

NameTypeDescription
preflightstring

1 or true: check the agent's provider (network) before loading it. Ignored for an agent that is already loaded.

One of 1, true, 0, false

hasUserMessagestring

1 or true: a chat is queued behind this start, so the startup turn skips the active-state greeting (Studio's AGENT_START hasUserMessage).

One of 1, true, 0, false

Responses

StatusDescriptionBody
200StartedStartAgentResponse
successrequiredboolean

Value true

loadedrequiredboolean

The agent was loaded from a tracked folder first

startupTriggeredrequiredboolean
sessionIdstring

The started agent's runtime session id

agentobject

Fields as in AgentStatus above.

Errors 401 · 403 · 404 · 409 · 500
401Missing or wrong bearer token (unauthorized)
403The .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 1object

The .adf has not been reviewed on this machine; review it (GET /agents/review) and accept (POST /agents/review/accept) first.

4 fields of Option 1 · ReviewRequiredResponse
errorrequiredstring
coderequiredstring

Value AGENT_REVIEW_REQUIRED

agentIdrequiredstring
filePathrequiredstring
Option 2object

Every error body. Some routes add fields (e.g. identity, coveredBy, agentId).

2 fields of Option 2 · ErrorResponse
errorrequiredstring

Human-readable message

codestring

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)

404Unknown agent (or the named resource: loop, task, file, …)
409The identifier matches several agent files (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)AmbiguousAgentResponse | ErrorResponse
Option 1object

Every error body. Some routes add fields (e.g. identity, coveredBy, agentId).

3 fields of Option 1 · AmbiguousAgentResponse
errorrequiredstring

Human-readable message

codestring

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)

candidatesrequiredarray<object>
3 fields of candidates
namerequiredstring
handlerequiredstring | null
filePathrequiredstring
Option 2object

Every error body. Some routes add fields (e.g. identity, coveredBy, agentId).

2 fields of Option 2 · ErrorResponse
errorrequiredstring

Human-readable message

codestring

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)

500Unexpected runtime failure

Error bodies use the error format.

Example

Request
curl -X POST "http://127.0.0.1:7385/agents/agent-1/start" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"
Response 200
{
  "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

POST/agents/{id}/stop

Operation stopAgentAuthBearer token

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

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Responses

StatusDescriptionBody
200Stopped and unloadedSuccessResponse
successrequiredboolean
Errors 401 · 403 · 404 · 500
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
curl -X POST "http://127.0.0.1:7385/agents/agent-1/stop" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"
Response 200
{
  "success": true
}

Unload an agent (alias of stop)

POST/agents/{id}/unload

Operation unloadAgentAuthBearer token

No body.

Path parameters

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Responses

StatusDescriptionBody
200UnloadedSuccessResponse
successrequiredboolean
Errors 401 · 403 · 404 · 500
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
curl -X POST "http://127.0.0.1:7385/agents/agent-1/unload" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"
Response 200
{
  "success": true
}

Abort the current turn without unloading

POST/agents/{id}/abort

Operation abortAgentAuthBearer token

A 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

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Query parameters

NameTypeDescription
loopstring

Cognition loop to address. Absent = main. Unknown loops answer 404.

Request bodyapplication/json · LoopBody · optional

Optional; ?loop= wins.

FieldTypeDescription
loopstring

Cognition loop; absent = main. The loop query parameter wins.

Responses

StatusDescriptionBody
200AbortedAbortResponse
successrequiredboolean

Value true

loopstring

Echoed when a loop was named

Errors 401 · 403 · 404 · 409 · 500
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
409The resource is in a state that does not allow this now
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

POST/agents/{id}/interrupt

Operation interruptAgentAuthBearer token

Ends 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

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Query parameters

NameTypeDescription
loopstring

Cognition loop to address. Absent = main. Unknown loops answer 404.

Request bodyapplication/json · LoopBody · optional

Optional; ?loop= wins.

FieldTypeDescription
loopstring

Cognition loop; absent = main. The loop query parameter wins.

Responses

StatusDescriptionBody
200Interrupted (or nothing to interrupt)InterruptResponse
successrequiredboolean

Value true

interruptedrequiredboolean

False when nothing was running

looprequiredstring
Errors 401 · 403 · 404 · 409 · 500
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
409The resource is in a state that does not allow this now
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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 '{}'
Response 200
{
  "success": true,
  "interrupted": true,
  "loop": "main"
}

Move the running agent's display state

POST/agents/{id}/state

Operation setAgentDisplayStateAuthBearer token

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

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Request bodyapplication/json · DisplayStateBody · required

FieldTypeDescription
staterequiredstring

Display (fleet-map) state of an agent

One of active, idle, hibernate, suspended, off

Responses

StatusDescriptionBody
200State setDisplayStateResponse
agentIdrequiredstring

Agent id

successrequiredboolean

Value true

staterequiredstring

Display (fleet-map) state of an agent

One of active, idle, hibernate, suspended, off

Errors 400 · 401 · 403 · 404 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

GET/agents/{id}/config

Operation getAgentConfigAuthBearer token

Path parameters

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Responses

StatusDescriptionBody
200ConfigAgentConfigResponse
agentIdrequiredstring

Agent id

configrequiredobject

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.

revisioninteger

W3-F: the resource's revision (monotonic per agent and resource; never reused across daemon restarts). Pass it as baseRevision (or If-Match) on the next write.

Errors 401 · 403 · 404
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/agents/agent-1/config" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Replace the agent config

PUT/agents/{id}/config

Operation setAgentConfigAuthBearer token

Validated 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

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Query parameters

NameTypeDescription
baseRevisioninteger

W3-F: write only over this revision of the resource (from a read or the last write). Another current revision answers 409 stale_revision. Without it (and without If-Match) the write replaces whatever is there.

range: ≥ 0

Header parameters

NameTypeDescription
If-Matchstring

W3-F: the base revision, as baseRevision (quotes and W/ are accepted; * is no base). Takes precedence over the query parameter and the body field.

example: "1792000000000001"

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

StatusDescriptionBody
200SavedAgentConfigUpdateResponse
agentIdrequiredstring

Agent id

successrequiredboolean

Value true

configrequiredobject

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.

filePathstring

Open document only: the file followed a name change to this path

renameDeferredboolean

Open document only: a start is building; the file is renamed when it stops

renameErrorstring

Open document only: why the file did not follow the name change (saved anyway)

revisioninteger

W3-F: the resource's revision (monotonic per agent and resource; never reused across daemon restarts). Pass it as baseRevision (or If-Match) on the next write.

Errors 400 · 401 · 403 · 404 · 409 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
409W3-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
errorrequiredstring

Human-readable message

coderequiredstring

Value stale_revision

resourcerequiredstring

config, document, or the internal file path

revisionrequiredinteger

The current revision: a write with it as the base overwrites

baseRevisionrequiredinteger

The base the write named

writerrequiredResourceWriter | null

Who made the current revision (null: nobody known since the daemon first saw it)

2 fields of writer
kindrequiredstring

One of agent, client, cli

clientstring

client only

sizeinteger | null

Current size in bytes (null for config)

hashrequiredstring

sha1 of the current content (absent for a missing file)

500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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

GET/agents/{id}/tools

Operation getAgentToolsAuthBearer token

Every 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

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Responses

StatusDescriptionBody
200ToolsAgentToolsResponse
agentIdrequiredstring

Agent id

toolsrequiredarray<ToolEntry>
9 fields of tools
namerequiredstring
enabledrequiredboolean
visiblerequiredboolean

Exposed in the LLM's active tool list (when enabled)

restrictedrequiredboolean

Authorized code only; an LLM call needs owner approval

lockedrequiredboolean

Owner lock: the agent cannot change this entry

sourcerequiredstring

builtin or mcp:<server>

descriptionrequiredstring
schemarequiredobject

The tool's JSON input schema

restrictionsrequiredobject
2 fields of restrictions
restrictedrequiredboolean
lockedrequiredboolean
Errors 401 · 403 · 404 · 500
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/agents/agent-1/tools" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

List metadata entries (adf_meta)

GET/agents/{id}/meta

Operation getAgentMetaAuthBearer token

Path parameters

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Responses

StatusDescriptionBody
200EntriesMetaResponse
agentIdrequiredstring

Agent id

entriesrequiredarray<MetaEntry>
3 fields of entries
keyrequiredstring
valuerequiredstring
protectionrequiredstring

One of none, readonly, increment

Errors 401 · 403 · 404
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/agents/agent-1/meta" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Set a metadata value

PUT/agents/{id}/meta/{key}

Operation setAgentMetaAuthBearer token

Path parameters

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

keyrequiredstring

Metadata key

Request bodyapplication/json · MetaSetBody · required

FieldTypeDescription
valuerequiredstring
protectionstring

One of none, readonly, increment

Responses

StatusDescriptionBody
200SavedAgentSuccess
agentIdrequiredstring

Agent id

successrequiredboolean
Errors 400 · 401 · 403 · 404 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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"}'
Response 200
{
  "agentId": "Xk3v9QpLm2",
  "success": true
}

Delete a metadata value

DELETE/agents/{id}/meta/{key}

Operation deleteAgentMetaAuthBearer token

Path parameters

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

keyrequiredstring

Metadata key

Responses

StatusDescriptionBody
200success is false when nothing was deletedAgentSuccess
agentIdrequiredstring

Agent id

successrequiredboolean
Errors 401 · 403 · 404 · 500
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
curl -X DELETE "http://127.0.0.1:7385/agents/agent-1/meta/KEY" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"
Response 200
{
  "agentId": "Xk3v9QpLm2",
  "success": true
}

Set a metadata key's protection

PATCH/agents/{id}/meta/{key}/protection

Operation setAgentMetaProtectionAuthBearer token

Path parameters

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

keyrequiredstring

Metadata key

Request bodyapplication/json · MetaProtectionBody · required

FieldTypeDescription
protectionrequiredstring

One of none, readonly, increment

Responses

StatusDescriptionBody
200SavedAgentSuccess
agentIdrequiredstring

Agent id

successrequiredboolean
Errors 400 · 401 · 403 · 404 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
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"}'
Response 200
{
  "agentId": "Xk3v9QpLm2",
  "success": true
}

List the agent's local tables

GET/agents/{id}/tables

Operation listAgentLocalTablesAuthBearer token

Path parameters

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Responses

StatusDescriptionBody
200TablesTablesResponse
agentIdrequiredstring

Agent id

tablesrequiredarray<object>
2 fields of tables
namerequiredstring
row_countrequiredinteger
Errors 401 · 403 · 404
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/agents/agent-1/tables" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Read rows of a local table

GET/agents/{id}/tables/{table}

Operation queryAgentLocalTableAuthBearer token

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

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

tablerequiredstring

Local table name (local_*)

Query parameters

NameTypeDescription
limitinteger

Maximum rows to return

offsetinteger

Rows to skip

range: ≥ 0

Responses

StatusDescriptionBody
200RowsTableQueryResponse
agentIdrequiredstring

Agent id

columnsrequiredarray<string>
rowsrequiredarray<object>
Errors 400 · 401 · 403 · 404 · 500
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/agents/agent-1/tables/TABLE" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Drop a local table

DELETE/agents/{id}/tables/{table}

Operation dropAgentLocalTableAuthBearer token

Only local_* tables can be dropped.

Path parameters

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

tablerequiredstring

Local table name (local_*)

Responses

StatusDescriptionBody
200DroppedAgentSuccess
agentIdrequiredstring

Agent id

successrequiredboolean
Errors 401 · 403 · 404 · 500
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
curl -X DELETE "http://127.0.0.1:7385/agents/agent-1/tables/TABLE" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"
Response 200
{
  "agentId": "Xk3v9QpLm2",
  "success": true
}

Recent agent logs (adf_logs)

GET/agents/{id}/logs

Operation getAgentLogsAuthBearer token

limit default 50 (clamped 1–500).

Path parameters

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Query parameters

NameTypeDescription
limitinteger

Maximum rows to return

originstring

Only this origin (e.g. lambda, websocket)

eventstring

Only this event name

Responses

StatusDescriptionBody
200Log rows, newest lastAgentLogsResponse
agentIdrequiredstring

Agent id

logsrequiredarray<LogEntry>
8 fields of logs
idrequiredinteger
levelrequiredstring

One of debug, info, warn, error

originrequiredstring | null
eventrequiredstring | null
targetrequiredstring | null
messagerequiredstring
datarequiredstring | null

JSON text

created_atrequiredinteger

Epoch ms

Errors 400 · 401 · 403 · 404
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/agents/agent-1/logs" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Clear the agent's logs

DELETE/agents/{id}/logs

Operation clearAgentLogsAuthBearer token

Path parameters

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Responses

StatusDescriptionBody
200ClearedAgentSuccess
agentIdrequiredstring

Agent id

successrequiredboolean
Errors 401 · 403 · 404 · 500
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
curl -X DELETE "http://127.0.0.1:7385/agents/agent-1/logs" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"
Response 200
{
  "agentId": "Xk3v9QpLm2",
  "success": true
}

Log rows after an id (tail)

GET/agents/{id}/logs/after

Operation getAgentLogsAfterAuthBearer token

Path parameters

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Query parameters

NameTypeDescription
afterIdrequiredinteger

Return rows with id greater than this

Responses

StatusDescriptionBody
200Newer rowsAgentLogsResponse

Fields as in AgentLogsResponse above.

Errors 400 · 401 · 403 · 404
400Invalid 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
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)

Error bodies use the error format.

Example

Request
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

GET/agents/{id}/usage

Operation getAgentUsageAuthBearer token

A 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

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Responses

StatusDescriptionBody
200UsageAgentUsageResponse
agentIdrequiredstring

Agent id

sourcerequiredstring

Value adf_loop

noterequiredstring
loopRowsrequiredinteger
usageRowsrequiredinteger
totalsrequiredobject
5 fields of totals · UsageTotals
inputrequiredinteger
outputrequiredinteger
cacheReadrequiredinteger
cacheWriterequiredinteger
totalrequiredinteger
byModelrequiredarray<object>
7 fields of byModel
inputrequiredinteger
outputrequiredinteger
cacheReadrequiredinteger
cacheWriterequiredinteger
totalrequiredinteger
modelrequiredstring
rowsrequiredinteger
Errors 401 · 403 · 404
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/agents/agent-1/usage" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Header read: document, config, status text

GET/agents/{id}/header

Operation getAgentHeaderAuthBearer token

Studio's DOC_GET_HEADER in one call, for a running agent or an open document.

Path parameters

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Responses

StatusDescriptionBody
200HeaderAgentHeaderResponse
agentIdrequiredstring
documentrequiredstring

The primary document

agentConfigrequiredobject

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.

statusTextrequiredstring

adf_meta status (empty when unset)

Errors 401 · 403 · 404
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)

Error bodies use the error format.

Example

Request
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

GET/agents/{id}/batch

Operation getAgentBatchAuthBearer token

Studio's DOC_GET_BATCH in one call (a file switch), for a running agent or an open document.

Path parameters

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Responses

StatusDescriptionBody
200BatchAgentBatchResponse
agentIdrequiredstring
documentrequiredstring

The primary document

agentConfigrequiredobject

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.

statusTextrequiredstring

adf_meta status (empty when unset)

lastTokensobject

The newest assistant row's token breakdown (absent when none)

contextBaselineobject | null

What the context gauge shows (null when none); after a compaction it differs from lastTokens and wins

chatrequiredobject
5 fields of chat
versionrequiredinteger
uiLogrequiredarray<DisplayEntry>
5 fields of uiLog
idrequiredstring
typerequiredstring

One of user, text, tool_call, tool_result, thinking, error, trigger, compaction, context

contentrequiredstring
timestamprequiredinteger
metadataobject
llmMessagesrequiredarray<any>
earlierCountrequiredinteger
totalrequiredinteger
configRevisioninteger

W3-F: the revision of agentConfig

documentRevisioninteger

W3-F: the revision of document

Errors 401 · 403 · 404
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/agents/agent-1/batch" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Fold the WAL into the .adf (save)

POST/agents/{id}/checkpoint

Operation checkpointAgentAuthBearer token

Studio's FILE_SAVE. SQLite persists every write; this folds the write-ahead log into the file.

Path parameters

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Responses

StatusDescriptionBody
200CheckpointedSuccessResponse
successrequiredboolean
Errors 401 · 403 · 404 · 409
401Missing or wrong bearer token (unauthorized)
403The 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
404Unknown agent (or the named resource: loop, task, file, …)
409The resource is in a state that does not allow this now

Error bodies use the error format.

Example

Request
curl -X POST "http://127.0.0.1:7385/agents/agent-1/checkpoint" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"
Response 200
{
  "success": true
}