Agent Runtime

Agent Runtime

An agent run is a structured, goal-directed execution that follows a plan → approval → execute loop. Every agent run is persisted to the database, gated by an explicit approval step, and scoped to a set of granted capabilities.

Agent Run Lifecycle

pending_approval → approved → executing → completed
                                        ↘ failed
                                        ↘ delegated → (sub-agent) → ...

Status	Meaning
pending_approval	Created; waiting for operator or automation to approve
approved	Approved; execution will begin immediately
executing	Plan is in progress
delegated	Sub-agent dispatched (multi-agent coordination)
completed	Run finished successfully; result field populated
failed	Run terminated with error; error field populated

Creating a Run

curl -X POST http://localhost:8000/apps/agent/runs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "objective": "Analyze the last 10 memory nodes in namespace sales and summarize trends",
    "risk_level": "low",
    "capabilities": ["read_memory", "write_memory", "execute_flow"]
  }'
# → {"id": "run_abc123", "status": "pending_approval"}

risk_level can be low, medium, or high. Higher risk runs may require explicit operator review before approval.

Approving a Run

curl -X POST http://localhost:8000/apps/agent/runs/run_abc123/approve \
  -H "Authorization: Bearer $TOKEN"

Approval is atomic — concurrent approval requests are safe. The run transitions to approved and execution begins in a background thread.

Capability Tokens

Each agent run is associated with a scoped capability token. The token limits what syscalls the agent may invoke during execution. Default capabilities for a runtime-only deployment:

• execute_flow — call sys.v1.flow.run
• read_memory — call sys.v1.memory.read, search, tree
• write_memory — call sys.v1.memory.write

App plugins can register additional capabilities. The token is minted at approval time and cannot be expanded mid-execution.

Planning

When a run enters executing, the agent calls a planner backend to decompose the objective into steps. The runtime includes a generic planner. App plugins may register a custom planner context provider to inject domain-specific context (KPIs, recent activity, task lists, etc.).

Tools

The agent's tool catalog is resolved from the tool registry at execution time. Runtime baseline tools: memory.recall, memory.write. App plugins may register additional tools (task management, web search, domain-specific APIs).

Trigger Evaluation (Autonomous Agents)

An autonomous agent run can be associated with a trigger evaluator — a function that decides whether to fire the run based on current conditions. The evaluator returns one of:

Decision	Meaning
execute	Fire immediately
defer	Re-evaluate after defer_seconds
ignore	Dismiss — no further evaluation

Trigger evaluation is logged as a SystemEvent with type autonomy.decision.

Multi-Agent Coordination

An agent run can delegate to a sub-agent via AgentCoordinator. The parent run enters delegated status while the sub-agent executes. When the sub-agent completes, the result is merged back and the parent may continue.

Polling and Webhooks

Poll for completion:

curl http://localhost:8000/apps/agent/runs/run_abc123 \
  -H "Authorization: Bearer $TOKEN"

Each run has an event history in SystemEvent records — step completions, capability denials, delegations — queryable via the observability endpoints.

Recovery

If the API process crashes during an agent run, the run is left in executing or approved status. On restart:

• The stuck-run scanner marks runs that have exceeded STUCK_RUN_THRESHOLD_MINUTES as failed and dead-letters them with a recovery event
• The orphaned-approved watchdog (scheduler job) catches runs stranded in approved with no active execution thread