On this page

List cognition loops (main plus inner loops)

GET/agents/{id}/loops

Operation listAgentLoopsAuthBearer token

Path parameters

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Responses

StatusDescriptionBody
200Loops with live status and declarationsLoopListResponse
agentIdrequiredstring

Agent id

loopsrequiredarray<LoopInfo>
8 fields of loops
namerequiredstring
goalrequiredstring
statusrequiredstring

One of idle, running

enabledrequiredboolean
isMainrequiredboolean

The implicit host loop

configrequiredLoopConfig | null
8 fields of config
namerequiredstring

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

goalrequiredstring

Becomes the loop's instructions

enabledrequiredboolean
autostartboolean
autonomousboolean
modelobject
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>
provider_paramsobject
compact_thresholdinteger | null
toolsarray<string>

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

entryCountrequiredinteger

Rows in this loop's adf_loop stream

effectiveToolsrequiredarray<string> | null
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/loops" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Create an inner loop

POST/agents/{id}/loops

Operation createAgentLoopAuthBearer token

Goes through the agent's loop pool, the same path as the loop_manage tool: same validation, tool attenuation and owner locks (locked_fields: ["loops"]). Defaults: enabled and autostart true; tools loop_send + loop_list + sys_set_state (filtered to what the host can grant). An enabled autostart loop is kicked off at once through loop_send (kickoff). excludedTools: requested tools the host has disabled, carried by name and granted once enabled. 400 invalid declaration (bad name, unknown or never-grantable tool); 409 for main, a duplicate name, the loop cap, or loops locked by the owner.

Path parameters

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Request bodyapplication/json · LoopCreateBody · required

FieldTypeDescription
namerequiredstring

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

goalrequiredstring
enabledboolean

default: true

autostartboolean

default: true

autonomousboolean
modelobject

Fields as in ModelConfig above.

compact_thresholdinteger | null
toolsarray<string>

Default: loop_send, loop_list, sys_set_state (filtered to what the host can grant)

Responses

StatusDescriptionBody
201CreatedLoopCreateResponse
agentIdrequiredstring

Agent id

looprequiredobject
8 fields of loop · LoopInfo
namerequiredstring
goalrequiredstring
statusrequiredstring

One of idle, running

enabledrequiredboolean
isMainrequiredboolean

The implicit host loop

configrequiredLoopConfig | null
8 fields of config
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

entryCountrequiredinteger

Rows in this loop's adf_loop stream

effectiveToolsrequiredarray<string> | null
effectiveToolsrequiredarray<string>
excludedToolsrequiredarray<string>
kickoffrequiredLoopSendResult | null
3 fields of kickoff
deliveredrequiredboolean
wokerequiredboolean
reasonstring
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 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/loops" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "reflector",
  "goal": "Review the day'\''s work and write lessons to mind.md."
}'

Read one loop

GET/agents/{id}/loops/{name}

Operation getAgentLoopInfoAuthBearer token

Path parameters

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

namerequiredstring

Loop name (main or an inner loop)

example: reflector

Responses

StatusDescriptionBody
200The loopLoopResponse
agentIdrequiredstring

Agent id

looprequiredobject

Fields as in LoopInfo above.

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/loops/reflector" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Patch an inner loop

PATCH/agents/{id}/loops/{name}

Operation updateAgentLoopAuthBearer token

Present keys replace wholesale; "model": null / "compact_threshold": null remove the override so the loop inherits main's again. The loop is re-derived at once; enabled: false stops a running loop now (its turn is aborted and flushed). Loops cannot be renamed and an empty patch is refused (400). main is not managed here (409; change the agent config).

Path parameters

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

namerequiredstring

Loop name (main or an inner loop)

example: reflector

Request bodyapplication/json · LoopPatchBody · required

At least one field. null clears model / compact_threshold. Loops cannot be renamed.

FieldTypeDescription
goalstring
enabledboolean

false stops the loop immediately

autostartboolean
autonomousboolean
modelModelConfig | null
9 fields of model
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
compact_thresholdinteger | null
toolsarray<string>

