Design a Single-Loop Agent

Build the core agent loop the leading coding agents use: one model, one loop, tools in, results folded back into context.

5 steps15 verify checks90-150 minutesWorks with: emergent · chatgpt · claude · cursor

Start Guided Walkthrough

#agent-loop #architecture #tools #harness #claude-code

The Route

0/5 verified

Define the loop contract

Write down exactly what one turn of the loop does before coding it.

3 checks 02

Build the tool registry

Tools are the agent's hands - define them with strict schemas.

3 checks 03

Implement the loop with result folding

The loop's job is bookkeeping: order, roles, and IDs must be exact.

3 checks 04

Harden termination and error paths

An agent that cannot stop is worse than one that cannot start.

3 checks 05

Prove it with a transcript review

Judge the loop the way harness engineers do: by reading transcripts.

3 checks

Every step ends at a Verify Gate. Do not continue until every check passes.

Context Pack

Paste this first. It briefs the AI on requirements, constraints, and the Definition of Done before your first build prompt.

Context Pack

PROJECT CONTEXT:
I want to build an AI agent and I keep seeing complex multi-agent diagrams. Research on the strongest coding agents shows they run ONE main loop: model call, tool execution, fold results back, repeat until done.

GOAL:
Implement a robust single-loop agent: message history, tool dispatch, result folding, and a clear termination condition.

REQUIREMENTS:
- A single main loop: send context, receive text or tool calls, execute tools, append results, repeat
- A typed tool registry with JSON-schema definitions per tool
- Deterministic termination: max turns, explicit finish signal, and error budget
- Tool results folded back into the conversation in strict order
- A transcript log of every turn for debugging

CONSTRAINTS:
- One loop, one model call at a time - no parallel model calls in v1
- No framework magic: the loop must be readable in a single file

DEFINITION OF DONE:
- The agent completes a 3-tool task (read file, edit, verify) end to end
- The loop terminates on finish signal, max turns, and repeated errors
- Every turn is logged with role, content, and tool payloads
- Malformed tool calls are rejected with a corrective message, not a crash

COMMON FAILURES TO AVOID:
- Building an orchestration framework before a single loop works
- Dropping or reordering tool results so the model loses causality
- No termination condition - the agent loops forever on a stuck task
- Swallowing tool errors instead of showing them to the model

Paste this into your AI builder first. It teaches the AI what you want before you give it the build prompt.