GitHub Copilot Agents: Complete Guide

GitHub Copilot Agents: Complete GuideAgents, MCP & Agentic Development1Intermediate → Advanced/github-copilot/agents/

Everything in Clusters 1 through 6 improved what Copilot said. This cluster is about what it does.

An agent reads your repository, chooses tools, edits files, runs commands, calls external systems, and iterates when something fails. That capability is the whole value and the whole problem: a suggestion you ignore costs nothing, and an action taken on your behalf has already happened by the time you evaluate it.

Key takeaways

• “Agent” names 5 different things at GitHub, with genuinely different capabilities. Advice that does not name a surface is advice about nothing.
• The current term is “Copilot cloud agent”. Writing you will find calls the same thing the “coding agent”.
• Agent mode edits your local tree. The cloud agent runs in a GitHub Actions-powered environment and opens pull requests. These are not variations of one product.
• The cloud agent uses available MCP tools autonomously and does not ask before use. Approval there is at the pull request, not per action.
• A custom agent’s tools list is the only part that constrains rather than suggests. Omitting it grants everything.
• Autonomy is a dial, not a switch. Most useful agent work sits lower on it than the discourse suggests.

The naming problem, first

Before anything else: the words. GitHub’s agent vocabulary has moved, and stale terminology is the single biggest source of confusion in third-party writing.

Copilot cloud agent — also seen as coding agent

Runs on GitHub in a GitHub Actions-powered environment, works on a branch, opens a pull request.

Agent mode

Runs inside your IDE and makes autonomous edits in your local working tree.

Copilot CLI

A terminal agent on your machine with file and shell access, governed by tool permissions.

Custom agent — also seen as agent profile

A named agent defined in a .agent.md file, with its own instructions and restricted tool list.

GitHub Agentic Workflows

Markdown automations compiled into GitHub Actions workflows. Public preview.

What each surface can actually do

This is the table the rest of the cluster depends on.

What each Copilot agent surface can do

Capability	Agent mode (IDE)	Copilot cloud agent	Copilot CLI	Copilot code review	GitHub Agentic Workflows
Runs in	Your editor, on your local working tree	GitHub, in a GitHub Actions-powered environment	Your machine, with your shell and your credentials	GitHub, against a diff	GitHub Actions, from markdown compiled to a workflow
Reads the repository	Yes	Yes	Yes	Partial	Yes
Modifies files	Yes	Yes	Yes	No	Partial
Executes commands	Yes	Yes	Yes	No	Yes
Opens pull requests	No	Yes	Yes	No	Partial
Custom agents	Yes	Yes	Yes	Not documented	Not documented
Agent skills	Yes	Yes	Yes	Not documented	Not documented
MCP	Yes	Yes	Yes	Yes	Not documented
Subagents	Not documented	Not documented	Yes	No	No
Per-action human approval	Yes	Partial	Yes	Yes	Partial

• Agent mode (IDE). Changes appear as a diff you review in the editor before they land.
• Copilot cloud agent. Approval is at the pull request, not per action. GitHub states Copilot uses available MCP tools autonomously and will not ask before use.
• Copilot CLI. Per-tool approval, configurable with --allow-tool and --deny-tool. Covered in Cluster 5.
• Copilot code review. Reviews changes and comments. Sees the diff rather than the whole repository.
• GitHub Agentic Workflows. Public preview. Read-only repository permissions unless explicitly granted more; outputs are constrained by the safe-outputs configuration.

Read down the columns. The differences that catch people:

Agent mode cannot open a pull request. It edits your working tree; publishing is still yours.

The cloud agent’s approval is at the pull request. GitHub states plainly that Copilot uses available MCP tools autonomously and will not ask for approval before use. That is a different trust model from the CLI, where every tool call can be gated.

Code review sees a diff, not a repository. Which is why it cannot see absences — a missing authorisation check is not in the diff.

Subagents are documented for the CLI and not for the other surfaces. “Not documented” in that table means exactly that, not “no”.

The autonomy scale

The most useful thing this cluster can give you is a way to say how much autonomy a piece of work actually needs.

1. 1
2. 2
3. 3
4. 4
5. 5
6. 6

Two observations that come from using it.

Most valuable agent work is level 1 to 3. Understanding a codebase, finding where a bug lives, writing tests, running validation. The high levels attract the attention and produce a minority of the value.

Each level up removes a place where you could have caught a mistake. Level 2 gives you a diff. Level 4 gives you an artefact someone else can already see. Level 5 gives you an incident.

