GitHub Copilot Agent Mode Explained

Agent mode is the point where Copilot stops proposing and starts doing. Given a goal, it decides which files are relevant, makes changes across them, runs tools and commands, reads the results, and iterates — with you approving as it goes.

It is the most capable thing in your editor and the easiest to use badly. This lesson covers how the loop works, how to scope a task so the result is reviewable, and where it genuinely should not be used.

What agent mode is

In supported IDEs, agent mode takes a task described in natural language and works on it autonomously inside your workspace. Concretely it can:

• Search the codebase to find what is relevant
• Read files you did not mention
• Edit multiple files in one task
• Run terminal commands, subject to your approval
• Read command output — including test failures — and respond to it
• Iterate until the goal is met or it gets stuck

The mental model that works: a capable engineer who joined your team this morning. They have read the repository, they are fast and literal, and they have no idea which parts are load-bearing. Everything about working with agent mode follows from that.

How it differs from autocomplete

Inline completion continues what you are typing, at your cursor, in one file, with no ability to run anything. Agent mode receives a goal, decides where to work, and can execute.

The gap is not incremental. Completion has no notion of a task — it cannot “finish” anything, because it does not know what finished means. Agent mode holds an objective across many steps.

How it differs from chat

Chat is the closer comparison, and the difference is worth being precise about.

That fourth row is the substantive one. Chat is guessing whether its code works. Agent mode can run your test suite, read the failure, and fix it — a feedback loop the assistive layers structurally cannot have.

The loop

A typical session runs roughly like this:

1. You state a goal.
2. It explores — searching, reading files, building a picture.
3. It plans — usually stating what it intends to change.
4. It edits across the files it identified.
5. It runs something — tests, a build, a linter — asking permission first.
6. It reads the output and, if something failed, goes back to step 4.
7. It stops, and you review the diff.

Step 7 is yours and does not get delegated. Everything before it is a draft.

Scoping the task

This is the variable that most determines whether a session goes well, and it is almost entirely under your control.

Compare:

The first invites the agent to touch files you did not expect, make defensible choices you did not want, and hand you a diff too large to read carefully. The second names the target, the constraint, the fixed points, and the definition of done.

Multi-file editing

Multi-file work is agent mode’s clearest advantage, and its clearest risk.

It is excellent at changes that are mechanically consistent across many places: renaming a concept, migrating a call pattern, adding a parameter everywhere it is needed, applying a new lint rule’s fixes.

It is poor at changes that require different judgement in different places — where three of the twelve call sites need special handling, and knowing which three requires context that is not in the code.

Tool use and the terminal

Agent mode can invoke tools, and in supported editors that includes MCP servers — giving it access to external systems you have configured.

The most consequential tool is the terminal. Running commands is what makes the feedback loop possible, and it is also the capability with real-world consequences.

Sensible defaults:

• Approve freely: running tests, linters, type checkers, builds, git status, git diff.
• Read carefully: anything installing dependencies, anything writing outside the workspace.
• Decline or run yourself: anything destructive, anything touching production, anything involving credentials.

Testing and debugging

The workflow that plays to agent mode’s strengths:

That last sentence prevents the most common failure mode. Ask an agent to make tests pass and it may make the tests pass — by editing the assertions. Naming the constraint removes the ambiguity.

Debugging works similarly: give it the real failure and let it verify its own fix by re-running.

Iterative work

Agent mode is a conversation, not a single shot. When the first result is close but wrong, correcting is usually better than restarting:

• “You changed the public signature — revert that part and keep the rest.”
• “The extraction is right, but name it normalise_input rather than helper.”
• “Do not catch the base exception there. Be specific.”

Editors supporting checkpoints let you roll back to an earlier state in the session, which makes exploratory instructions safer — you can let it try something and discard the attempt cleanly. Checkpoints are supported in VS Code, Visual Studio, JetBrains and Xcode.

Permissions and human approval

Two layers of control exist.

Session-level: the approval prompts described above, plus the ability to stop a run at any point.

Policy-level: on Business and Enterprise plans, administrators control which Copilot features are enabled at all, can exclude content from Copilot’s context entirely, and can restrict agentic capabilities by policy. If agent mode is missing in a work environment where it should be present, that is the likely cause rather than a bug.

Giving the agent standing context

Everything in the scoping section is per-task. There is a second layer that applies to every task in a repository, and it is where teams get the largest return.

Repository custom instructions are read as part of the agent’s context. If your instructions file states the test command, the error-handling convention and the directory layout, you stop restating them in every prompt — and, more importantly, the agent stops guessing them differently each time.

# Project conventions

Python 3.12. Run tests with `pytest -q` from the repository root.

## Errors
- Raise specific exceptions, never bare `except:`.
- Error messages name the offending value.

