Why it matters
Agent repositories look like ordinary applications until you try to predict what they will do. The behaviour lives in a loop that calls a model, parses an action, executes a tool and appends the result. Reading such a codebase means reconstructing that cycle, then finding the constraints around it: maximum steps, tool permissions, retry policy and how failures are surfaced. Without that map, any review of the agent is a review of its prompt only.
Mental model
Reading an agent is reading a control system: sensor, decision, actuator, feedback. The metaphor breaks because the decision component is a model whose behaviour is not in the code, so the code tells you the available actions, not the policy.
How it works
- 1Find the entry point and trace one request until the loop exits, noting every place the model is called.
- 2List the tools with their schemas, side effects and permission checks, since that list bounds what the agent can do.
- 3Identify how observations are appended to state and whether old turns are truncated or summarised.
- 4Look for the termination conditions: step budget, token budget, explicit finish action and timeout.
- 5Check error handling for tool failures, because a swallowed exception often becomes an infinite retry.
- 6Read the tests or fixtures for one full trajectory, which is usually faster than reading the prompt.
Step 1 of 6
Find the entry point and trace one request until the loop exits, noting every place the model is called.
Figure. The mechanism in this page's own steps. The figure adds sequence, not new claims.
What to notice. A step can be read alone, but the order is the mechanism. The control lets you stop on any one.
Text version
The page's steps: 1. Find the entry point and trace one request until the loop exits, noting every place the m… 2. List the tools with their schemas, side effects and permission checks, since that list bo… 3. Identify how observations are appended to state and whether old turns are truncated or su… 4. Look for the termination conditions: step budget, token budget, explicit finish action an… 5. Check error handling for tool failures, because a swallowed exception often becomes an in… 6. Read the tests or fixtures for one full trajectory, which is usually faster than reading …
- Find the entry point and trace one request until the loop exits, noting every place the model is called.
- List the tools with their schemas, side effects and permission checks, since that list bounds what the agent can do.
- Identify how observations are appended to state and whether old turns are truncated or summarised.
- Look for the termination conditions: step budget, token budget, explicit finish action and timeout.
- Check error handling for tool failures, because a swallowed exception often becomes an infinite retry.
- Read the tests or fixtures for one full trajectory, which is usually faster than reading the prompt.
Trade-offs
| Choice | Good for | Cost | Fails when |
|---|---|---|---|
| Single-file agent loop | Easy to read and change | Grows into tangled state handling | More than a few tools and branches |
| Framework graph | Explicit nodes and checkpoints | Indirection obscures the actual loop | You need to debug a single step quickly |
| Tools as free functions | Simple to add | No central permission or audit point | Tools touch production systems |
| Tools behind a gateway | Policy and logging in one place | Another hop and schema duplication | Latency budget is tight |
Good for
Easy to read and change
Cost
Grows into tangled state handling
Fails when
More than a few tools and branches
- More than a few tools and branches
- You need to debug a single step quickly
- Tools touch production systems
- Latency budget is tight
Figure. Each choice with what it buys, what it costs, and the case where it loses.
What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.
Text version
Four trade-offs: Single-file agent loop is good for Easy to read and change, costs Grows into tangled state handling, and fails when More than a few tools and branches. Framework graph is good for Explicit nodes and checkpoints, costs Indirection obscures the actual loop, and fails when You need to debug a single step quickly. Tools as free functions is good for Simple to add, costs No central permission or audit point, and fails when Tools touch production systems. Tools behind a gateway is good for Policy and logging in one place, costs Another hop and schema duplication, and fails when Latency budget is tight
Failure modes
- Hidden second loop. A retry wrapper re-invokes the agent and step counts double. Debug: grep for model calls outside the main loop and count invocations per request.
- Unbounded state growth. Every observation is appended and the prompt grows until it fails. Debug: log token count per turn for one long trajectory.
- Silent tool failure. An exception is caught and returned as an empty observation, so the model retries forever. Debug: search for broad exception handlers around tool calls.
In production
Read the code with one real trace open beside it, and check that the trace contains a step count, a tool name and an error field per turn. If the repository cannot produce that, the first review finding is observability.
Common misconceptions
People think: The prompt is the agent.
Actually: The prompt is one input; the loop, tools and termination rules decide what the agent can actually do.
People think: Frameworks make agent code self-explanatory.
Actually: They move the loop into a library, so you must read the framework's control flow to know when it stops.
Interview angle
Walk the loop, then the tool boundary, then the limits, and say what you would instrument first. Mention one concrete risk you found in the code. Weak answers summarise the README or describe the prompt without tracing a request.
Sources
- Anthropic, Building effective agents — loops, tools and when a workflow is enough.
- OpenAI Agents SDK — a minimal loop, tool and handoff implementation to read.
- LangGraph documentation — explicit graph state, checkpoints and interrupts.