Autonomic Agents

Autonomic Agents are unattended tenant workers. They wake on a schedule, webhook, or process event, run one bounded MCP tool-loop turn, then return a decision JSON object. They are not chat agents and do not appear in the in-app agent picker.

When to use Autonomic Agents

Trace AI stays user-initiated. Autonomic Agents run as the process-execution identity (or the agent’s identity_user_id) and cannot be started from GET /api/v1/chat/agents or /chat/*.

This feature is gated by AUTONOMIC_AGENTS_ENABLED (default off). When it is off, the Agents console returns an empty list and mutations are unavailable. Ask a platform operator to enable it for your deployment.

Create an agent

In the tenant console, open Agents. Tenant administrators can create and edit agents.

Required:

Optional:

Saving the agent:

• Creates or updates the owned wake process (hidden from the default Processes list).
• Compiles schedule subscriptions into ProcessTriggers on that wake process. Webhook subscriptions are not stored; use linked WebApps instead.
• Seeds a sticky chat session used as the transcript for every wake.
• Creates the working directory {tenant data}/agents/{agent_id}/ with BACKLOG.md.
• Links any Triggers → Connect Webapp entries by setting WebApps.process_id to that wake process (not a ProcessTriggers webhook row). Invoking the published WebApp or Webhook then runs executeProcess on the wake process, same as a process webhook.

Do not assemble this process by hand in the process editor. The Agents editor is the source of truth unless you detach the process.

Working directory and backlog

Each agent has a home directory {tenant data}/agents/{agent_id}/ with BACKLOG.md. File tools may read and write anywhere under that tenant's tenantdata (same tenant-root bound as other MCP file tools). Use the agent home for BACKLOG.md and agent-owned notes; typical layout:

agents/{agent_id}/
  BACKLOG.md
  docs/
  logs/

Every turn injects the current BACKLOG.md as <autonomic_backlog>. The model must rewrite the backlog before the final JSON (update_agent_backlog or a write to that BACKLOG.md path). Decision done is rejected while open backlog items remain; the platform coerces that to continue and re-enqueues a wake until max_hops.

Runs and sticky transcript

Each wake writes an agent_runs row: status, current action, heartbeat, hop count, selected model, and the parsed decision. Open Agents → {name} → Runs to inspect them.

The agent has one sticky chat_session_id. Every wake appends messages to that session. The session is not restored in Chat with Agents or the picker. Use the agent Runs page for the transcript.

Only one run per agent may be in flight (max_concurrent_runs defaults to 1) so two turns cannot write the sticky session at once.

Decision JSON

The final assistant message must be only this object (no Markdown fence, no prose):

{
  "decision": "execute_process | emit_event | send_agent_message | continue | need_human | done",
  "target_id": "process_id or event_type or null",
  "input": {},
  "summary": "one-line audit",
  "correlation_id": "corr_…",
  "backlog_open_count": 0
}

Invalid JSON fails the run.

Mailbox (peer agents)

Each agent has allowed_peer_agent_ids (UUIDs or slugs). Decision or tool send_agent_message writes to agent_messages and wakes the recipient. Incoming mail is injected as <autonomic_mailbox> on the next turn. Compile always adds an event trigger for agent.message.received.

Unattended human input

request_human_input chat cards are not used. When the model returns need_human:

1. The run status becomes need_human. Remaining wake-process steps are skipped.
2. An in-app notification is sent to the agent identity user (if set) and tenant admins.
3. A tenant admin answers from the Runs page. That wakes the same agent with event: human.answered.

Limits

Manual test run

Tenant administrators can enqueue a manual wake from the console (Run on the Triggers tab) or POST /api/v1/autonomic-agents/{agent_id}/run. That executes the compiled wake process asynchronously (same path as schedule and webhook wakes via invoke_agent).

Webhook triggers

Webhook wakes use the same WebApp model as Processes:

1. Save the agent so it has a wake_process_id.
2. On Agents → {name} → Triggers, Create webhook (or Connect an existing unlinked webhook / callback WebApp).
3. Publish the WebApp and copy its published URL.
4. Send GET or POST to that URL. The WebApp runtime runs the wake process, which calls invoke_agent for one bounded turn.

Do not add { type: "webhook" } entries to subscriptions; compile ignores them and strips legacy rows on the next save.

Event triggers

Event wakes use { type: "event" } subscriptions compiled to ProcessTriggers on the wake process:

1. On Agents → {name} → Triggers, Add Trigger under Event Triggers and set an event type (for example invoice.overdue).
2. Save the agent so compile syncs the trigger onto wake_process_id.
3. Deliver the event explicitly — for example another agent’s emit_event decision, POST /processflow?action=fire-trigger with the compiled trigger_id, or an Event Broker process that fans out to listeners.

Peer mailbox delivery (agent.message.received) is compiled automatically; you do not add it manually.

See also

• AI, agents, and MCP introduction
• Trace AI Agent
• Agent wait tool
• Tenant skills user guide
• Platform skills quick reference