> ## Documentation Index
> Fetch the complete documentation index at: https://afk.arpan.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Agentic Levels
> A capability maturity model — know when to add complexity.
AFK applications progress through five levels of capability. Each level adds features and complexity. Start at Level 1 and move up only when you have clear signals that the current level isn't enough.
## The five levels
One agent, one model, no tools. The simplest possible setup.
```python theme={null}
agent = Agent(name="classifier", model="gpt-5.5", instructions="Classify as positive/negative/neutral.")
result = runner.run_sync(agent, user_message="Great product!")
```
**AFK features used:** `Agent`, `Runner`, `run_sync`
**Good for:** Text classification, summarization, translation, simple Q\&A
**Move up when:** The agent needs to take actions or access external data
Add typed tool functions for the agent to call.
```python theme={null}
@tool(args_model=SearchArgs, name="search", description="Search knowledge base.")
def search(args: SearchArgs) -> dict: ...
agent = Agent(name="helper", model="gpt-5.5", tools=[search])
```
**AFK features added:** `@tool`, Pydantic models, `FailSafeConfig`
**Good for:** RAG, data lookup, calculations, API integrations
**Move up when:** Different parts of the task need different expertise or models
Coordinator delegates to specialist subagents.
```python theme={null}
coordinator = Agent(
name="coordinator",
model="gpt-5.5",
subagents=[researcher, writer, reviewer],
)
```
**AFK features added:** `subagents`, join policies, backpressure
**Good for:** Complex tasks, parallel work, specialist expertise, consensus
**Move up when:** Tasks take minutes, need async processing, or need queue-based reliability
Decouple producers and consumers with task queues. Long-running jobs execute asynchronously.
```python theme={null}
queue = TaskQueue(backend="redis")
await queue.push(TaskItem(contract="runner.chat.v1", agent=agent, user_message="..."))
```
**AFK features added:** `TaskQueue`, `TaskItem`, workers, dead-letter handling
**Good for:** Batch processing, background jobs, retryable pipelines, high-throughput
**Move up when:** You need cross-system communication or external agent interop
Agents communicate across systems using the A2A protocol with authenticated endpoints.
```python theme={null}
from afk.messaging import AgentInvocationRequest
response = await protocol.invoke(AgentInvocationRequest(...))
```
**AFK features added:** `InternalA2AProtocol`, `A2AServiceHost`, auth providers, external adapters
**Good for:** Microservice agent meshes, third-party integrations, federated AI systems
**This is the ceiling** — most applications don't need Level 5.
## Capability comparison
| Capability | L1 | L2 | L3 | L4 | L5 |
| -------------------------- | ------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------ |
| Text generation | | | | | |
| Tool calling | — | | | | |
| Multi-agent delegation | — | — | | | |
| Async processing | — | — | — | | |
| Cross-system communication | — | — | — | — | |
| Policy engine | | | | | |
| Observability | | | | | |
| Evals | | | | | |
= essential at this level
= recommended
— = not applicable
## Decision guide
```mermaid theme={null}
flowchart TD
Start["What does your task need?"]
Start -->|"Just text in/out"| L1["Level 1: Single Agent"]
Start -->|"External data or actions"| L2["Level 2: Agent + Tools"]
Start -->|"Multiple specialists"| L3Q{"Long-running or high-volume?"}
L3Q -->|"No"| L3["Level 3: Multi-Agent"]
L3Q -->|"Yes"| L4Q{"Cross-system interop?"}
L4Q -->|"No"| L4["Level 4: Queue-Backed"]
L4Q -->|"Yes"| L5["Level 5: A2A"]
```
> \[!TIP]
> **Start at Level 1.** The simplest system that works is the best system. Premature complexity is the most common mistake in agent design.
## Signals to level up
| Signal | Current Level | Move to |
| ----------------------------------------------- | ------------- | -------------------------- |
| Agent needs external data | 1 | 2 — Add tools |
| One prompt can't cover all expertise | 2 | 3 — Split into specialists |
| Users waiting too long for results | 3 | 4 — Queue for async |
| Tasks fail and need to be retried automatically | 3 | 4 — Queue with DLQ |
| Other systems need to invoke your agents | 4 | 5 — Expose A2A |
| Third-party agents need to use your tools | 4 | 5 — Use MCP server |
## Next steps
DAG orchestration, join policies, and fan-out.
How AFK separates orchestration from execution.