Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Agent Architecture

Amodal uses a multi-agent architecture where a primary agent delegates data-intensive work to ephemeral task agents, keeping its own context clean for reasoning.

Agent Types

Primary Agent

One per chat session. Handles the conversation, reasons about findings, decides next steps, and presents results. Never loads API docs or parses raw JSON directly.

Task Agents

Ephemeral workers dispatched by the primary agent (or by other task agents). Each gets its own fresh context, loads KB docs, queries systems, interprets raw responses, and returns a clean summary (~200-500 tokens). Context is discarded after.

Automations

Scheduled or triggered runs can execute agent workflows without an open chat client. Configure them only when the agent has a clear background job to perform.

Context Isolation

This is the key architectural insight. Without task agents, raw data accumulates in the primary agent's context and never leaves:

Without task agents:                 With task agents:
 
[System prompt: 2K]                 [System prompt: 2K]
[User: "What changed on ticket T-100?"][User: "What changed on ticket T-100?"]
[API docs: 8K]     ← stuck forever  [Task result: 200 tokens]
[Raw JSON: 3K]     ← stuck forever  [Task result: 250 tokens]
[Pattern docs: 4K] ← stuck forever  [Task result: 150 tokens]
Context: 28K+ and growing           Context: 3K — clean, focused

Task agents can dispatch sub-task agents (depth 2). Depth 3 is rare. Depth 4+ is blocked.

Task Agent Capabilities

Task agents inherit the parent's tool registry by default but are typically dispatched with a narrowed subset via dispatch_task({toolSubset: [...]}):

ToolAvailable to sub-agents
request (read-only)Yes
store__<store>__get / store__<store>__query / store__<store>__listYes
store__<store>__set / store__<store>__removeYes when the dispatcher includes write-capable store tools
dispatch_task (nested sub-tasks)Yes (depth limited)
present (widgets)Usually filtered out — sub-agents return summaries, not widgets
Custom toolsYes (whichever ones the dispatcher includes in toolSubset)
MCP toolsYes (same rule)
SkillsNot applicable — sub-agents have a task prompt, not an agent loop with skills

Task agents produce 200-500 token summaries from 8-15K of processed data. The primary agent reasons about these summaries, not the raw data.

Dispatch Example

User: "What changed on ticket T-100?"
 
Primary Agent dispatches 3 task agents in parallel:
  1. "Load ticket T-100 and summarize the current state"
  2. "Check related account events for the same user"
  3. "Review the support policy for the relevant category"
 
Each task agent:
  - Loads relevant KB docs (API documentation)
  - Makes API calls via `request`
  - Processes raw JSON responses
  - Returns a clean summary
 
Primary Agent receives 3 summaries (~600 tokens total)
  → Correlates: the ticket category, recent account event, and policy guidance
  → Presents a concise recommendation