An agent is not a better chat

The distinction worth internalising is not capability, it is reversibility.

1. 1
2. 2
3. 3
4. 4

In chat, being wrong costs you the time to read a bad answer. In an agent with tool access, being wrong can cost a branch, a comment on someone’s issue, a deployed change. The model has not become less reliable — the consequences of its mistakes have moved.

Everything this cluster teaches about permissions, tool scoping and review follows from that single shift.

What an agent actually is

Strip away the marketing and an agent is a loop.

It reads something — your request, the repository, the output of the last thing it did. It decides on an action. It takes that action using a tool it has been given. It looks at what happened. Then it goes round again, until it decides the work is finished or you stop it.

Everything distinctive about agents follows from that loop. They can recover from a failure, because the failure is an input to the next iteration. They can work for a long time without you, because each step produces the context for the next. And they can go a long way wrong before anyone notices, for exactly the same reason.

The pieces this cluster covers are all ways of shaping that loop: what it may read, which actions it may take, what expertise it brings, and who checks the result.

The maturity model

Teams adopt agents in a recognisable order, and the order matters because each step teaches you what the next one will get wrong.

1. 1
2. 2
3. 3
4. 4
5. 5
6. 6
7. 7

Skipping steps is where trouble comes from. A team that starts at step six — wiring an agent to production systems through MCP before it has watched an agent work on a diff — has no calibration for what the agent gets wrong, and no habits for catching it.

The steps are also not a ladder you must climb. Plenty of productive teams stop at three permanently. The question is never “how agentic are we” but “what does this piece of work actually need”.

When an agent is the wrong tool

Worth stating early, because the enthusiasm runs the other way.

When you want to understand rather than change. Chat is better. An agent given a question will often start doing things, and the doing obscures the answer. If you catch yourself saying “no, just tell me”, you wanted chat.

When the task is one edit you could make faster yourself. The overhead of framing, waiting and reviewing exceeds the work.

When you cannot describe done. An agent optimises toward the finish line you gave it. No finish line means it invents one, and its invention will be plausible and not yours.

When the blast radius is large and the confidence is low. New codebase, production system, irreversible operation — the combination that produces incident reports.

When the real problem is missing context. Cluster 6’s central point applies with more force here: an agent that cannot see the constraint will act on its absence rather than merely talk around it.

The corollary is where agents genuinely shine: bounded, verifiable, tedious work in a codebase you know, with a test suite that can tell you whether it worked. Adding coverage. Migrating a pattern across forty files. Finding every call site. Turning an issue into a first draft.

The pieces, and what each is for

Six mechanisms are easy to conflate. They are not alternatives; they compose.

Cluster 6 covered the first three. This cluster covers the last three, and the distinction that matters most is between the ones that advise and the one that constrains: a custom agent’s tools list is enforced. Everything else is guidance a model usually follows.

Built-in agents

Before writing one, know what already exists.

• exploreRead onlyRead-only codebase analysis.
• taskCan actRuns development commands.
• general-purposeCan actFull Copilot capabilities.
• code-reviewRead onlyAnalyses changes for substantive issues.
• researchRead onlyExhaustive investigation using GitHub and web sources.
• rubber-duckRead onlyAn independent critique, using a different model.

Three are read-only by construction: explore, code-review and research. Those are the right default for a repository you do not fully trust, and reaching for one first is a habit worth forming.

MCP, in one paragraph

Model Context Protocol lets an agent call tools that live outside Copilot: your issue tracker, your documentation, your cloud provider, GitHub itself. Copilot is the MCP client; the thing exposing tools is the server.

That is the single largest expansion of what an agent can reach, and therefore the single largest expansion of what it can get wrong. The MCP guide covers it properly, including the security model, and connecting servers covers the per-client configuration — which differs enough that copied examples fail silently.

Tool permissions are the real control

Every other control in this cluster is advisory. Tool permissions are not.

An instruction saying “do not deploy” is a sentence a model usually honours. An agent whose tools list omits the deploy tool has no deploy tool to call. The difference is not a matter of degree — one is a request and the other is an absence of capability.

This produces a design rule that runs through every remaining lesson:

What is the worst thing this agent could do if it completely misunderstood my request?

If the answer is bad, remove the tool rather than adding a rule about it.

Three practical forms of that rule.

Omit rather than forbid. A custom agent with tools: ["read", "search"] cannot write. A custom agent with every tool and an instruction not to write is a different, weaker thing.

