Skip to content
AI Engineer Guide.

drill · drills · beginner · concept 18 of 33

Code reading: agent

0 of 33 complete

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

Mechanism, step by stepInteractive
  1. 1Find the entry point and trace one request until the loop exits, noting every place the model is called.
  2. 2List the tools with their schemas, side effects and permission checks, since that list bounds what the agent can do.
  3. 3Identify how observations are appended to state and whether old turns are truncated or summarised.
  4. 4Look for the termination conditions: step budget, token budget, explicit finish action and timeout.
  5. 5Check error handling for tool failures, because a swallowed exception often becomes an infinite retry.
  6. 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.

Step 1/6 · step 1

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 …

  1. Find the entry point and trace one request until the loop exits, noting every place the model is called.
  2. List the tools with their schemas, side effects and permission checks, since that list bounds what the agent can do.
  3. Identify how observations are appended to state and whether old turns are truncated or summarised.
  4. Look for the termination conditions: step budget, token budget, explicit finish action and timeout.
  5. Check error handling for tool failures, because a swallowed exception often becomes an infinite retry.
  6. Read the tests or fixtures for one full trajectory, which is usually faster than reading the prompt.

Trade-offs

ChoiceGood forCostFails when
Single-file agent loopEasy to read and changeGrows into tangled state handlingMore than a few tools and branches
Framework graphExplicit nodes and checkpointsIndirection obscures the actual loopYou need to debug a single step quickly
Tools as free functionsSimple to addNo central permission or audit pointTools touch production systems
Tools behind a gatewayPolicy and logging in one placeAnother hop and schema duplicationLatency budget is tight
Trade-off mapInteractive

Good for

Easy to read and change

Cost

Grows into tangled state handling

Fails when

More than a few tools and branches

  1. More than a few tools and branches
  2. You need to debug a single step quickly
  3. Tools touch production systems
  4. 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