Agent System
Atamaia's agent system is a full execution framework for autonomous AI actors. Agents are not wrappers around chat completions. They are long-running, tool-calling, budget-managed, human-supervised execution loops that can spawn children, escalate decisions, checkpoint their state, and recover from failure.
A project task is the board. An agent run may link to one via taskId. They are different tables. See Tasks.
Architecture
Human creates AgentRun via API
│
▼
AgentExecutionLoop
├── Hydrate context (identity, memories, facts, tasks)
├── Build system prompt from AgentRoleDefinition
├── Resolve model (route config → locked default; refuse broken)
├── Load tool profile (safe/opt-in/blocked)
│
├── MAIN LOOP ─────────────────────────────────────────
│ ├── Check budget (iterations, tokens, wall clock)
│ ├── Inject pending messages (human, child, fact updates)
│ ├── Build messages (with context compaction at 50/75/90%)
│ ├── Call LLM via AIRouter
│ ├── Parse tool calls → filter against profile
│ ├── Execute tools (with summarization)
│ ├── 4-mode failure detection
│ ├── Duplicate read detection (3-level warnings)
│ ├── Stale loop detection (3 = replan, 6 = escalate)
│ ├── Checkpoint every 5 iterations
│ └── Handle escalations, child spawns, pauses
│
└── On completion: update status, notify parent, log final event
Model resolution is not “hardcoded fallback to local:main-instruct.” Routing requires enabled AND available; broken role routes are refused; last resort is the tenant’s locked-default model. See AI routing.
Core Entities
AgentRoleDefinition
Configurable agent roles stored in the database. Tenants can create custom roles via the API.
| Field | Description |
|---|---|
Name |
Machine name (e.g. Builder, Researcher) |
DisplayName |
Human-readable name |
SystemPromptTemplate |
System prompt with variable substitution |
DefaultMaxIterations |
Default iteration budget |
HardIterationCap |
Absolute maximum even with budget extensions |
ContextBudgetTokens |
Token budget for context window |
Temperature |
LLM temperature default |
Icon |
Lucide icon name for UI display |
IsSystem / Enabled |
Seed vs custom; whether the role is offered |
Live on prod (2026-08-14): 9 definitions. The AgentRole enum still has the original eight. The ninth is a custom row.
| Role | isSystem |
Purpose (from live description) |
|---|---|---|
| Builder | yes | Code generation, file modification, implementation |
| Designer | yes | Architecture, API design, schema design |
| Orchestrator | yes | Multi-agent coordination, task decomposition |
| Planner | yes | Breaking goals into task DAGs |
| Researcher | yes | Information gathering, analysis, web search |
| Reviewer | yes | Code review, quality checks, validation |
| Scribe | yes | Documentation, summarization, writing |
| Tester | yes | Test generation, test execution, validation |
| SocialManager | no | Social drafts for human approval; never publishes autonomously |
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}
AgentRun
POST /api/agent/runs
Create body (CreateAgentRunRequest):
| Field | Notes |
|---|---|
goal |
What the run is to do |
role |
Role name (not roleDefinitionId — that field is not on the live body) |
identityId |
AI identity executing |
projectId / taskId |
Optional board link |
modelId |
Explicit override; otherwise role route |
maxIterations / maxTokens / maxWallClockMs / contextBudgetTokens |
Budgets |
toolProfileName |
Optional profile override |
environmentJson |
Cascade (council mode, etc.) |
autoStart |
Start immediately |
councilMode / councilRounds / councilPerspectives |
Optional council |
compactionConfig / hydrationBudget |
Context controls |
Response is AgentRunDto (id, guid, role, roleDefinitionId, status, budgets, cost, child/event counts). Status on create is Pending unless autoStart.
Key fields on the run itself: ParentRunId / SpawnDepth (hard max 10), PlanJson, ProgressSummary, StaleStepCount, CheckpointJson, InteractionThreadId, PauseChatSessionId, CostUsd.
AgentRun Statuses
| Status | Description |
|---|---|
Pending |
Created but not started |
Running |
Actively executing |
Paused |
Paused by human or system |
WaitingOnChildren |
Orchestrator waiting for child runs |
WaitingOnEscalation |
Blocked on human decision |
WaitingOnParent |
Child waiting for parent response |
Completed |
Successfully finished |
Failed |
Failed with reason |
Cancelled |
Cancelled by human |
Execution 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}/restart
Cancel body: { "reason": "…" }.
Every 5 iterations the loop writes CheckpointJson. Restart creates a new run pre-loaded from the failed run’s checkpoint.
While paused, humans can send messages (POST /api/agent/runs/{id}/messages) or open a pause chat (POST /api/agent/runs/{id}/pause-chat). On resume, the chat is summarized into handoff notes.
Tool System
GET /api/agent/tools
Live count 57 (2026-08-14). Categories and names from that response:
| Category | Tools |
|---|---|
| FileRead | file_read, cat, head, tail, glob, grep, find, list_dir, ls, pwd, git_diff, git_status, lsp_definition, lsp_diagnostics, lsp_hover, lsp_references, lsp_symbols |
| FileWrite | file_write, file_edit, file_copy, file_move, make_dir, git_add, git_branch, git_commit |
| System | bash, run_build (both isDangerous) |
| AtamaiaService | memory_create, memory_search (these are agent-memory tools — Memory surfaces), task_create, task_update, task_list, channel_send, channel_list, run_add_note, training_pair_create, model_for_role, convene_council, request_budget, wait_approval, agent_task_create, agent_task_update, agent_task_list, web_search, web_fetch, graph_search, graph_neighbors, graph_node, graph_drift |
| AgentControl | spawn_child, respond_to_child, message_parent, escalate, resolve_escalation (all isDangerous) |
| Meta | list_tools, context_pin, lsp_status |
Not registered (documented in 2026-03, gone now): fact_confirm, fact_upsert, fact_search, run_note (renamed run_add_note).
Graph tools: Code graph. Web search: Web search. Task create still requires kind + subsystem.
Tool Profiles
Three tiers: Safe (default on), Opt-in (explicit enable), Blocked (never). Resolution: Global Defaults → Role Profile → Identity Override.
GET /api/agent/tool-profiles
GET /api/agent/tool-profiles/{role}
POST /api/agent/tool-profiles
PUT /api/agent/tool-profiles/{id}
Dynamic MCP Proxy Tools
Registered MCP servers (POST /api/system/mcp-proxies) can be discovered into the registry. Naming convention mcp__{proxy}__{tool} is the documented Claude Code shape; live name emission was not re-probed.
File I/O is scoped per run: OutputDirectory, AllowedWritePaths, AllowedReadPaths.
Failure Detection
Four distinct failure modes:
| Mode | Detection | Recovery |
|---|---|---|
| EmptyResponse | LLM returns no content and no tool calls | Retry with nudge; fail after consecutive empties |
| PrematureIntent | Agent says it will act but does not | Inject reminder to execute |
| StaleLoop | Consecutive text-only steps without progress | Replan, then escalate |
| DuplicateRead | Same file read repeatedly at same offset | Graduated warnings then STOP |
Also recorded as event types: RepeatedToolCall, ContextOverflow, BudgetExceeded, ToolTimeout, DependencyBlocked.
Context warnings fire at 50 / 75 / 90% of budget, then compaction.
Escalation System
POST /api/agent/runs/{runId}/escalate
GET /api/agent/escalations
POST /api/agent/escalations/{id}/resolve
Create body: situation, optionsJson, supervisorRecommendation, confidence, timeoutMinutes, preferredMode.
Resolution modes (ResolutionMode)
| Mode | Description |
|---|---|
QuickPick |
Human selects from agent-provided options |
Discussed |
Opens a chat session for discussion |
TrustedSupervisor |
Auto-resolve if confidence exceeds threshold |
AutoResolved |
Timed out and auto-resolved |
KnowledgeQuery |
Check facts first, escalate only if not found |
BudgetRequest |
Agent requested more iterations |
ApprovalViaMessage |
Resolved via message thread (revision loop) |
Escalation supports an approval thread with revision rounds (maxRevisionRounds on the DTO).
Orchestration
POST /api/agent/runs/{id}/children
GET /api/agent/runs/{id}/children
GET /api/agent/runs/{runId}/councils
GET /api/agent/councils/{id}
Maximum spawn depth: 10. Environment cascades. Orchestrators can share an iteration pool (PoolIterationBudget).
Council modes: auto (keyword detection), required, none.
Human-Agent Interaction
POST /api/agent/runs/{runId}/messages
GET /api/agent/runs/{runId}/messages
POST /api/agent/runs/{runId}/pause-chat
Messages inject at the next iteration boundary. Pause chat returns a ChatSessionDetailDto linked to the run.
Event Trail
GET /api/agent/runs/{runId}/events?sinceSequence=50&limit=100
AgentEventType (live):
- Planning: PlanCreated, PlanRevised, StepStarted, StepCompleted
- LLM: LlmRequest, LlmResponse
- Tool Use: ToolCallRequested, ToolCallResult, ToolCallBlocked
- Files: FileCheckedOut, FileCommitted, FileConflict
- Decisions: Decision, Observation, Reasoning
- Failures: EmptyResponse, PrematureIntent, StaleLoop, ContextOverflow, ToolTimeout, DependencyBlocked, BudgetExceeded, DuplicateRead, RepeatedToolCall
- Context: ContextWarning50/75/90, ContextCompacted, ContextFlushed
- Lifecycle: Checkpoint, Paused, Resumed, BudgetWarning, BudgetExtended
- Escalation: EscalationCreated, EscalationResolved, ApprovalRevision
- Children: ChildSpawned, ChildCompleted, ChildFailed, ChildMessage, ParentResponse, SystemMessage
- Interaction: InteractionMessageReceived, InteractionMessageSent, PauseChatLinked, PauseChatSummarized
- Audit: RunStarted, RunCompleted, RunFailed
Run Notes, Agent Tasks, Feedback, Analytics
POST /api/agent/runs/{runId}/notes
GET /api/agent/runs/{runId}/notes
Note types: Observation, Decision, Blocker, Progress, Handoff.
GET /api/agent/runs/{runId}/tasks
POST /api/agent/runs/{runId}/tasks
PATCH /api/agent/tasks/{id}
These are run-local work items. They do not appear on the project board.
POST /api/agent/runs/{runId}/feedback
GET /api/agent/runs/{runId}/feedback
Ratings: Good, Partial, Bad.
GET /api/agent/analytics?modelId=…&role=…
Cost: PromptTokens / CompletionTokens / CostUsd, rolled up as TotalTokensWithChildren / TotalCostWithChildren. Pricing comes from the model’s InputCostPer1M / OutputCostPer1M.
When a model’s provider type is AnthropicAgentSdk, the loop can delegate to Claude’s Agent SDK. Live behaviour of that path was not re-probed.
API Reference
| Method | Endpoint | Permission | Description |
|---|---|---|---|
| GET | /api/agent/role-definitions |
AgentRunView | List role definitions |
| GET | /api/agent/role-definitions/{id} |
AgentRunView | Get role definition |
| GET | /api/agent/role-definitions/by-name/{name} |
AgentRunView | Get by name |
| POST | /api/agent/role-definitions |
AgentToolProfileManage | Create role definition |
| PATCH | /api/agent/role-definitions/{id} |
AgentToolProfileManage | Update role definition |
| DELETE | /api/agent/role-definitions/{id} |
AgentToolProfileManage | Delete role definition |
| GET | /api/agent/tools |
(any auth) | List registered tools |
| GET | /api/agent/runs |
AgentRunView | List runs |
| GET | /api/agent/runs/{id} |
AgentRunView | Get run detail |
| POST | /api/agent/runs |
AgentRunCreate | Create a run |
| PATCH | /api/agent/runs/{id} |
AgentRunManage | Update a run |
| DELETE | /api/agent/runs/{id} |
AgentRunManage | Soft delete a run |
| POST | /api/agent/runs/{id}/start |
AgentRunManage | Start execution |
| POST | /api/agent/runs/{id}/pause |
AgentRunManage | Pause execution |
| POST | /api/agent/runs/{id}/resume |
AgentRunManage | Resume execution |
| POST | /api/agent/runs/{id}/cancel |
AgentRunManage | Cancel with reason |
| POST | /api/agent/runs/{id}/checkpoint |
AgentRunManage | Force checkpoint |
| POST | /api/agent/runs/{id}/restart |
AgentRunManage | Restart from checkpoint |
| POST | /api/agent/runs/{id}/children |
AgentRunCreate | Spawn child run |
| GET | /api/agent/runs/{id}/children |
AgentRunView | List child runs |
| GET | /api/agent/runs/{runId}/events |
AgentRunView | Get execution events |
| GET | /api/agent/escalations |
AgentRunView | List pending escalations |
| POST | /api/agent/runs/{runId}/escalate |
AgentRunManage | Create escalation |
| POST | /api/agent/escalations/{id}/resolve |
AgentEscalationResolve | Resolve escalation |
| GET | /api/agent/runs/{runId}/tasks |
AgentRunView | List agent tasks |
| POST | /api/agent/runs/{runId}/tasks |
AgentRunManage | Create agent task |
| PATCH | /api/agent/tasks/{id} |
AgentRunManage | Update agent task |
| POST | /api/agent/runs/{runId}/notes |
AgentRunManage | Add run note |
| GET | /api/agent/runs/{runId}/notes |
AgentRunView | Get run notes |
| GET | /api/agent/runs/{runId}/councils |
AgentRunView | List councils |
| GET | /api/agent/councils/{id} |
AgentRunView | Get council detail |
| GET | /api/agent/tool-profiles |
AgentRunView | List tool profiles |
| GET | /api/agent/tool-profiles/{role} |
AgentRunView | Get tool profile |
| POST | /api/agent/tool-profiles |
AgentToolProfileManage | Create tool profile |
| PUT | /api/agent/tool-profiles/{id} |
AgentToolProfileManage | Update tool profile |
| POST | /api/agent/runs/{runId}/feedback |
AgentRunManage | Add feedback |
| GET | /api/agent/runs/{runId}/feedback |
AgentRunView | Get feedback |
| GET | /api/agent/analytics |
AgentRunView | Get analytics |
| POST | /api/agent/runs/{runId}/messages |
AgentRunManage | Send message to agent |
| GET | /api/agent/runs/{runId}/messages |
AgentRunView | Get run messages |
| POST | /api/agent/runs/{runId}/pause-chat |
AgentRunManage | Create/get pause chat |
All endpoints require authentication. Responses wrapped in ApiEnvelope<T>. Canonical host: https://api.atamaia.ai.