Default to read-only and widen deliberately. The three read-only built-ins exist for this. Starting from explore and finding it insufficient is a much better path than starting from general-purpose and hoping.

Scope the MCP toolset. GitHub’s own guidance is to set the tools field to only what is needed rather than enabling everything — for performance, and because every enabled tool is attack surface.

Repository trust and prompt injection

An agent reads your repository. Repository content is text. Text can contain instructions addressed to the agent rather than to you.

That is not a hypothetical risk category invented for a security section — it is the same mechanism that makes AGENTS.md useful, pointed the other way. A README, an issue body, a code comment, a dependency’s documentation, or an MCP server’s response can all carry text intended to steer the agent.

Cluster 5 treats this in the CLI context, where the agent has shell access and the stakes are highest. The mechanism is identical everywhere; only the blast radius changes.

Human in the loop

The phrase is used loosely enough to be meaningless. Concretely, there are six places a human can stand, and choosing which ones you keep is the actual design decision:

1. 1
2. 2
3. 3
4. 4
5. 5
6. 6

Different surfaces offer different subsets. The CLI can gate every tool call. The cloud agent gates at the pull request. Agentic workflows gate through Actions permissions and safe outputs.

The one habit that matters most

If you take a single practice from this cluster, take this one: before you start an agent session, commit your work and decide what “done” looks like.

Both halves do real work. The commit makes every mistake recoverable, which changes how much risk you can afford to take with the instruction. The definition of done gives the agent a target it cannot invent, which is the difference between a session that converges and one that keeps going until you stop it.

Everything else in the next twelve lessons — tool lists, custom agents, skills, MCP, workflows — is refinement on top of that. Teams that get the basics right and adopt the rest slowly do better than teams that build elaborate agent configurations before they have watched an agent work at all.

The rest of this cluster is arranged so you can do exactly that: the surfaces first, then the ways to shape them, then the systems they can reach, then the roles worth building. Read it in order the first time. Come back to individual lessons as reference afterwards.

Vocabulary, and why it keeps shifting

This area’s terminology has moved faster than anything else in Copilot, and the churn is a genuine obstacle rather than a pedantic complaint. Documentation, blog posts and your colleagues are frequently describing the same thing with different words, or different things with the same word.

The table above pins the current usage. Three distinctions are worth stating plainly because getting them wrong changes what you build.

“Agent mode” is a mode, not an agent. It is the editor behaviour in which Copilot plans and edits across files. It is not a named role you configure, and switching to it does not select an agent.

“Custom agent” and “cloud agent” are unrelated. A custom agent is a configured role — a file with a name, a description and a tool list. The cloud agent is a hosted service that works on your repository and opens pull requests. You can have either without the other. GitHub’s documentation has used “coding agent” for the hosted service and increasingly uses “cloud agent”; where you see the older term, it means the same thing.

“Agentic workflow” has a specific meaning here. It refers to GitHub Agentic Workflows — markdown files with YAML frontmatter that compile into GitHub Actions workflows — and not to the general idea of a workflow that involves an agent. It is in public preview, which is worth knowing before you build on it.

The practical advice is to check dates on anything you read about agents, including this page. Material from more than a few months ago may describe mechanisms that no longer exist, file locations that have moved, or capabilities that have since become defaults. Each lesson here carries its verification date for that reason.

Reading the agent’s work

Reviewing an agent’s output is a different skill from reviewing a colleague’s, and treating it as the same is where most of the disappointment comes from.

A colleague’s pull request carries an implicit guarantee: they understood the problem, they had a reason for each choice, and if they were unsure they would have said so. None of that holds for an agent. The output is fluent, internally consistent and complete-looking whether or not it is right, and fluency is precisely the signal your review instincts are calibrated on.

Three habits compensate.

Check the premise before the implementation. The most expensive agent mistakes are not bugs — they are correct implementations of the wrong thing. An agent asked to fix a flaky test will make the test pass, which is not the same as fixing the flakiness. Read the first paragraph of its summary against your actual request before you read a line of the diff.

Look hardest at what you did not ask about. Agents fill gaps. A request to add a function may arrive with a refactor of the file around it, a new dependency, and a changed default. Each may be reasonable. None of them were requested, and they will be the parts you skim.

Treat passing tests as one input, not a verdict. An agent that can edit tests can make tests pass. Check that the test still asserts what it asserted before.

Cost, latency and the request model

Agentic work consumes premium requests differently from chat, and the difference is structural rather than incidental.

