Companion article
Anatomy of a coding-agent turn
Follow a coding request from context assembly through tool calls, execution, verification, and a final response.
One user request can contain several decisions
“Fix the empty search state and run the tests” sounds like one exchange. For a coding agent, it can require reading a component, inspecting tests, editing files, running checks, and examining the result. This glossary calls the user-visible span a turn. It can contain several model provider requests.
The harness coordinates that work. It assembles instructions, selected history, tool descriptions, and the latest request. The model chooses a response or an action. The harness then executes an allowed action and supplies its result for a later decision. A model response that requests a tool is an intermediate output, not evidence that the requested operation has happened.
| Concept | Responsibility | Example |
|---|---|---|
| Tool | Expose an operation with an input and a result. | Read src/Search.tsx or execute a test command. |
| Agent | Choose actions and respond to observations toward a goal. | Read the component, change the empty state, then verify it. |
| Harness | Assemble context and enforce the execution lifecycle. | Validate a requested command, execute it, and return its exit status. |
Read the observable sequence
The following transcript is an illustrative example, not a recorded run or benchmark. It leaves out transport fields and any private internal reasoning. Each numbered request represents another invocation of the model; real tools may batch work or return asynchronously.
User: Fix the empty search state; preserve keyboard navigation.
Harness: Supplies project instructions and available tools.
Model request 1 -> read_file("src/Search.tsx")
Tool result -> Component source, with its path.
Model request 2 -> apply_patch(empty-state change)
Tool result -> Patch applied to src/Search.tsx.
Model request 3 -> run_tests("search interactions")
Tool result -> Exit 0; lists the tests that actually ran.
Model request 4 -> Inspect coverage and remaining requirements.
Assistant: Reports the change, checks, and anything unverified.Check each boundary before moving on
Before the first decision, context must match the task: the right repository, relevant instructions, and current acceptance criteria. Before execution, the harness must validate arguments and apply permissions. A model’s confidence cannot grant access that the environment does not allow. A denied call is useful feedback, not a reason to silently bypass the boundary.
After execution, the result needs enough detail to support a decision. A patch receipt identifies what changed; a test report identifies what ran. A process that is still running needs a later completion result. A truncated log may require a narrower follow-up. The agent should not equate a successful request to start a job with that job finishing.
Before stopping, compare the artifact with the user’s request. For the search example, tests that only check the empty-state wording do not cover keyboard selection. The remaining requirement calls for an interaction test or a browser check. The final answer should distinguish checks performed from behavior that remains unverified.
A runtime’s “turn” may mean something narrower
The OpenAI Agents SDK counts a model invocation as a turn for its max_turns limit. That is narrower than this glossary’s user-facing definition. When a trace says “maximum turns exceeded,” check the runtime’s definition instead of counting user messages. Likewise, a handoff may transfer control to a specialist, while a tool that calls another agent may return control to the caller.
A tool can internally use a model, and an agent can be exposed as a tool. The distinction is about the boundary you are inspecting: what operation does the caller request, what result does it receive, and who owns the next decision? It is not a rule that every tool is simple or deterministic.
Try it: audit one small turn
In a disposable copy of a repository, ask an available coding agent to change one visible label and preserve the relevant behavior. Supply the test command and require a final report of the changed file and checks. Do not publish the change. Save the observable tool log, product/version, model if exposed, settings, starting revision, and requested acceptance criteria.
Make a four-column ledger: request, tool arguments, result, and what that result proves. Count provider requests only if the trace exposes them; do not guess from progress messages. Mark any requested operation with no completion result. Then compare the final diff and test coverage with the original request. This is a repeatable inspection procedure, not a claim about how many calls a particular agent will use.
If the ledger contains green calls but the requirement is still unmet, continue with why tool success can still mean task failure. The useful question is where evidence stopped supporting the next decision.