Agents · Daemon API

On this page

List loaded agents

GET/agents

Operation listAgentsAuthBearer token

Responses

Status Description Body

200 Loaded agents AgentList · array<AgentSummary>

`id`required	string
`filePath`required	string \| null
`name`required	string
`handle`	string
`autostart`required	boolean

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

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.

Request bodyapplication/json · LoadAgentBody · required

Field	Type	Description
`filePath`required	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

idrequired string

filePathrequired string | null

configrequired

object

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_versionrequired

string

Value 0.2

idrequired

string

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

namerequired string

descriptionrequired string

handle string

icon string

staterequired

string

Display (fleet-map) state of an agent

One of active, idle, hibernate, suspended, off

autonomousrequired boolean

autostart boolean

modelrequired object

9 fields of model · ModelConfig

providerrequired

string

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

model_idrequired string

temperature number | null

max_tokens integer | null

top_p number | null

reasoning

object

Provider-agnostic reasoning ("thinking") config

multimodal object

3 fields of multimodal

`image`	boolean
`audio`	boolean
`video`	boolean

params array<object>

2 fields of params

`key`required	string
`value`required	string

provider_params object

instructionsrequired string

contextrequired

object

compact_threshold, audit, dynamic_instructions

toolsrequired

array<object>

Tool declarations

5 fields of tools

`name`required	string
`enabled`required	boolean
`visible`	boolean
`restricted`	boolean
`locked`	boolean

triggersrequired

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

enabledrequired boolean

targetsrequired array<TriggerTarget>

11 fields of targets

