Core Concepts

The Execution Loop

Every agent run follows the same loop:

Initialize → [LLM Call → Process Response → (Tool Calls | Done)] → Complete
                ↑                                    |
                └────────────── Loop ────────────────┘

1. Initialize — create or resume a run with a unique run ID
2. LLM Call — send the conversation history and available tools to the LLM
3. Process Response — the LLM returns either text (done) or tool calls (continue)
4. Tool Execution — validate inputs, execute tools in parallel, record results
5. Checkpoint — save state to the state store (crash recovery point)
6. Repeat until the LLM returns a text response or maxSteps is reached

Runs

A run is a single execution of an agent for a given task. Every run has:

• A unique run ID (format: run_{timestamp}_{nanoid(6)})
• A status: initializing → running → completed | failed | max_steps_exceeded
• A trace of every step, tool call, and token count

const result = await agent.run({ task: 'Do something' });
// result.runId    — "run_1710000000000_abc123"
// result.status   — "completed"
// result.output   — the agent's final response
// result.trace    — { steps: StepRecord[], summary: TraceSummary }

Steps

Each iteration of the loop is a step. A step records:

• Index — 0-based position in the run
• Type — 'llm' (LLM response) or 'tool' (tool execution)
• Timing — start time and duration
• Token usage — input and output tokens
• Tool call details — name, input, output, errors

Messages

The message history is the conversation between the user, assistant, and tools. This is the permanent API surface — messages go into Redis, traces, and replays.

Tools

Tools are typed functions the agent can call. Each tool has:

• Input schema (Zod) — validated before execution
• Output schema (Zod) — validated after execution
• Execute function — the actual implementation
• Retry config — automatic retries with backoff
• Optional compensation — rollback function for failure recovery

State

AgentForge saves run state at every checkpoint. If the process crashes, the run can be resumed from the last checkpoint by providing the same run ID:

// First run — crashes at step 3
const result1 = await agent.run({ task: 'Long task', runId: 'run_abc' });

// Resume — continues from step 3
const result2 = await agent.run({ task: 'Long task', runId: 'run_abc' });

Governance

Two mechanisms control agent behavior at runtime:

• Budget Governor — enforces token and cost limits. The agent stops if it exceeds the budget.
• Autonomy Policy — tool-level allow/deny/escalate rules. The agent pauses for approval when escalation is required.

Error Sources

AgentForge always tells you where an error came from:

Next Steps

• Agents — full agent configuration
• Tools — define typed tools
• State — state management in depth