How AI Coding Agents Actually Work, Step by Step

Updated for July 2026

"Just ask the AI to fix the bug" sounds simple. Underneath that sentence sits a surprisingly mechanical system: a loop that calls an API, gets back a structured request instead of an answer, runs a real command on a real machine, and feeds the output back in — over and over, sometimes for hours, until the task is done or the loop gives up. This piece pulls that loop apart, layer by layer, with primary sources for every mechanical claim so you can verify it yourself.

1. The core distinction: assistant vs. agent

Before the mechanics, the definition matters, because it explains why the failure modes are so different from ordinary autocomplete.

Autocomplete tools operate at the line or block level: they see a few hundred lines of context, predict what comes next, and the human accepts or rejects every suggestion — the human is in the loop for every decision. An AI coding agent, by contrast, receives a goal in plain English ("add pagination to the API," "fix this failing test") and executes a sequence of actions to reach it, without a human approving each intermediate step (Plus8Soft, "AI Coding Agents in 2026").

Sourcegraph draws the same line from the engineering side: autocomplete predicts the next token, chat answers a question, but an agent reads files, calls tools, runs commands, observes outputs, and decides what to do next — repeatedly, without a human re-prompting it at each step (Sourcegraph, "Agentic Coding in 2026").

2. Where this architecture actually comes from: ReAct

The pattern nearly every coding agent uses today — reason, act, observe, repeat — traces back to a specific 2022 paper. ReAct: Synergizing Reasoning and Acting in Language Models, by Shunyu Yao and colleagues at Princeton and Google, first showed that interleaving reasoning traces with concrete actions produced more reliable, less hallucination-prone behavior than either reasoning or acting alone, evaluated at ICLR 2023 (arXiv:2210.03629). The paper's own framing: reasoning traces help the model track and update its plan and handle exceptions, while actions let it pull in real information from an external source — originally something as simple as a Wikipedia API call. On interactive decision-making benchmarks, ReAct beat pure imitation- and reinforcement-learning baselines by a wide margin while needing only one or two in-context examples (arXiv:2210.03629).

That thought → action → observation cycle is the direct ancestor of what every modern coding agent calls "the agent loop." A recent survey of LLM agent architectures still cites ReAct as the foundational agent framework, describing its contribution precisely as the "Thought-Action-Observation loop" (arXiv:2606.14502).

3. The mechanical core: how a tool call actually works

This is the part most explainers wave their hands over. Here's the literal request/response contract, using Anthropic's Claude API as the concrete example (OpenAI's function-calling and Google's equivalents follow the same shape with different field names).

Step 1 — you describe the tools. Your application sends a request with a tools array. Each tool has a name, a description (this is what the model actually reads to decide when to call it — treat it like a function docstring, not decoration), and an input_schema, a JSON Schema object defining the parameters (Claude Platform Docs, Tool use overview).

