Loops · Daemon API

On this page

List cognition loops (main plus inner loops)

GET/agents/{id}/loops

Operation listAgentLoopsAuthBearer token

Path parameters

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

Responses

Status Description Body

200 Loops with live status and declarations LoopListResponse

agentIdrequired

string

Agent id

loopsrequired array<LoopInfo>

8 fields of loops

namerequired string

goalrequired string

statusrequired

string

One of idle, running

enabledrequired boolean

isMainrequired

boolean

The implicit host loop

configrequired LoopConfig | null

8 fields of config

namerequired

string

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

goalrequired

string

Becomes the loop's instructions

enabledrequired boolean

autostart boolean

autonomous boolean

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

provider_params object

compact_threshold integer | null

tools

array<string>

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

entryCountrequired

integer

Rows in this loop's adf_loop stream

effectiveToolsrequired array<string> | null

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

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

Request bodyapplication/json · LoopCreateBody · required

Field	Type	Description
`name`required	string	pattern: ^[a-z0-9][a-z0-9_-]{0,31}$
`goal`required	string
`enabled`	boolean	default: true
`autostart`	boolean	default: true
`autonomous`	boolean
`model`	object	Fields as in ModelConfig above.
`compact_threshold`	integer \| null
`tools`	array<string>	Default: loop_send, loop_list, sys_set_state (filtered to what the host can grant)

Responses

Status Description Body

201 Created LoopCreateResponse

agentIdrequired

string

Agent id

looprequired object

8 fields of loop · LoopInfo

namerequired string

goalrequired string

statusrequired

string

One of idle, running

enabledrequired boolean

isMainrequired

boolean

The implicit host loop

configrequired LoopConfig | null

8 fields of config

`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

entryCountrequired

integer

Rows in this loop's adf_loop stream

effectiveToolsrequired array<string> | null

effectiveToolsrequired array<string>

excludedToolsrequired array<string>

kickoffrequired LoopSendResult | null

3 fields of kickoff

`delivered`required	boolean
`woke`required	boolean
`reason`	string

Errors 400 · 401 · 403 · 404 · 409 · 500

400	Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (`statusCode`, `code`, `error`, `message`).`bad_requestFST_ERR_CTP_EMPTY_JSON_BODY`
401	Missing or wrong bearer token (`unauthorized`)
403	The request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)`host_not_allowedcross_origin`
404	Unknown agent (or the named resource: loop, task, file, …)
409	The 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/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

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1
`name`required	string	Loop name (`main` or an inner loop) example: reflector

Responses

Status Description Body

200 The loop LoopResponse

`agentId`required	string	Agent id
`loop`required	object	Fields as in LoopInfo above.

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

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1
`name`required	string	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.

Field Type Description

goal string

enabled

boolean

false stops the loop immediately

autostart boolean

autonomous boolean

model ModelConfig | null

9 fields of model

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

compact_threshold integer | null

tools array<string>

Responses

Status Description Body

200 Updated LoopUpdateResponse

`agentId`required	string	Agent id
`loop`required	object	Fields as in LoopInfo above.
`updated`required	array<string>
`excludedTools`required	array<string>

Errors 400 · 401 · 403 · 404 · 409 · 500

400	Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (`statusCode`, `code`, `error`, `message`).`bad_requestFST_ERR_CTP_EMPTY_JSON_BODY`
401	Missing or wrong bearer token (`unauthorized`)
403	The request guard refused it: Host header not allowed (`host_not_allowed`, DNS-rebinding protection) or a browser cross-site request (`cross_origin`)`host_not_allowedcross_origin`
404	Unknown agent (or the named resource: loop, task, file, …)
409	The 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 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

Name	Type	Description
`id`required	string	Loaded agent: its id, handle or name. example: agent-1
`name`required	string	Loop name (`main` or an inner loop) example: reflector

Responses

Status Description Body

200 Deleted LoopDeleteResponse

`agentId`required	string	Agent id
`name`required	string
`archivedEntries`required	integer	adf_loop rows written to adf_audit
`interruptedTurn`required	boolean

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

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
`offset`	integer	Rows to skip range: ≥ 0
`loop`	string	Cognition loop to address. Absent = main. Unknown loops answer 404.

Responses

Status Description Body

200 A page of adf_loop rows LoopPage

agentIdrequired

string

Agent id

looprequired string

totalrequired integer

limitrequired integer

offsetrequired integer

entriesrequired array<LoopEntry>

6 fields of entries

seqrequired integer

rolerequired

string

One of user, assistant

content_jsonrequired

array<object>

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

model string

tokens object

6 fields of tokens · LoopTokenUsage

`input`	integer
`output`	integer
`cache_read`	integer
`cache_write`	integer
`reasoning`	integer
`cost_usd`	number

created_atrequired

integer

Epoch ms

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

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.
`items`	integer	Items per category (default 12, max 200) range: 0–200

Responses

Status Description Body

200 Context usage AgentContextResponse

agentIdrequired

string

Agent id

looprequired string

availablerequired

boolean

False when the loop has no live executor

modelrequired object

2 fields of model

`provider`required	string \| null
`modelId`required	string \| null

compactThresholdrequired integer

compactThresholdSourcerequired

string

One of loop, agent, model, default

agentCompactThresholdrequired integer

totalTokensrequired integer | null

percentrequired

integer | null

totalTokens / compactThreshold, rounded percent

categoriesrequired array<ContextCategory>

7 fields of categories

idrequired

string

The key, or mcp:<server>

keyrequired

string

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

labelrequired string

tokensrequired integer

count integer

itemsrequired array<object>

3 fields of items

`name`required	string
`tokens`required	integer
`detail`	string

noterequired string

breakdownrequired ContextBreakdown | null

9 fields of breakdown

system_prompt_tokensrequired integer

system_prompt_partsrequired object

3 fields of system_prompt_parts

`base_and_sections`required	integer
`runtime_blocks`required	integer
`instructions`required	integer

injected_filesrequired array<object>

2 fields of injected_files

`path`required	string
`tokens`required	integer

tool_groupsrequired array<object>

3 fields of tool_groups

sourcerequired

string

built-in or the MCP server name

tokensrequired integer

toolsrequired array<object>

2 fields of tools

`name`required	string
`tokens`required	integer

tools_total_tokensrequired integer

dynamic_instructions_tokensrequired integer

messages_tokensrequired integer

overhead_tokensrequired integer

computed_atrequired

integer

Epoch ms

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

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 Compacted CompactResponse

`agentId`required	string	Agent id
`loop`required	string
`success`required	boolean	Value `true`

Errors 401 · 403 · 404 · 409 · 500 · 502

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
502	An 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 '{}'