Responses

StatusDescriptionBody
200UpdatedLoopUpdateResponse
agentIdrequiredstring

Agent id

looprequiredobject

Fields as in LoopInfo above.

updatedrequiredarray<string>
excludedToolsrequiredarray<string>
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 resource is in a state that does not allow this now
500Unexpected runtime failure

Error bodies use the error format.

Example

Request
curl -X PATCH "http://127.0.0.1:7385/agents/agent-1/loops/reflector" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

Stop, archive and remove an inner loop

DELETE/agents/{id}/loops/{name}

Operation deleteAgentLoopAuthBearer token

Stops the loop (mid-turn included), archives its stream to adf_audit under loop:<name>, drops its timers (locked timers are kept), then removes it. 409 for main.

Path parameters

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

namerequiredstring

Loop name (main or an inner loop)

example: reflector

Responses

StatusDescriptionBody
200DeletedLoopDeleteResponse
agentIdrequiredstring

Agent id

namerequiredstring
archivedEntriesrequiredinteger

adf_loop rows written to adf_audit

interruptedTurnrequiredboolean
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 DELETE "http://127.0.0.1:7385/agents/agent-1/loops/reflector" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Read persisted loop entries (paginated)

GET/agents/{id}/loop

Operation getAgentLoopAuthBearer token

The durable conversation history. limit default 50 (clamped 1–500); offset default = the last page.

Path parameters

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

Query parameters

NameTypeDescription
limitinteger

Maximum rows to return

offsetinteger

Rows to skip

range: ≥ 0

loopstring

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

Responses

StatusDescriptionBody
200A page of adf_loop rowsLoopPage
agentIdrequiredstring

Agent id

looprequiredstring
totalrequiredinteger
limitrequiredinteger
offsetrequiredinteger
entriesrequiredarray<LoopEntry>
6 fields of entries
seqrequiredinteger
rolerequiredstring

One of user, assistant

content_jsonrequiredarray<object>

Provider-neutral content blocks (text, tool_use, tool_result, …)

modelstring
tokensobject
6 fields of tokens · LoopTokenUsage
inputinteger
outputinteger
cache_readinteger
cache_writeinteger
reasoninginteger
cost_usdnumber
created_atrequiredinteger

Epoch ms

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/loop" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

One loop's context usage

GET/agents/{id}/context

Operation getAgentContextAuthBearer token

What the next request of main (or ?loop=) would carry: the executor's breakdown split into non-overlapping categories (system, files, tools, mcp:<server>, dynamic, messages; biggest first, summing to totalTokens) with their biggest items, plus the compact threshold that loop auto-compacts at. Figures are the executor's own: system prompt and tool schemas measured with the provider tokenizer when it rebuilds them; conversation (compaction summary included) and dynamic instructions estimated per read. compactThreshold resolves like the executor: the loop's compact_threshold, else the agent's context.compact_threshold, else the (loop's or agent's) model's, else 100000 (compactThresholdSource: loop · agent · model · default); agentCompactThreshold is main's, for comparison. available: false (empty categories, null totals) when the loop has no live executor: disabled, never woken or put to sleep.

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.

itemsinteger

Items per category (default 12, max 200)

range: 0–200

Responses

StatusDescriptionBody
200Context usageAgentContextResponse
agentIdrequiredstring

Agent id

looprequiredstring
availablerequiredboolean

False when the loop has no live executor

modelrequiredobject
2 fields of model
providerrequiredstring | null
modelIdrequiredstring | null
compactThresholdrequiredinteger
compactThresholdSourcerequiredstring

One of loop, agent, model, default

agentCompactThresholdrequiredinteger
totalTokensrequiredinteger | null
percentrequiredinteger | null

totalTokens / compactThreshold, rounded percent

categoriesrequiredarray<ContextCategory>
8 fields of categories
idrequiredstring

The key, or mcp:<server>

keyrequiredstring

One of system, files, tools, mcp, dynamic, messages, recent

