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.

Mandate playbook

The mandate is the unattended loop. Trace AI (skill_id: autonomic-agents) and Library templates (skill_id: model-agent-import) must write it as a playbook with:

1. Purpose — standing outcome in tenant terms (which records, people, systems).
2. Context / fitness — what “good enough for this purpose” means, and what is unfit even if a mechanical result exists.
3. Sense-Reason-Act-Evaluate — internal order every wake before the decision JSON. Do not Act without Sense. Do not done or dispatch without Evaluate.
4. How fitness is ensured — named evidence (DataPool re-query, notify row, BACKLOG.md) and fail paths (continue or need_human).
5. Stop rules — when done is allowed and which mutations are forbidden.

Reject a one-line goal (“keep invoices current”, “watch the mailbox”). If Sense cannot obtain a source of truth, the agent returns need_human instead of guessing IDs. Rewrite BACKLOG.md every turn. done is rejected while open backlog items remain.

Manage agents with Trace AI

Tenant administrators can manage the current Autonomic Agent resources from Trace AI:

1. Call load_platform_skill with skill_id: autonomic-agents.
2. Use describe_autonomic_agent and list_autonomic_agents before creating or changing a definition.
3. Use the create/update tools with a five-part mandate. Prefer a draft first.
4. Confirm before activation, manual runs, disable, or delete.
5. Verify the definition and inspect runs with the get/list run tools.

The skill unlocks:

• describe_autonomic_agent, list_autonomic_agents, get_autonomic_agent
• create_autonomic_agent, update_autonomic_agent
• disable_autonomic_agent, delete_autonomic_agent
• run_autonomic_agent
• list_autonomic_agent_runs, get_autonomic_agent_run

These MCP tools:

• require AUTONOMIC_AGENTS_ENABLED=1;
• require a tenant-admin role;
• are restricted to Trace AI and cannot be called recursively by autonomic_mcp;
• use the same CRUD, compile, run, and tenant-isolation services as the Agents console;
• do not expose the generated owned ProcessFlow as a separately managed resource.

skill_id on an Autonomic Agent means a tenant skill package loaded with load_tenant_skill during unattended runs. It is not a platform skill_id.

To install a published Autonomic Agent template, ask Trace AI to use model-agent-import. Trace installs required tenant playbooks first, binds Prerequisites (DataPool schemas, in-app recipients), and creates the agent as draft. See Model Autonomic Agents library.

Repo-wired platform specialists are different. See Platform specialists. They live in SKILLS/platform-agents.json (platform-bulk-reader, platform-code-specialist). list_subagent_catalog returns them with source: "platform" without a tenant admin creating a row. The first delegate_subagent to that slug compiles a tenant Autonomic Agent from the template. Do not recreate those slugs with create_autonomic_agent unless you are replacing a shadowed tenant definition.

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} → Execution logs 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.

Durable wakes use the sticky session. Trace AI delegated runs use a hidden child session and agents/{agent_id}/runs/{run_id}/, so independent runs can execute in parallel up to max_concurrent_runs and platform limits. The run inspector labels durable wakes and Trace delegations separately and shows delegated progress events.

skill_state execution mode (optional)

When AUTONOMIC_SKILL_STATE_ENABLED=true and an agent's execution_mode is skill_state, cross-wake reasoning context uses structured execution_state.json (canonical Σ) instead of replaying the sticky session transcript. Each wake injects:

• <autonomic_execution_state> — JSON snapshot of backlog items, working memory, blockers, hop count, and correlation id
• <autonomic_observation> — the wake payload and mailbox only

BACKLOG.md remains a human-readable projection generated from Σ. The final decision JSON may include an optional state_patch object; the platform validates and merges it before dispatch. Sticky session logging to chat_sessions continues for audit, but that history is not fed back into the LLM context in skill_state mode.

Delegated subagent runs

When delegatable_by_trace is enabled and the definition is active, Trace AI may target it after loading load_platform_skill with skill_id: subagents.

• Delegation returns immediately with a run_id.
• The child transcript is hidden from ordinary chat history.
• agent_run_events preserves queued, model, tool, completion, failure, and cancellation progress.
• Queued cancellation is immediate.
• Running cancellation is cooperative and stops at the next safe model/tool boundary.

For ProcessFlow step or WebApp code, prefer the repo-wired platform specialist slug platform-code-specialist (child turn already unlocks platform-code-generation). Tenant-authored specialists should still require load_platform_skill with skill_id: platform-code-generation in the mandate. The code contract and validation tools are read-only; platform mutations remain separate.

Decision JSON

Each wake is one MCP tool loop. The platform parses only the last non-empty assistant message in that loop. If you respond without tool calls, the loop stops immediately and that message must be valid decision JSON — there is no separate interim assistant channel.

• While more tool work is needed: respond with tool calls only (use progress_indicator on tools for operator status).
• When tool work is complete: respond without tool calls and put only this JSON object in assistant content (no prose, Markdown, or code fence):

{
  "state_patch": { "working_memory": { "po_id": "PO-42" } },
  "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
}

Common failure modes: prose after tool results, emitting decision JSON before finishing required tools, or wrapping the object in Markdown. All fail the run.

Invalid JSON fails the run.

Security and prompt trust

Autonomic Agents share the NestJS prompt-trust pipeline with Trace AI. See MCP guardrails — prompt trust.

Prefer a dedicated low-privilege user for identity_user_id rather than a tenant administrator.

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

Trace AI can also call run_autonomic_agent after confirmation. The MCP call invokes one current Autonomic Agent turn synchronously and returns its decision, so it may take several minutes. Use schedule/event wakes for durable unattended execution rather than repeatedly calling the manual test tool.

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
• Trace AI subagents
• Platform specialists
• Platform code generation
• Autonomic Agent token budgets
• Agent wait tool
• Tenant skills user guide
• Process flows as custom AI agent tools
• Model Autonomic Agents library
• Platform skills quick reference