## Structure
- HTTP handlers live in `app/api/`, business logic in `app/services/`.
- Handlers must not contain business logic.

## Tests
- pytest, mirroring the module layout under `tests/`.
- Do not modify existing tests to make a change pass. Raise the conflict instead.

That last line is worth stealing. It converts the single most common agent failure mode — quietly editing assertions until the suite is green — from something you have to remember to forbid into a standing rule.

Beyond instructions, two further mechanisms extend an agent’s reach: prompt files (reusable, named prompt templates checked into the workspace) and agent skills (folders of instructions and supporting resources that teach an agent to perform a specific task well). Both are covered properly in Cluster 6; for now it is enough to know the ceiling is higher than a single prompt box.

Reviewing an agent diff

The review is the part of agent mode that does not scale automatically, and treating it like a normal pull request review is a mistake — the failure modes are different.

Read it in a diff view, not in the editor. Reading changed files in place makes it far too easy to see what you expected rather than what changed.

Check the files you did not ask about. Agents frequently make one “helpful” change outside the stated scope — reformatting a neighbouring function, adding a dependency, adjusting an unrelated import. Those are the changes least likely to be reviewed, because they are not what you were looking for.

Verify the tests still test something. Run the suite with the fix reverted and confirm it fails. A suite that passes both ways is not testing the change.

Look for silently widened behaviour. Broadened exception handling, a loosened type, a removed validation, a default that used to be required. These make things pass without making them correct, and they read as tidy.

Check what it deleted. Diffs draw the eye to additions. Removals — of a guard clause, of a comment explaining why something odd was necessary — are where regressions hide.

Best use cases

Agent mode is well suited to:

• Mechanical refactors across many files — renames, migrations, consistent call-site updates.
• Adding a feature that follows an existing pattern, where four similar implementations already exist.
• Writing a test suite for existing code, particularly parametrised coverage of an established contract.
• Fixing a failing test where the failure is legible from the output.
• Applying a lint or type-checker’s findings across a codebase.
• Scaffolding a new module consistent with the ones around it.

The common thread: the shape of the answer is known and the work is verifiable.

Poor use cases

And badly suited to:

• Work where requirements are still being decided. It will implement one interpretation confidently.
• Subtle correctness — concurrency, floating-point precision, cryptography, authorisation logic. It produces plausible code, and plausible is the failure mode.
• Code you do not understand well enough to review. If you cannot evaluate the diff, you cannot use it.
• Changes with consequences outside the repository — migrations, infrastructure applied to real environments, anything touching production data.
• Very large, open-ended tasks. “Modernise this codebase” produces an unreviewable diff, which in practice means an unreviewed one.

Limitations

• It cannot see beyond the workspace unless a tool provides more.
• It does not know your system — no production behaviour, no incident history.
• It is confidently wrong, with no calibration signal.
• Sessions consume AI credits, and agent runs are considerably more expensive than completions — more so on premium reasoning models.
• Long sessions lose earlier context as the window fills.
• Output is not reproducible. The same task twice gives different diffs.

Cost and model selection

Agent runs are the most expensive thing you can do with a Copilot subscription, and it is worth knowing why before you are surprised by it.

A single agent session may read a dozen files, make several rounds of edits, run the test suite twice and re-read output each time. Each of those steps consumes AI credits, and the total dwarfs what inline completion costs over the same period. On a premium reasoning model, it costs more again.

Two practical consequences:

• Scope tightly for cost as well as for reviewability. A vague task is expensive twice — once in credits spent exploring, once in your time reviewing the sprawl.
• Match the model to the task. A mechanical rename does not need a premium reasoning model. A refactor with subtle invariants might.

If your credits are disappearing faster than expected, agent sessions are almost always the cause rather than completions. See the plans comparison for how the allowances work.

A practical project: a small Python REST API

Here is a task genuinely suited to agent mode. Scope it as follows.

copilot-agent-demo/
├── app/
│   ├── init.py
│   ├── main.py
│   └── models.py
├── tests/
│   └── test_main.py
└── requirements.txt

Then do the part that is yours:

1. Read the diff in full. Every file, not a sample.
2. Check the boundary decisions — what counts as an invalid hostname, and is that the definition you wanted?
3. Verify the tests test the contract, not the implementation. A test asserting the stub was called proves nothing about the endpoint.
4. Run it yourself. Do not take “tests pass” on trust; run pytest -q in your own terminal.
5. Start the service and make a real request.

Next steps

Agent mode has a sibling that is easy to confuse it with. Continue to GitHub Copilot Cloud Agent vs Agent Mode to learn which one a given task belongs to.

For the prompting principles behind the scoped examples above, see Best Practices for Beginners.