A chat turn is one exchange. An agent turn is a loop: read, act, observe, decide, repeat. Each cycle is model work. An agent that runs for twenty steps has done roughly twenty times the model work of a single answer, and the multiplier compounds when several agents run in parallel.

That is not an argument against agents — twenty steps of automated work for the price of twenty requests is often an excellent trade against an hour of yours. It is an argument for two specific habits.

Scope tightly. An open-ended task on a large codebase can loop for a long time. “Update the three files that use this helper” costs a fraction of “modernise this module” and is usually what you meant.

Watch the first few runs. Cost intuition for agents is not transferable from chat, and the only reliable way to build it is to observe your own usage against your own tasks. Cluster 6’s request model lesson covers how the multipliers work.

Latency follows the same pattern. Agent mode’s loop is slower than a chat answer, and the cloud agent works on GitHub’s schedule rather than yours. The cloud agent’s asynchrony is a feature when the task is genuinely background work and a frustration when you are waiting on it — which is a reason to choose the surface by how you intend to spend the next twenty minutes, not only by capability.

Team adoption

Individual use of agents is a personal productivity question. Team use is a configuration-management question, and it arrives faster than most teams expect.

The moment more than one person has a custom agent, you have a shared surface with no owner. Two people write a reviewer agent with different tool lists and different opinions. An MCP server appears in one person’s configuration and not another’s, so the same prompt behaves differently on two machines. A skill lands in the repository and nobody knows whether it is maintained.

The remedy is unglamorous and works: commit the configuration, review it like code, and keep it small.

Commit what should be shared. Repository-level agents, skills and instruction files belong in version control, where they are reviewable and their history is visible. Personal experiments belong at the user level.

Review agent and skill changes as code changes. They are configuration for automation with tool access. A pull request that adds a tool to an agent’s list is a permission change and should be read as one.

Prefer fewer, sharper agents. A team with four agents everybody understands is better off than one with fifteen nobody can distinguish. Agents accumulate easily and are almost never deleted.

Decide MCP centrally. Which servers are approved, who runs them and what credentials they use are decisions with security consequences. Copilot Business and Enterprise gate this behind an organisation policy for exactly that reason, and the policy is a good forcing function even where you could work around it.

A practical architecture

The pieces assemble into a shape that most working setups converge on, and seeing it whole makes the individual lessons easier to place.

1. 1
2. 2
3. 3
4. 4
5. 5
6. 6
7. 7

Each layer answers a different question. Instructions answer how do we work here. The agent answers what is this one for, and what may it touch. Skills answer how is this particular job done. MCP answers what else can it reach. Tools answer what can it actually do. Validation and review answer was it right.

The failure mode is putting content in the wrong layer. A rule that belongs in instructions duplicated into six agent files. A capability restriction written as prose instead of a tool list. Expertise embedded in an agent’s description when it should be a skill available to several agents. None of these break anything immediately; they produce a configuration nobody can reason about six months later.

Authentication and least privilege

Agents act with an identity, and which identity is one of the least examined questions in this area.

In the CLI, the agent acts as you. Your shell, your credentials, your group memberships. There is no reduced privilege set unless you arrange one.

In the cloud agent, work happens in a GitHub Actions-powered environment, and the default GitHub MCP connection uses a specially scoped token with read-only access to the current repository. That default is a good one, and it can be replaced with a broader token, which is where care is required.

In agentic workflows, permissions are read-only unless explicitly granted more — the same posture Actions uses generally.

The through-line is that the safest defaults are the ones you did not change, and most incidents in this space start with widening a permission to make something work and never narrowing it again.

Designing an agent that earns its place

The agents worth building share a shape, and it is narrower than most people expect on their first attempt.

One job. An agent that reviews security, writes tests and updates documentation is a general-purpose agent wearing a name badge. Narrowness is what makes a restrictive tool list possible and what makes output predictable enough to rely on.

A tool list written before the prose. Decide what it must not be able to do, then write the list, then write the instructions. Doing it the other way round reliably produces a file whose description and capabilities disagree.

Knowledge your team actually has. A “security expert” agent is the same model with different framing — it does not know more about security than it did. What it can hold is your accumulated specifics: the mistake that caused an incident in March, the pattern your codebase uses, the constraint nobody writes down. That is the content that makes an agent better than a prompt.

A stated output format, including the empty case. “If you find nothing, say so plainly” prevents the agent manufacturing marginal findings because reporting nothing feels like failing.

Something that verifies it. Plant a defect of the kind the agent exists to catch and confirm it is reported. An agent that reports nothing might be working perfectly or might be misconfigured, and without a positive control the two are indistinguishable.