`scope`required	string	One of `agent`, `system`
`lambda`	string	System scope: `path/file.ts:functionName`
`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

locked boolean

securityrequired object

limitsrequired object

messagingrequired

object

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

mcp object

2 fields of mcp

serversrequired array<McpServerConfig>

20 fields of servers

namerequired string

transportrequired

string

One of stdio, http

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

One of host, shared

credential_files array<object>

3 fields of credential_files

`path`required	string
`required`	boolean
`write_back`	boolean

new_tools_restricted boolean

adapters

map<string, AdapterInstanceConfig>

Channel 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 limits

max_attachment_size

integer

Bytes

providers array<AgentProviderConfig>

8 fields of providers

idrequired

string

anthropic, openai, … or custom:<id>

typerequired

string

One of anthropic, openai, openai-compatible, openrouter

namerequired string

baseUrlrequired string

preset string

defaultModel string

params array<object>

2 fields of params

`key`required	string
`value`required	string

requestDelayMs integer

loops

array<LoopConfig>

Inner (side) loops; main is implicit

8 fields of loops

`name`required	string	pattern: ^[a-z0-9][a-z0-9_-]{0,31}$
`goal`required	string	Becomes the loop's instructions
`enabled`required	boolean
`autostart`	boolean
`autonomous`	boolean
`model`	object	Fields as in ModelConfig above.
`compact_threshold`	integer \| null
`tools`	array<string>	Absolute allow-list, intersected with the host's enabled tools

ws_connections array<object>

serving object

locked_fields array<string>

metadatarequired

object

created_at, updated_at, author, tags, version

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

object

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

`error`required	string
`code`required	string	Value `AGENT_REVIEW_REQUIRED`
`agentId`required	string
`filePath`required	string

Option 2

object

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

2 fields of Option 2 · ErrorResponse

`error`required	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)

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

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 `standard`.
`provider`	string	App provider id (must exist in settings.providers)
`model`	string
`start`	boolean	default: false

Responses

Status Description Body

201 Created (and loaded; started when start) CreateAgentResponse

`agentId`required	string
`name`required	string
`filePath`required	string
`did`required	string
`started`required	boolean

Errors 400 · 401 · 403 · 409 · 422 · 500 · 503

400 Invalid field (bad_request) AgentCreateErrorResponse

errorrequired string

coderequired

string

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

identity object

7 fields of identity · IdentityStatus

`status`required	string	One of `none`, `locked`, `restore-needed`, `ready`
`ownerDid`required	string \| null
`runtimeDid`required	string \| null	This daemon's own runtime DID (never Studio's)
`storage`required	string	One of `keychain`, `file`
`backupConfirmed`required	boolean
`passphraseRequired`required	boolean	File storage not unlocked: create/restore/unlock take a passphrase
`message`required	string	What to do next

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 Owner identity not ready (identity_not_ready) or the name is taken in that directory (name_taken)identity_not_readyname_taken AgentCreateErrorResponse

422 The template was refused (template_missing, template_unreviewed, template_invalid) or the new file could not load (load_failed) AgentCreateErrorResponse

500 Unexpected runtime failure

503 The 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…",
  "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

Field	Type	Description
`trackedDirs`required	array<string>
`maxDepth`	integer

Responses

Status Description Body

200 What was started, skipped and failed AutostartReport

scannedrequired

integer

.adf files found

startedrequired array<object>

4 fields of started

`agentId`required	string
`filePath`required	string
`name`required	string
`startupTriggered`required	boolean

skippedrequired array<object>

4 fields of skipped

`filePath`required	string
`name`required	string
`reason`required	string	One of `already_loaded`, `not_autostart`, `password_protected`, `unreviewed`
`agentId`	string

failedrequired array<object>

3 fields of failed

`filePath`required	string
`name`required	string
`error`required	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

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

Query parameters

Name	Type	Description
`filePath`required	string	Absolute path of the .adf file example: /home/me/agents/agent-2.adf

Responses

Status Description Body

200 Review summary ReviewInfo

agentIdrequired string

filePathrequired string

reviewedrequired boolean

summaryrequired

object

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

13 fields of summary · ReviewSummary

namerequired string

descriptionrequired string

icon string

identityrequired

object

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

computeTierrequired

string

One of shared, isolated, host

autostartrequired boolean

toolsrequired array<object>

3 fields of tools

`name`required	string
`enabled`required	boolean
`notable`required	boolean

mcpServersrequired array<object>

triggersrequired array<object>

3 fields of triggers

`type`required	string
`enabled`required	boolean
`targetCount`required	integer

codeExecutionrequired boolean

messagingrequired object

1 field of messaging

moderequired string

networkrequired object

securityrequired object

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

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

Request bodyapplication/json · ReviewAcceptBody · required

Field	Type	Description
`filePath`required	string

Responses

Status	Description	Body
200	Reviewed	ReviewInfo
Fields as in ReviewInfo above.

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

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 loaded agent's reference (id, file, config)

GET/agents/{id}

Operation getAgentAuthBearer token

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

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

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

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Responses

Status Description Body

200 Status AgentStatus

`id`required	string
`filePath`required	string \| null
`name`required	string
`handle`	string
`autostart`required	boolean
`runtimeState`required	string	Executor state: idle, thinking, tool_use, awaiting_approval, awaiting_ask, suspended, error, stopped: or a display state (active, hibernate, off)
`targetState`required	string \| null
`loopCount`required	integer	Persisted entries in main's loop stream
`degraded`	string	Set when the agent loaded but cannot fully function (CREDENTIALS_LOCKED: its credentials envelope is locked); cleared once the owner identity unlocks it

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

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
}

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.

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Responses

Status Description Body

200 Started StartAgentResponse

`success`required	boolean	Value `true`
`loaded`required	boolean	The agent was loaded from a tracked folder first
`startupTriggered`required	boolean
`agent`	object	Fields as in AgentStatus above.

Errors 401 · 403 · 404 · 409 · 500

401 Missing or wrong bearer token (unauthorized)

Option 1

object

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

`error`required	string
`code`required	string	Value `AGENT_REVIEW_REQUIRED`
`agentId`required	string
`filePath`required	string

Option 2

object

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

2 fields of Option 2 · ErrorResponse

`error`required	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)

404 Unknown agent (or the named resource: loop, task, file, …)

409 The identifier matches several agent files (ambiguous_agent) AmbiguousAgentResponse

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 candidates

`name`required	string
`handle`required	string \| null
`filePath`required	string

500 Unexpected 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

Graceful: a running turn gets a 5 s grace period, then the agent is unloaded (its file stays on disk). No body.

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Responses

Status Description Body

200 Stopped and unloaded SuccessResponse

successrequired boolean

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

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

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Responses

Status Description Body

200 Unloaded SuccessResponse

successrequired boolean

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

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

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

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 `loop` query parameter wins.

Responses

Status Description Body

200 Aborted AbortResponse

`success`required	boolean	Value `true`
`loop`	string	Echoed when a loop was named

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

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. Unlike /abort it never stops the executor, and chats queued behind the turn are kept and run next. interrupted is false when nothing was running; 409 when the loop is stopped or errored.

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

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 `loop` query parameter wins.

Responses

Status Description Body

200 Interrupted (or nothing to interrupt) InterruptResponse

`success`required	boolean	Value `true`
`interrupted`required	boolean	False when nothing was running
`loop`required	string

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

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.

Path parameters

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Request bodyapplication/json · DisplayStateBody · required

Field	Type	Description
`state`required	string	Display (fleet-map) state of an agent One of `active`, `idle`, `hibernate`, `suspended`, `off`

Responses

Status Description Body

200 State set DisplayStateResponse

`agentId`required	string	Agent id
`success`required	boolean	Value `true`
`state`required	string	Display (fleet-map) state of an agent One of `active`, `idle`, `hibernate`, `suspended`, `off`

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

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

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Responses

Status Description Body

200 Config AgentConfigResponse

`agentId`required	string	Agent id
`config`required	object	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.

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

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

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

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

`agentId`required	string	Agent id
`success`required	boolean	Value `true`
`config`required	object	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.

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

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

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Responses

Status Description Body

200 Tools AgentToolsResponse

agentIdrequired

string

Agent id

toolsrequired array<ToolEntry>

9 fields of tools

namerequired string

enabledrequired boolean

visiblerequired

boolean

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

restrictedrequired

boolean

Authorized code only; an LLM call needs owner approval

lockedrequired

boolean

Owner lock: the agent cannot change this entry

sourcerequired

string

builtin or mcp:<server>

descriptionrequired string

schemarequired

object

The tool's JSON input schema

restrictionsrequired object

2 fields of restrictions

`restricted`required	boolean
`locked`required	boolean

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

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

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Responses

Status Description Body

200 Entries MetaResponse

agentIdrequired

string

Agent id

entriesrequired array<MetaEntry>

3 fields of entries

`key`required	string
`value`required	string
`protection`required	string	One of `none`, `readonly`, `increment`

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

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

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1
`key`required	string	Metadata key

Request bodyapplication/json · MetaSetBody · required

Field	Type	Description
`value`required	string
`protection`	string	One of `none`, `readonly`, `increment`

Responses

Status Description Body

200 Saved AgentSuccess

`agentId`required	string	Agent id
`success`required	boolean

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

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

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1
`key`required	string	Metadata key

Responses

Status Description Body

200 success is false when nothing was deleted AgentSuccess

`agentId`required	string	Agent id
`success`required	boolean

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

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

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1
`key`required	string	Metadata key

Request bodyapplication/json · MetaProtectionBody · required

Field	Type	Description
`protection`required	string	One of `none`, `readonly`, `increment`

Responses

Status Description Body

200 Saved AgentSuccess

`agentId`required	string	Agent id
`success`required	boolean

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

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

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Responses

Status Description Body

200 Tables TablesResponse

agentIdrequired

string

Agent id

tablesrequired array<object>

2 fields of tables

`name`required	string
`row_count`required	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

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

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1
`table`required	string	Local table name (`local_*`)

Query parameters

Name	Type	Description
`limit`	integer	Maximum rows to return
`offset`	integer	Rows to skip range: ≥ 0

Responses

Status Description Body

200 Rows TableQueryResponse

`agentId`required	string	Agent id
`columns`required	array<string>
`rows`required	array<object>

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

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

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1
`table`required	string	Local table name (`local_*`)

Responses

Status Description Body

200 Dropped AgentSuccess

`agentId`required	string	Agent id
`success`required	boolean

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

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

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Query parameters

Name	Type	Description
`limit`	integer	Maximum rows to return
`origin`	string	Only this origin (e.g. `lambda`, `websocket`)
`event`	string	Only this event name

Responses

Status Description Body

200 Log rows, newest last AgentLogsResponse

agentIdrequired

string

Agent id

logsrequired array<LogEntry>

8 fields of logs

`id`required	integer
`level`required	string	One of `debug`, `info`, `warn`, `error`
`origin`required	string \| null
`event`required	string \| null
`target`required	string \| null
`message`required	string
`data`required	string \| null	JSON text
`created_at`required	integer	Epoch ms

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

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

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Responses

Status Description Body

200 Cleared AgentSuccess

`agentId`required	string	Agent id
`success`required	boolean

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

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

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Query parameters

Name	Type	Description
`afterId`required	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

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

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1

Responses

Status Description Body

200 Usage AgentUsageResponse

agentIdrequired

string

Agent id

sourcerequired

string

Value adf_loop

noterequired string

loopRowsrequired integer

usageRowsrequired integer

totalsrequired object

5 fields of totals · UsageTotals

`input`required	integer
`output`required	integer
`cacheRead`required	integer
`cacheWrite`required	integer
`total`required	integer

byModelrequired array<object>

7 fields of byModel

`input`required	integer
`output`required	integer
`cacheRead`required	integer
`cacheWrite`required	integer
`total`required	integer
`model`required	string
`rows`required	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

Request

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