This chapter takes a closer look at how coding agents work behind the scenes, from their underlying architecture to how they interact with your codebase and carry out tasks.

Most coding agents have three main components: a language model, an agent harness, and an execution environment.

Let's understand how each one works.

The Language Model

The language model is the brain behind the agent. It understands your instructions, analyzes code, reasons through problems, and decides what to do next.

However, the model doesn't directly access files or run commands. Instead, it generates responses, including requests to use tools.

This is where the agent harness comes in.

The Agent Harness

The harness connects the model to the outside world. It manages the conversation, provides access to tools, executes permitted actions, and sends the results back to the model.

The Execution Environment

Finally, the execution environment is where the actual work happens.

It could be your local machine, a Docker container, a virtual machine, or an isolated cloud environment.

This is where the agent reads and edits files, runs commands, and executes tests.

Together, these components allow a coding agent to work on real software projects, rather than simply generate code.

Let's say you give a coding agent this task:

Fix the bug where changing a user's display name doesn't persist after refreshing the page. Add a regression test and don't modify unrelated functionality.

What happens behind the scenes?

First, the agent harness prepares your request for the language model, along with additional context.

This may include system instructions, available tools, permissions, the working directory, conversation history, and project-specific guidelines.

For example, your repository might have an AGENTS.md or CLAUDE.md file describing its architecture, coding conventions, and testing commands. A short one might look like this:

Depending on the agent, these instructions may also be included in the model's context.

The key thing to understand is that the model doesn't automatically know your entire codebase. It starts with the context provided by the harness and uses tools to gather any additional information it needs.

So how does the agent actually explore your codebase and make changes?

That's where tool calling comes in.

Tool calling is what allows a coding agent to interact with your development environment.

Most coding agents have tools to search code, read and edit files, run terminal commands, and inspect Git changes. Some can also interact with browsers, databases, and external services.

When the model needs to use a tool, it generates a structured request.

For example, it might ask the terminal to search for references to the displayName field:

But the model doesn't execute the command itself.

Instead, the harness receives the request, checks permissions when required, executes the command, and collects the result.

The result might contain matching files, source code, error messages, or test output. The harness then sends this information back to the model.

With this new context, the model can decide what to do next.

This is what makes coding agents different from simple code generators. Instead of relying entirely on your initial prompt, they can explore your codebase, gather information, and make decisions based on what they discover.

At the heart of a coding agent is the agentic loop.

It's a repeating cycle where the agent gathers information, decides what to do, uses tools, observes the results, and continues until the task is complete.

Let's see how this works with our example.

The agent starts by searching the codebase for the profile settings page and the API responsible for updating user information.

It finds a frontend component and a backend endpoint. After reading both, it notices something interesting.

The frontend sends a field called displayName, but the backend expects display_name. The project notes say API fields use camelCase, so the backend is the side that breaks the rule.

Here's a simplified version of the code:

This could explain the bug, but the agent doesn't stop there.

It inspects the backend logic and confirms that unexpected fields are ignored, while the API still returns a successful response.

So the frontend shows a success message, even though the database was never updated.

Now that the agent understands the root cause, it can fix the field mismatch, add a regression test, and verify the changes.

Before making changes, a coding agent may first create a plan.

For a simple bug fix, this might involve identifying the relevant files and deciding what to modify.

For larger tasks, the plan could involve updating APIs, modifying database logic, adding tests, and verifying that everything works together.

Some coding agents even have a dedicated planning mode, where they explore the codebase and propose an approach without making any changes.

Planning is especially useful because even small changes can have hidden dependencies. A frontend update might also require changes to the backend, shared types, or existing tests.

However, a plan isn't a guarantee of correctness. The agent can still misunderstand the architecture or overlook important details.

That's why it's worth reviewing the plan before allowing the agent to make significant changes.

And remember, plans should be flexible. If the agent discovers something unexpected, it should adjust its approach rather than blindly follow the original plan.

Once the agent understands the problem, it can start making changes.

In our example, it might fix the field name mismatch in the backend and add a regression test to make sure profile updates work correctly:

Depending on the tool, the agent can edit files directly or run commands to modify them.

Unlike a chatbot that simply generates code for you to copy, a coding agent makes changes directly in your project, often across multiple related files.

However, that doesn't mean every change will be correct.

The agent might fix the problem in the wrong place, introduce inconsistencies, or accidentally break unrelated functionality.

For example, fixing the backend field name solves our immediate bug. But we could also improve the backend to reject unexpected fields instead of silently returning success.

A good agent should recognize these trade-offs and help you choose the right approach.

And making changes is only half the job. The next step is verifying that those changes actually work.

One of the most important capabilities of coding agents is their ability to verify their own changes.

