Agent System
Agents are long-running, tool-calling, budget-managed execution loops. They can spawn children, escalate decisions, checkpoint, and recover from failure. They are not a wrapper around one chat completion.
A project task is the board. An agent run may link to one via taskId. They are different tables. See Tasks.
Model resolution uses the role route, then the tenant locked default. A model must be enabled and available. A broken role route is refused. See AI routing.
Canonical host: https://api.atamaia.ai. Responses are wrapped in ApiEnvelope<T>.
Loop
A run hydrates context, builds a system prompt from the role, resolves a model, and loads a tool profile. Each iteration checks budget, injects pending human or child messages, calls the model, executes allowed tools, and records failure signals. A checkpoint is written every 5 iterations. On completion the run updates status and notifies its parent.
Context warnings fire at 50, 75, and 90 percent of budget, then compaction.
Roles
Roles are rows, not a fixed enum. Tenants can add custom roles. Eight system roles ship with the product:
| Role | Purpose |
|---|---|
| Builder | Code generation and implementation |
| Designer | Architecture, API, and schema design |
| Orchestrator | Multi-agent coordination |
| Planner | Breaking a goal into a task graph |
| Researcher | Gathering and analysis |
| Reviewer | Review and validation |
| Scribe | Documentation and summarization |
| Tester | Test generation and execution |
GET /api/agent/role-definitions
GET /api/agent/role-definitions/{id}
GET /api/agent/role-definitions/by-name/{name}
POST /api/agent/role-definitions
PATCH /api/agent/role-definitions/{id}
DELETE /api/agent/role-definitions/{id}Fields include name, displayName, systemPromptTemplate, defaultMaxIterations, hardIterationCap, contextBudgetTokens, and temperature.
Creating a run
POST /api/agent/runs
| Field | Notes |
|---|---|
goal |
What the run is to do |
role |
Role name |
identityId |
Identity executing the run |
projectId / taskId |
Optional board link |
modelId |
Override. Otherwise the role route is used |
maxIterations / maxTokens / maxWallClockMs / contextBudgetTokens |
Budgets |
toolProfileName |
Optional profile override |
autoStart |
Start immediately. Otherwise status is Pending |
councilMode / councilRounds / councilPerspectives |
Optional council |
Spawn depth has a hard maximum of 10. ParentRunId records the parent.
| Status | Meaning |
|---|---|
Pending |
Created, not started |
Running |
Executing |
Paused |
Paused by a human or the system |
WaitingOnChildren |
Orchestrator waiting on child runs |
WaitingOnEscalation |
Blocked on a human decision |
WaitingOnParent |
Child waiting on its parent |
Completed |
Finished |
Failed |
Failed, with a reason |
Cancelled |
Cancelled by a human |
Lifecycle
POST /api/agent/runs/{id}/start
POST /api/agent/runs/{id}/pause
POST /api/agent/runs/{id}/resume
POST /api/agent/runs/{id}/cancel
POST /api/agent/runs/{id}/checkpoint
POST /api/agent/runs/{id}/restartCancel body: { "reason": "..." }. Restart creates a new run from the failed run's checkpoint.
While paused, humans can send POST /api/agent/runs/{id}/messages or open POST /api/agent/runs/{id}/pause-chat. On resume, the chat is summarized into handoff notes. Messages inject at the next iteration boundary.
Channel triggers
An inbound channel message can wake an identity to run — a mention in a bound channel, or a direct message. Wake behaviour is per binding, not global: mention plus DMs is the default posture, with a per-binding debounce and a daily cap so a busy channel cannot burn the run budget. The reply is delivered back through the same binding, threaded to the triggering message.
The Agents:EventReactor master switch is off by default; enabling it is an operator act, and the per-binding rules then decide what actually wakes. Full rules, gates, and guards: Channels. Setup: Channels setup.
Tools
GET /api/agent/tools lists the agent-loop tools. Tiers are Safe (default on), Opt-in, and Blocked. Effective policy is global defaults, then role profile, then identity override.
GET /api/agent/tool-profiles
GET /api/agent/tool-profiles/{role}
POST /api/agent/tool-profiles
PUT /api/agent/tool-profiles/{id}File I/O is scoped per run: outputDirectory, allowedWritePaths, allowedReadPaths.
Agent-loop memory tools write agent memory, not the work store. See Memory surfaces. Task create still requires kind and subsystem. Graph and web search: Code graph, Web search. Retired tool names are in the Retired surfaces.
External MCP servers can be registered and discovered into the run. The tool name shape is mcp__{connector}__{tool}.
Failure detection
| Mode | What it is | Recovery |
|---|---|---|
EmptyResponse |
No content and no tool calls | Retry with a nudge, then fail |
PrematureIntent |
Says it will act, then does not | Reminder to execute |
StaleLoop |
Text-only steps with no progress | Replan, then escalate |
DuplicateRead |
Same file read at the same offset | Warnings, then stop |
Also recorded: RepeatedToolCall, ContextOverflow, BudgetExceeded, ToolTimeout, DependencyBlocked. Stale steps replan at 3 and escalate at 6.
Escalation
POST /api/agent/runs/{runId}/escalate
GET /api/agent/escalations
POST /api/agent/escalations/{id}/resolveCreate body: situation, optionsJson, supervisorRecommendation, confidence, timeoutMinutes, preferredMode.
Resolution modes: QuickPick, Discussed, TrustedSupervisor, AutoResolved, KnowledgeQuery, BudgetRequest, ApprovalViaMessage. An approval thread can limit revision rounds.
Orchestration
POST /api/agent/runs/{id}/children
GET /api/agent/runs/{id}/children
GET /api/agent/runs/{runId}/councils
GET /api/agent/councils/{id}Environment cascades to children. Orchestrators can share an iteration pool (poolIterationBudget). Council modes: auto, required, none.
Notes, run tasks, feedback
Run notes (Observation, Decision, Blocker, Progress, Handoff) are on POST/GET /api/agent/runs/{runId}/notes.
/api/agent/runs/{runId}/tasks are run-local work items. They do not appear on the project board.
Feedback ratings are Good, Partial, and Bad. Analytics at GET /api/agent/analytics roll token cost up the child tree. Pricing comes from the model's inputCostPer1M and outputCostPer1M.
If the resolved provider type is AnthropicAgentSdk, the loop can delegate to Claude's Agent SDK.
Events
GET /api/agent/runs/{runId}/events?sinceSequence=50&limit=100
Event families: planning, LLM, tool use, files, decisions, failures, context compaction, lifecycle, escalation, children, interaction, and audit (RunStarted, RunCompleted, RunFailed).
Last updated