labelrequiredstring
tokensrequiredinteger
countinteger
itemsrequiredarray<object>
3 fields of items
namerequiredstring
tokensrequiredinteger
detailstring
noterequiredstring
basisrequiredstring

estimate: not tied to any call. calibrated: an estimate scaled so the calibrated parts sum to the last call's measured prompt (only the sum is measured). measured: the API-reported figure (the last reply's output).

One of estimate, calibrated, measured

breakdownrequiredContextBreakdown | null
10 fields of breakdown
system_prompt_tokensrequiredinteger
system_prompt_partsrequiredobject
3 fields of system_prompt_parts
base_and_sectionsrequiredinteger
runtime_blocksrequiredinteger
instructionsrequiredinteger
injected_filesrequiredarray<object>
2 fields of injected_files
pathrequiredstring
tokensrequiredinteger
tool_groupsrequiredarray<object>
3 fields of tool_groups
sourcerequiredstring

built-in or the MCP server name

tokensrequiredinteger
toolsrequiredarray<object>
2 fields of tools
namerequiredstring
tokensrequiredinteger
tools_total_tokensrequiredinteger
dynamic_instructions_tokensrequiredinteger
messages_tokensrequiredinteger

Includes calibration.since_last_call_tokens

overhead_tokensrequiredinteger
computed_atrequiredinteger

Epoch ms

calibrationobject

Present when the parts are calibrated to the loop's last call: they then sum to that call's real prompt size plus the content added since it. Absent: every figure is an uncalibrated estimate.

4 fields of calibration
last_call_tokensrequiredinteger

API-reported prompt size of the last call, cache reads and writes included

ratiorequirednumber

Real / estimated, applied to every estimated part

since_last_call_tokensrequiredinteger

Part of messages_tokens added since that call: reply_tokens plus later content estimated at ratio

reply_tokensrequiredinteger

API-reported output of that call, counted exactly in since_last_call_tokens (0 when not reported)

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/context" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Compact one loop's history now

POST/agents/{id}/compact

Operation compactAgentLoopAuthBearer token

Summarize-and-replace on demand for main, or the named inner loop. Emits loop.compacted; triggers queue and chats replay after it. 409 mid-turn, already compacting, nothing to compact, or a disabled loop; 502 when summarization fails (history preserved).

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
200CompactedCompactResponse
agentIdrequiredstring

Agent id

looprequiredstring
successrequiredboolean

Value true

Errors 401 · 403 · 404 · 409 · 500 · 502
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
502An upstream call failed (e.g. the summarization request of a compaction); nothing was changed

Error bodies use the error format.

Example

Request
curl -X POST "http://127.0.0.1:7385/agents/agent-1/compact" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Run an owner slash command

POST/agents/{id}/commands/{name}/run

Operation runAgentCommandAuthBearer token

Runs a registered lambda without a model turn and records its bounded outcome in the selected loop. Requires a running agent; never starts it. Error and denied outcomes are recorded and return 200. The authorize boolean elevates only this invocation; chat text is never interpreted as a command.

Path parameters

NameTypeDescription
idrequiredstring

Loaded agent: its id, handle or name.

example: agent-1

namerequiredstring

Registered command name without the slash.

Request bodyapplication/json · OwnerCommandBody · optional

FieldTypeDescription
argsstring

default: ""length: ≤ 4096pattern: ^[^\n]*$

loopstring

default: "main"

authorizeboolean

Owner grant for this invocation only. Paired devices may grant it.

default: false

requestIdstring

pattern: ^[A-Za-z0-9_-]{1,64}$

Responses

StatusDescriptionBody
200Recorded command outcomeOwnerCommandResult
idrequiredstring
namerequiredstring
looprequiredstring
statusrequiredstring

One of ok, error, denied

authorizedrequiredboolean
resultrequiredstring

Bounded output exactly as recorded in the loop.

durationMsrequirednumber
deferredrequiredboolean

The record waits for the current step to finish.

seqinteger
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 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/commands/NAME/run" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'