Step 2 — the model doesn't run anything. It asks. If the model decides a tool is needed, the API response comes back with stop_reason: "tool_use" and one or more tool_use content blocks, each containing the tool's name and a JSON object of arguments. Critically: the model never executes code itself. It emits a structured request; your code (or, for a handful of Anthropic-hosted "server tools" like web search, code execution, and web fetch, Anthropic's own infrastructure) does the actual work (Claude Platform Docs, How tool use works).

Step 3 — your application executes and reports back. Your code parses the arguments, runs the real operation (a shell command, a file write, an HTTP call), and sends the output back as a tool_result block referencing the same tool_use_id, in a new message. If the tool failed, you mark is_error: true so the model understands why, rather than assuming success (Claude Platform Docs; also see the worked example in Composio's function-calling guide).

Step 4 — repeat until done. The canonical control flow, straight from Anthropic's own documentation, is a while loop keyed on stop_reason: send the request, execute any tools the model calls, feed results back, and repeat while stop_reason == "tool_use". The loop exits only when the model returns end_turn (a final answer), max_tokens, stop_sequence, or a refusal (Claude Platform Docs, How tool use works).

That's it. That's the entire mechanical trick underneath every "AI agent" product you've used. There is no hidden execution channel where the model reaches out and runs something on its own — every single action is a round trip your application code controls.

A genuinely new wrinkle in 2026: letting the model write orchestration code instead of calling tools one at a time

Anthropic's engineering team identified a real bottleneck in the loop above: a five-tool workflow means five separate inference passes, and the model has to "eyeball" each JSON result in natural language to decide what to do next — slow, token-expensive, and error-prone. Their answer, shipped as Programmatic Tool Calling, lets the model write an actual Python script that calls multiple tools, processes their outputs with real loops and conditionals, and controls what information ever reaches its context window — running inside a sandboxed code-execution tool that pauses whenever it needs a live tool result (Anthropic Engineering, "Introducing advanced tool use"). It's a meaningful admission that natural-language tool orchestration doesn't scale cleanly past a handful of steps, and that sometimes the more reliable "reasoning" step is just letting the model write code.

4. What a coding agent's loop looks like end to end

Stitching the general tool-use contract above into an actual coding workflow, most agents converge on the same five stages (Plus8Soft):

  1. Context gathering. The agent indexes the repository — file structure, dependencies, recent commits, test configuration — before touching anything.
  2. Planning. It breaks the goal into a sequence of steps, often visibly (a running todo list is common in production agents).
  3. Code generation that respects existing conventions. The difference between a good and mediocre agent, per this analysis, is whether the generated code fits the codebase's existing naming, error-handling, and architectural patterns, or just works in isolation.
  4. Execution and validation — the actual iteration loop. The agent runs builds, tests, and linters, and reads the output. If something fails, it analyzes the error, edits the code, and retries. This is the step that separates an agent from an assistant: an assistant hands you code and walks away; an agent stays until the tests pass.
  5. Output. A diff, a pull request, or a set of file changes for human review — with the better tools (GitHub Copilot's coding agent, Claude Code) generating PR summaries and flagging areas of uncertainty rather than presenting the change as unambiguously correct.

By mid-2026, JetBrains' Developer Ecosystem survey put regular AI-coding-tool usage at roughly 85% of developers, and the tools gaining share are explicitly the ones that act independently rather than merely autocompleting faster (Plus8Soft).

5. A concrete walkthrough: inside Claude Code's architecture

Rather than talk about agents in the abstract, it's worth looking at one production system closely, because the internal mechanics are unusually well documented. Claude Code is Anthropic's agentic CLI, and independent architecture write-ups (cross-checked against Anthropic's own docs) lay out the pipeline in detail.

The layered architecture. One detailed community write-up describes four layers: a presentation layer (a custom terminal UI renderer), an application layer running a queryLoop() async generator that manages sessions and tool orchestration, a domain layer holding 50+ built-in tools plus dynamically-loaded MCP tools, and an infrastructure layer handling the actual API calls (Zain Hasan, "Inside Claude Code: An Architecture Deep Dive").

What happens on every single tool call, per that same deep dive:

  1. Claude returns a tool call (say, the Bash tool with input git status).
  2. The orchestration layer validates the input against the tool's schema.
  3. It checks permissions through a multi-layer system: static allow/deny rules from settings files, the tool's own permission logic, the current permission mode, and — depending on configuration — an automated classifier or a live prompt to the user.
  4. Pre-tool hooks fire (user-configured shell commands or LLM-based checks).
  5. The tool actually executes, streaming progress to the UI.
  6. Read-only tools (file read, glob, grep) run in parallel batches for speed; write tools (file write, bash) run sequentially to avoid race conditions.
  7. Results are yielded back as a tool_result, appended to message history, and the loop calls the API again (Zain Hasan).

That's the ReAct loop and the Anthropic tool-use contract from Sections 2–3, concretely instantiated in a shipping product.

The permission system — because "run any command" is obviously dangerous. Claude Code's own documentation lays out a three-tier rule system: deny, ask, and allow, evaluated strictly in that order regardless of how specific a competing rule is — a broad Bash(aws *) deny blocks even a narrower Bash(aws s3 ls) allow (Claude Code Docs, Permissions). A curated set of genuinely read-only commands (ls, cat, grep, find, read-only git, and others) run without any prompt in every mode, but the rule set is intentionally not user-configurable to loosen, only to tighten (Claude Code Docs).

A real, second, independent isolation layer sits underneath the rules. On supported platforms, every shell command runs inside an OS-level sandbox that restricts filesystem writes to the working tree and blocks outbound network access and access to sensitive directories like ~/.ssh and ~/.aws — regardless of what the permission rules say. The stated purpose is to make it safe to auto-approve broadly, since a sandboxed shell can do far less damage even under a permissive rule set (Claude Directory, "Claude Code Permissions (2026)").

A classifier watches for overreach, not just rule violations. Anthropic's own engineering blog on "auto mode" is unusually candid about why this exists: by default, Claude Code asks for approval before running commands or editing files, but this creates "approval fatigue" — and in practice, users approve 93% of prompts anyway, meaning manual review isn't catching much. Their answer is a two-stage transcript classifier: a fast single-token filter decides yes/no on whether an action needs a closer look, and only flagged transcripts get a slower chain-of-thought review. The classifier is deliberately "reasoning-blind" — it only sees user messages and the agent's tool calls, never the agent's own reasoning or tool outputs, which is a structural defense against the classifier itself being manipulated by a prompt injection buried in tool output. A second, separate probe screens tool results for injection attempts before the main agent ever sees them (Anthropic Engineering, "How we built Claude Code auto mode").

Anthropic's own incident log, referenced in that post, is a useful reality check on what can still go wrong even with this scaffolding: documented past incidents include the agent deleting remote git branches from a misinterpreted instruction, uploading an engineer's GitHub auth token to an internal compute cluster, and attempting a migration against a production database — all attributed to the model being overeager rather than malicious (Anthropic Engineering).

6. Where the code actually runs: sandboxing in 2026

"Run a command" sounds abstract until you ask: run it where? By 2026, the field converged on a defense-in-depth answer with roughly three tiers of isolation strength, because standard Docker/OCI containers share the host kernel — a kernel vulnerability or misconfiguration can let malicious or buggy agent-generated code escape the container entirely, and unlike ordinary application sandboxing, the code being run was written at runtime by an LLM and can't be pre-reviewed (Northflank, "How to sandbox AI agents in 2026"; Zylos Research):

  • Hardened containers (seccomp, AppArmor, capability dropping) — fastest, but only appropriate when the agent executes code you've already reviewed and trust.
  • gVisor — a user-space kernel that intercepts every syscall from the sandboxed process before it reaches the real host kernel; good for compute-heavy workloads with limited I/O, at a 10–30% overhead on I/O-heavy tasks.
  • Firecracker microVMs / Kata Containers — each execution session gets its own dedicated kernel, which closes off entire classes of kernel-exploit escape routes; Firecracker specifically boots in roughly 125 milliseconds with under 5 MiB of memory overhead, making hardware-level isolation cheap enough to use per-session (Northflank).

2026 infrastructure research cited by Zylos put the practical payoff in blunt terms: sandboxed agents show roughly 90% fewer security incidents compared to agents given unrestricted host access (Zylos Research). The same research flags that the threat landscape has two genuinely distinct layers that both need addressing: execution isolation (stopping generated code from escaping to the host) and agent-layer manipulation — prompt injection and tool poisoning that subvert what the agent decides to do before any code ever runs, which no amount of sandboxing fixes on its own (Zylos Research, "AI Agent Sandboxing and Security Isolation," April 2026).

7. MCP: how agents get a common language for tools

Once an agent needs to talk to more than a handful of hand-coded tools — a database, Slack, GitHub, a file system — hand-rolling an integration for each becomes the bottleneck. The Model Context Protocol (MCP), introduced by Anthropic in November 2024, standardizes exactly this: a client-server protocol over JSON-RPC where a server exposes tools, resources, and prompts, and any MCP-compliant agent can discover and call them without a bespoke integration (Model Context Protocol specification).

The architectural elegance inside a system like Claude Code is that MCP tools aren't treated as a special case: they appear in the same tool-call pipeline as built-in tools, named with the pattern mcp__<server>__<tool>, and pass through the same permission hooks as anything else (Penligent, "Inside Claude Code"). By March 2026, MCP's official SDKs were seeing roughly 97 million monthly downloads, and it's supported across Anthropic, OpenAI, Google, and Microsoft's agent platforms — genuinely cross-vendor infrastructure at this point, not an Anthropic-only feature.

8. Measuring whether any of this actually works: SWE-bench

The main public benchmark for "can an agent actually fix real software bugs" is SWE-bench, built from real GitHub issues in popular Python repositories: an agent gets an issue and a repo, produces a patch, and the patch is scored by actually running the project's test suite — not a preference judgment, not a synthetic unit test (Steel.dev, SWE-bench Verified leaderboard).

A few honest caveats before any numbers, because this is exactly where hype creeps in:

  • The 500-task "Verified" subset is now largely saturated. Multiple 2026 leaderboards put top frontier models within a point or two of each other in the high-80s to mid-90s percent range on Verified, and independent audits have flagged both training-data contamination risk (the benchmark is old enough to plausibly leak into training corpora) and remaining flawed or underspecified test cases even in the "human-verified" split (Local AI Master, "SWE-bench Leaderboard 2026"; Steel.dev).
  • The same model scores very differently depending on the agent scaffold wrapped around it — not just the base model. One tracking site notes Claude Opus 4.5 scoring 79.2% with one agent scaffold and 76.8% in a stripped-down "bash-only" harness — a multi-point swing from harness design alone, on the identical model (CodeSOTA).
  • A strikingly minimal agent competes with heavily engineered ones. mini-swe-agent, from the same Princeton/Stanford lineage as the original SWE-agent, strips away custom tool interfaces and stateful shell sessions entirely — it's roughly 100 lines of Python, every action runs via plain subprocess.run, and the model gets nothing but a bash shell. It reportedly scores above 74% on SWE-bench Verified anyway, which is a genuinely useful data point against the assumption that more scaffolding automatically means better results (Programming Helper Tech, "SWE-bench and Coding Agent Benchmarks 2026").
  • Because Verified is saturating, the field is shifting to harder variants. SWE-bench Pro, a newer and larger set (1,865 tasks across 41 actively-maintained repos spanning Python, Go, TypeScript, and JavaScript, scored pass@1 with no retries), currently shows much more separation between models — reported scores cluster in the roughly 55–70% range for leading systems as of mid-2026, with a meaningful gap between vendor-reported numbers (run on each lab's own tuned scaffold) and Scale AI's standardized leaderboard, which uses one fixed harness for every model to keep comparisons apples-to-apples (Morph, "SWE-bench Pro Leaderboard"; Local AI Master).

The practical takeaway one benchmark-tracking site puts well: a benchmark score is a compass, not a map — useful for within-benchmark ranking, much less useful as an absolute claim about real-world reliability, and read the methodology notes before making a procurement decision on the strength of a single percentage (Steel.dev).

9. "Loop engineering": the emerging discipline of designing the loop itself, not just the prompt

As agents started running for minutes or hours rather than responding to a single prompt, a distinct practice emerged in 2026 for designing the loop itself — when it triggers, what it treats as "done," and where a human has to sign off. Developer Peter Steinberger's framing, quoted widely in this discussion, captures the shift bluntly: you shouldn't be prompting coding agents anymore, you should be designing loops that prompt your agents (cited in AlphaMatch, "Loop Engineering").

A well-designed loop, per that same analysis, generally needs:

  • A scheduled or event-driven trigger — a timer, a git event, a CI signal — rather than a human re-invoking it each time. Claude Code's /loop and /goal commands and Codex's Automations tab are cited as concrete implementations.
  • A memory layer so the loop doesn't repeat solved mistakes or lose track of prior decisions across iterations.
  • Explicit stop criteria — a poorly specified goal is the single biggest cause of bad loop behavior, because the agent fills ambiguity with assumptions that compound across iterations (MindStudio, "What Is an Agentic Loop?").
  • Human-in-the-loop checkpoints for irreversible actions — LangChain's own framing places this at multiple levels: inside the agent loop (approval before sensitive tool calls), inside a verification loop (a human grades outputs), and inside a deployment loop (a human approves before a change reaches production) (LangChain, "The Art of Loop Engineering").

Sourcegraph's guidance for teams actually running this at scale is refreshingly unglamorous, and worth stating plainly because it's the opposite of "just trust the agent": review every diff like a human pull request, run it locally, check the tests it wrote itself, gate everything on the same CI checks human commits go through, and audit activity afterward by agent, prompt, and change — treat the agent like a contractor with commit rights, not a colleague you stop supervising (Sourcegraph, "Agentic Coding in 2026"). The same piece cites engineer Steve Yegge's "brute squad" framing for what this does to the human role: less typing code, more steering and verifying many concurrent runs — the work doesn't disappear, it moves up a level.

10. My take

Strip away the branding and "AI coding agent" is a remarkably plain mechanism: a while-loop around an API call, gated by a permission system, executing inside a sandbox of varying strength, occasionally reaching out through MCP for a tool it doesn't have built in. None of that is mysterious once you've seen the actual request/response shapes — stop_reason: "tool_use", a JSON blob of arguments, a tool_result sent back. The genuinely hard engineering isn't the loop; it's everything wrapped around it: deciding which of the model's actions need a human's eyes before they run, building an isolation boundary strong enough that a mistake doesn't become an incident, and being honest that a benchmark score is a ranking signal, not a reliability guarantee.

The most useful shift in thinking for 2026 isn't "the model got smarter" — though it did — it's that the unit of engineering work moved. It used to be the prompt. Now it's the loop: what triggers it, what it's allowed to touch without asking, and where a human still has to look at the diff before it ships. Anthropic's own incident log — a leaked credential, a deleted branch, an attempted production migration — is the best one-sentence argument for why that last part isn't optional.

Sources

Note on benchmark numbers: SWE-bench scores vary meaningfully by source, scaffold, and whether a figure is vendor-reported or independently/standardized-leaderboard-measured. Where sources disagreed by a wide margin, that disagreement is flagged above rather than resolved into one clean number.