Subagents and delegation

Where supported, an agent can hand a bounded question to another agent that works in its own context and returns a conclusion rather than a transcript.

GitHub documents subagents for Copilot CLI; the matrix above records the other surfaces as not documented, which means exactly that. Cluster 5 covers the CLI’s implementation — /tasks, fleet mode, per-agent model configuration.

The benefit is context isolation. A subagent asked “find every call site of this function” does that work elsewhere and returns an answer, rather than filling the main session with file listings. Since context pressure directly degrades behaviour, that is a substantive gain rather than tidiness.

The cost is proportional and easy to underestimate: parallel agents mean parallel tool calls, and a permission policy that felt comfortable for one sequential agent is being exercised several times over, faster than approvals can be read.

Rollback, and what it does not cover

Agents make mistakes, and the question is what undoes them.

In the editor, a diff you have not accepted is trivially discarded, and git covers what you did accept.

In the CLI, /rewind reverts the last turn and its file changes — narrow, and exactly right for “that was not what I meant”.

In the cloud agent, work happens on a branch and arrives as a pull request. Closing it is the undo, which is one of the genuinely good properties of that design.

Outside your machine, nothing undoes it. A comment posted on someone’s issue, an external API called, a deployment triggered. This asymmetry is the practical argument for denying the tools that reach outward rather than relying on being able to back out.

What this cluster assumes

You can read a diff, run your project’s tests, and evaluate whether a change is right. Everything here depends on those three, because every safety property in agentic work eventually reduces to a human looking at an artefact.

It assumes you have used Copilot enough to have been disappointed by it — that calibration matters more here than anywhere, because an agent’s confident wrong answer is expressed as a commit rather than a paragraph.

It does not assume you have used agents, built one, or heard of MCP.

If you are earlier than that, Cluster 1 is the entry point and agent mode is where this becomes concrete. If you live in the terminal, Cluster 5 covers the same ideas with the sharpest available permission model.

The failure that matters most

Across every surface, one failure mode accounts for more wasted work than all the others together, and it is not the one people brace for.

It is not the agent producing broken code — broken code fails loudly and gets fixed. It is the agent producing working code that solves a different problem from the one you had.

This is the failure agents are structurally prone to. Asked something ambiguous, an agent does not stop; it resolves the ambiguity toward the most likely reading and proceeds with complete confidence. The result compiles, the tests pass, the summary is coherent, and the whole thing is answering a question you did not ask.

Two habits reduce it, and both appear repeatedly in the lessons that follow.

Say what done looks like before you start. Not what to do — how you will know it worked. A stated finish line is the one thing an agent cannot invent for you.

Read the premise before the implementation. The first paragraph of the agent’s summary, compared against your actual request, catches this in ten seconds. The diff does not, because at the line level a confident answer to the wrong question looks exactly like a right one.

Common misconceptions

Five beliefs that cause most of the wasted effort, stated plainly so the rest of the cluster can assume they are settled.

“Agent mode is a better chat.” It is a different activity. Chat answers; agent mode acts. Using it for questions produces changes you did not want and obscures the answer you did.

“A custom agent makes the model better at something.” It does not. The model is the same model. What an agent supplies is a boundary and your team’s specific knowledge, and the boundary is the more valuable half.

“More context is better.” Up to a point, and then not. Every enabled tool, every loaded skill and every server’s descriptions occupy space and make selection harder. Teams that add everything frequently conclude the tooling is unreliable when what they built was a large haystack.

“MCP makes Copilot smarter.” It makes it reach further. A model that misunderstands your architecture will misunderstand it identically with access to your monitoring — the difference is that now it can act on the misunderstanding.

“The autonomous surfaces are the advanced ones.” The cloud agent is the least interactive and the safest, because its output is a pull request. Autonomy and risk are not the same axis, and conflating them leads people to fear the safe surface and trust the sharp one.

Where to go next

Thirteen lessons, split by what they do for you:

Understanding the surfaces — delegating a task end to end, and the cloud agent for what it is and where it runs.

Building agents — custom agents, agent skills and building your first skill.

MCP — the complete guide, GitHub’s own server, and connecting servers.

Three agents you build — DevOps, code review and documentation.

The capstone — GitHub Agentic Workflows.

If you arrived from earlier clusters, the direct connections: agent mode and cloud agent versus agent mode from Cluster 1; Cluster 5’s custom agents, which covers the same mechanism as the CLI implements it; and Cluster 6’s custom instructions, which every agent here inherits.