After editing code, an agent can run tests, builds, type checks, or linters to catch problems.

For example, suppose our new regression test fails. The error reveals that while the backend now reads the correct field, another part of the application still expects the old response format.

The agent can inspect the failure, identify the issue, make another change, and run the test again.

This is called a feedback loop.

Instead of generating code and hoping it works, the agent uses actual results to identify problems and improve its implementation.

Verification can go beyond automated tests.

However, passing tests don't guarantee correctness. Tests only check the scenarios they cover, so missing edge cases can still lead to bugs.

Real-world projects can contain thousands of files, but language models have a limited context window, which determines how much information they can process at once.

This includes your instructions, source code, conversation history, tool calls, and their outputs.

Loading an entire codebase would quickly fill that window.

Instead, coding agents typically search for relevant files and read only the sections they need, gathering more context as they work.

As the conversation grows, the harness may also compact older information by summarizing it to free up space.

However, compaction can lose important details.

For example, if a summary mentions that a field name mismatch was fixed but leaves out the project's camelCase naming convention, the agent might introduce a similar bug later.

That's why clear documentation, well-organized code, and focused tasks help coding agents work more reliably.

So far, we've focused on files and terminal commands. But coding agents can also interact with external services.

For example, an agent might need to read a GitHub issue, search internal documentation, or inspect application logs.

One way to enable this is through the Model Context Protocol (MCP).

MCP is an open standard that lets AI applications connect to external tools and data sources through a common interface.

An MCP server exposes capabilities that the agent's host application can make available to the model.

For example, a GitHub integration might let the agent read issues and pull requests, while another integration provides access to application logs.

This makes coding agents more useful because real software development involves much more than writing code.

However, MCP isn't required for agentic coding. Many agents already have built-in tools for common tasks.

And adding more integrations doesn't necessarily make an agent better. Each connection introduces additional permissions, complexity, and potential failure points that need to be managed.

Since coding agents can run commands and modify files, security is an important consideration.

An agent could accidentally delete important files, change production settings, or expose sensitive information.

That's why coding agents often use sandboxing and permission controls.

A sandbox limits what an agent can access, such as specific directories, network connections, or sensitive files.

Permission controls determine which actions require your approval.

For example, an agent might be allowed to read files and run tests, but need permission before accessing the network or running destructive commands.

Another important risk is prompt injection.

This happens when an attacker places malicious instructions in a file, webpage, or tool response that the agent reads.

If the agent mistakes those instructions for legitimate commands, it could perform actions you never requested.

The key principle is simple: give coding agents only the access they need, and require approval for sensitive actions.

Some coding agents can delegate parts of a task to other agents, known as subagents.

For example, suppose you ask an agent to improve an application's performance.

One subagent might investigate slow database queries, another could analyze frontend rendering, while a third explores caching opportunities.

Each subagent works with its own context and reports its findings to the main agent, which combines the results and decides what to do next.

This allows independent tasks to run in parallel, potentially saving time.

It also helps manage context, since the main agent can receive summaries instead of every detail from each investigation.

However, more agents don't always mean better results.

Subagents introduce coordination overhead, consume additional resources, and can create conflicts if they modify the same files.

For smaller tasks, a single agent is usually enough. Subagents are most useful when work can be divided into independent tasks with clear responsibilities.

We've seen how coding agents repeatedly inspect, edit, and verify code. But how do they know when to stop?

Typically, the loop ends when the model stops requesting tools and produces a final response.

The agent should then summarize what it changed, which checks it ran, and whether anything remains unresolved.

An agent might stop for several reasons:

These limits matter because every model request and tool call consumes time and resources.

Without clear stopping conditions, an agent might spend too long investigating a minor issue or repeatedly attempting a fix that isn't working.

That's why it's important to define clear success criteria before starting a task.

For our example, that means:

These are much more useful instructions than simply telling the agent to "fix the code."

Clear success criteria help agents stay focused, verify their work, and know when the task is complete.

To recap, a coding agent has three main components: the language model makes decisions, the agent harness coordinates actions, and the execution environment is where the actual work happens.

The model starts with the context provided by the harness, including your instructions, available tools, permissions, conversation history, and project guidelines. It gathers additional information through tools.

Tool calling allows the agent to search code, edit files, and execute commands. The harness manages these actions and sends the results back to the model.

The agentic loop follows a simple cycle: gather information, reason, act, observe results, and repeat.

Planning helps identify dependencies before making changes, while verification allows agents to catch mistakes and improve their implementations.

Since context windows are limited, agents retrieve relevant information as needed and may summarize older context to free up space.

MCP enables integration with external tools and services, while permissions and sandboxing help control what agents can access and execute.

Subagents can work on independent tasks in parallel, but introduce additional coordination and resource costs.