GitHub Copilot agents¶
GitHub Copilot started life in 2021 as an inline autocomplete plugin. Five years later, the brand covers something much wider: a family of agent surfaces that plan multi-step work, run terminal commands, open pull requests on their own, build entire prototype apps from a prompt, and call out to third-party tools through the Model Context Protocol. By May 2026, "Copilot" is not a single product but a layered stack of agentic capabilities that share models, billing, and policy plumbing while differing in where they run, how synchronous they are, and how much autonomy the user grants them.
This page is a working reference to that stack as it stands today. It walks through each agent surface, what it does, how to trigger and configure it, what the moving parts are under the hood, and where each surface still falls short.
The map of agent surfaces in 2026¶
Four distinct agent surfaces ship under the Copilot brand, plus an extension mechanism that lets third parties plug new agents in. They share a control plane (Copilot policies, premium-request accounting, GitHub identity) but execute in very different environments.
| Surface | Where it runs | Synchrony | Triggers |
|---|---|---|---|
| Copilot agent mode | Locally, in VS Code / Visual Studio / JetBrains / Eclipse / Xcode | Synchronous, in-editor | Chat panel → Agent mode |
| Copilot cloud agent (a.k.a. coding agent) | GitHub Actions ephemeral sandbox | Asynchronous | Assign issue, Agents tab, "Delegate to coding agent" |
| GitHub Spark | Azure Container Apps managed runtime + Codespace | Asynchronous (per prompt) | github.com/spark, natural-language prompt |
| Copilot Extensions / third-party agents | Partner-hosted (Claude, Codex, others) | Sync (chat) or async (issue) | @extension-name in chat, or assign issue |
Copilot Workspace — the browser-based "issue to PR" technical preview launched in April 2024 — was officially sunset on May 30, 2025. Its sub-agent architecture, issue-to-PR loop, and asynchronous execution model were absorbed into what GitHub now ships as the Copilot cloud agent. References to "Copilot Workspace" in 2026 documentation point either to legacy material or to the cloud agent that succeeded it.
Copilot agent mode (the local, synchronous agent)¶
Agent mode is the autonomous peer-programmer that lives inside the editor. It was announced February 24, 2025 in VS Code Insiders, reached VS Code Stable later that spring, and is now generally available across VS Code, JetBrains IDEs (IntelliJ, PyCharm, WebStorm and the rest), Eclipse, Xcode, and Visual Studio 2026. By March 2026 it had reached general availability on both VS Code and JetBrains — the two largest IDE families.
How it differs from the older Copilot modes¶
The Copilot chat panel in VS Code exposes a mode picker. Ask is plain conversational Q\&A about your code. Edit (formerly Copilot Edits) takes a targeted, multi-file edit request and produces a diff to review. Agent is the autonomous mode: you describe a goal, and Copilot reads files, writes files, runs terminal commands, observes the output, and loops on its own until the task is done or it needs your help. The key behavioural shift is that Agent mode is not answering a question — it is executing a plan, with each tool call feeding the next decision.
Under the hood, the model is given a fixed tool surface: read_file, list_dir, run_terminal, apply_edit, search tools, and language-aware navigation tools. Each tool result feeds back into the model's next reasoning step. This is the same loop pattern used by Claude Code and Cursor's agent — the differentiator for Copilot is the tight coupling to GitHub identity, repos, and Actions.
Triggering and using it¶
In VS Code: open Copilot Chat with Ctrl+Shift+I (or Cmd+Shift+I), select Agent from the mode dropdown at the top of the chat panel, then describe what you want. A useful example prompt:
Add input validation to the signup form, write unit tests for
the validation logic, and fix any test failures.
The agent will inspect the workspace, find the signup component, edit the form code, create a test file, run the tests, react to failures, and present a clean diff at the end. Terminal commands are surfaced for approval before execution by default, with an auto-approve option for trusted commands. You don't need to tag files with @filename — the agent reads the workspace as part of its planning step.
Custom instructions and prompt files¶
Agent mode automatically reads .github/copilot-instructions.md at the repo root. This is the canonical place for repo-wide guidance: coding style, preferred libraries, naming conventions, architectural rules. A trimmed example:
# Copilot instructions
- Use TypeScript with strict mode. Prefer `unknown` over `any`.
- React components are functional. State via Zustand, never Redux.
- All HTTP calls go through src/lib/api.ts. Never call fetch directly.
- Tests live next to source as *.test.ts using Vitest, not Jest.
Beyond repo-level instructions, the Copilot customization framework now spans custom agents (named personas with their own tools and prompt), prompt files invoked as /command, and agent skills that auto-activate when the agent detects a matching task. The April 2026 Visual Studio update extended custom agents with user-level definitions stored in %USERPROFILE%/.github/agents/ so a developer's personal agents travel across projects, and broadened skill discovery to include .claude/skills/ and .agents/skills/ alongside the original .github/skills/ path.
A custom agent file is a Markdown file with YAML frontmatter, per the custom agents configuration reference. A minimal definition:
---
name: Reviewer
description: Reviews diffs for security and style issues, never edits code.
target: vscode
tools: [read_file, list_dir, grep_search]
---
You are a focused code reviewer. Read the diff, flag security and
style issues against the repo's copilot-instructions.md, and produce
a single Markdown report. Never call apply_edit.
The configuration filename minus the extension is used as the dedup key, so a repo-level Reviewer.agent.md overrides a user-level one with the same name.
Copilot cloud agent (the asynchronous, GitHub-hosted agent)¶
If agent mode is the local peer programmer, the cloud agent — historically called the "coding agent" — is the off-IDE teammate. It does not live in an editor. It lives on github.com, in the flow of issues, pull requests, and Actions. It became generally available to all paid Copilot subscribers in mid-2025 after being seeded out of the discontinued Copilot Workspace preview, as reported by GitHub and corroborated by the Java Code Geeks retrospective.
The assignment flow¶
There are three canonical ways to kick off a cloud agent session, per the official GitHub blog walkthrough:
- Assign a GitHub issue to Copilot from the issue sidebar, exactly the way a human teammate would be assigned.
- Use the Agents tab that appears on every github.com page — type a prompt, pick a repo, watch the session start.
- "Delegate to coding agent" from VS Code's Copilot Chat, which hands off an in-progress chat to the cloud and frees up the local editor.
The April 2026 Visual Studio update extended this further: a new Cloud entry in the agent picker lets a developer start a cloud session directly from Visual Studio, which creates the corresponding GitHub issue and pull request on remote infrastructure while they keep working locally.
For Copilot Business and Enterprise customers an organization admin must first enable the agent under Copilot policies, and there is a per-user toggle on individual accounts as well.
What happens after assignment¶
When the agent picks up a task, it spins up an ephemeral GitHub Actions runner dedicated to that session, clones the repo, runs any configured setup steps, then begins making code changes. Commits land on a feature branch and the agent immediately opens a draft pull request that you can watch in real time. The session log is exposed through the same UI you use to track Actions workflows, so reviewers can see every file the agent read, every command it ran, and every iteration it went through.
When the agent is done — or when it gets stuck — it requests a review. You leave a normal pull-request comment, the agent reads it, adjusts the code, pushes more commits, and asks again. The session is fully asynchronous: you can delegate, walk away, do other work, and come back when the PR is ready.
GitHub's own assessment, validated through private preview, is that the cloud agent is best at low-to-medium complexity tasks in well-tested codebases: adding features against a clear spec, fixing well-described bugs, extending test coverage, applying a refactor pattern, and improving documentation. It does poorly when asked to make architectural decisions or work in messy untested code.
The runtime sandbox¶
The execution environment is a normal GitHub Actions runner, by default Ubuntu Linux x64. The official customization docs describe how a repository can shape it. You can pre-install dependencies, upgrade to a larger runner, swap to self-hosted runners, switch to a Windows runner, or enable Git LFS by adding a special workflow at .github/workflows/copilot-setup-steps.yml. The job must be named copilot-setup-steps, and only steps, permissions, runs-on, services, snapshot, and timeout-minutes (max 59) are honoured — anything else is ignored.
A realistic setup file for a Node project:
name: "Copilot Setup Steps"
on:
workflow_dispatch:
push:
paths: [.github/workflows/copilot-setup-steps.yml]
pull_request:
paths: [.github/workflows/copilot-setup-steps.yml]
jobs:
copilot-setup-steps:
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- name: Checkout code
uses: actions/checkout@v6
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: "20"
cache: "npm"
- name: Install dependencies
run: npm ci
- name: Warm the build cache
run: npm run build -- --noEmit
The job's exit status gates the agent: if a setup step returns non-zero the remaining steps are skipped and the agent starts with whatever state has been reached. This is also why GitHub recommends running the workflow manually first — it shows up in the Actions tab and can be debugged without burning agent sessions.
The firewall¶
By default the agent's sandbox has a built-in egress firewall that blocks network access outside an allowlist. This protects against prompt-injection-driven exfiltration: if an attacker convinces the agent to send your code to evil.example, the firewall refuses the connection. The firewall can be customized (add allowed domains) or disabled entirely, but disabling it is required if you switch to self-hosted runners, where GitHub cannot enforce egress controls.
For self-hosted or Azure-private-networked runners, the agent still needs outbound access to a small set of GitHub hosts to fetch instructions and submit completions: uploads.github.com, user-images.githubusercontent.com, and one of api.individual.githubcopilot.com, api.business.githubcopilot.com, or api.enterprise.githubcopilot.com depending on the plan of the user who triggered the session.
Secrets, variables, and proxies¶
The agent runs with a dedicated, scoped GitHub token — not the user's PAT. Repository secrets and variables can be exposed to the agent through the Agents environment in repository settings, separate from normal Actions secrets so a leaked agent token cannot drain CI/CD credentials. For locked-down networks the agent honours https_proxy, http_proxy, no_proxy, ssl_cert_file, and node_extra_ca_certs environment variables, configured either as Agents variables or baked into a custom runner image.
GitHub Spark¶
Spark is the third leg of the Copilot agent stack: a natural-language app builder. Unlike agent mode (which edits files you already have) and the cloud agent (which works against an existing repo), Spark generates an entire fullstack web app from a sentence and deploys it.
Spark entered public preview for Copilot Pro+ subscribers on July 23, 2025 and has since been opened to other paid Copilot plans through staged rollout. The launch model was Claude Sonnet 4, with model selection broadening since.
What it does¶
From the official concept docs, a single prompt produces a runnable app with frontend code, backend logic, a managed key-value data store (backed by Azure Cosmos DB, capped at 512 KB per record), GitHub-based authentication, and a one-click deployment to a fully managed runtime hosted on Azure Container Apps. From the user's perspective there is no infra to configure, no LLM API key to manage — if the app uses an LLM, Spark routes inference through GitHub Models.
Generated apps are GitHub-native. With one click Spark creates a backing repository with two-way sync: changes made through Spark prompts appear as commits on the main branch, and edits made directly in the repo flow back into the Spark editor. Once a repo exists, the project participates in normal GitHub workflows — pull requests, issues, Actions, Dependabot. A developer who has outgrown the prompt-only UI can open the same project in a Codespace and continue with agent mode or assign issues to the cloud agent.
Production posture¶
Spark remains in public preview but has acquired the trappings of a real product. The December 2025 update covered by Visual Studio Magazine added DPA coverage (effective October 27, 2025), a dedicated billing SKU so org admins can see Spark spend separately, granular premium-request budgets, and improvements to how the agent handles user edits and apps that exceed the underlying model's context window. Enterprises can now force all Spark-generated repos into the org account rather than personal accounts.
Usage is metered through Copilot's premium request system rather than a separate API charge. A single Spark prompt typically consumes multiple premium requests, which is why Spark first launched on Pro+ (1500 premium requests / month) rather than Pro (300).
Copilot Extensions and third-party agents¶
Copilot Extensions are the plug-in mechanism. Launched at Microsoft Build 2024, they let partners ship Copilot Chat skills that bring outside knowledge or services into the chat surface: DataStax, Docker, MongoDB, Sentry, Stripe, Pinecone, LaunchDarkly, Octopus Deploy, Atlassian, Azure, and Microsoft Teams were among the launch partners, and the marketplace has grown into the hundreds. Organizations can also build private Extensions for internal tooling — a homegrown deploy system or monitoring product can become a @deploy skill in chat without leaving the IDE.
In 2025 GitHub generalized this further with third-party agents: not just chat skills, but full autonomous agents that compete with Copilot's own cloud agent for the same issue-to-PR workflow. Per the official third-party agents docs, as of May 2026 the supported third-party agents are Anthropic Claude and OpenAI Codex. You can assign an issue to either one the same way you assign one to Copilot's own agent, or @-mention them in PR comments to iterate. Available models depend on the agent: Codex exposes GPT-5.2-Codex through GPT-5.4 plus the nano variant; Claude exposes Opus 4.5 through 4.7 and Sonnet 4.5 / 4.6. An Auto option lets Copilot pick the best model per task.
Under the hood, enabling a partner agent installs a backing GitHub App (anthropic code agent or openai code agent) whose actions appear in the audit log but which is intentionally hidden from the normal App installation list so a user cannot accidentally uninstall it. Each session counts as one premium request plus the Actions minutes consumed by the underlying sandbox.
MCP support across the stack¶
The Model Context Protocol is now a first-class citizen across both the local and the cloud agent. The same mcp.json schema configures both — the difference is where it lives.
In VS Code, MCP servers are configured at the user level in mcp.json or at the workspace level in .vscode/mcp.json. The VS Code MCP docs describe the format. A minimal config that wires up a Playwright browser server and a local Postgres server:
{
"servers": {
"playwright": {
"command": "npx",
"args": ["-y", "@playwright/mcp@latest"]
},
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgres://localhost:5432/myapp"
]
}
},
"inputs": []
}
Agent mode discovers the tools each server exposes and surfaces them to the model the same way as its built-in tools. The chat UI lists active servers and lets the user toggle individual tools on or off per session.
The cloud agent uses the same JSON shape but stored in the repo or org configuration so that every cloud session running against the repo gets the same set of servers. Per the custom agents configuration reference, the cloud agent's MCP setup has evolved from the initial implementation: a custom agent definition can scope which MCP tools it is allowed to call via the tools frontmatter field, so a Reviewer agent can be denied write tools even if those tools are configured at the org level.
GitHub's own gh aw CLI extension (described in the Agentic Workflows developer guide) is a sibling concept: it lets a team define Markdown-authored workflows that run as AI agents inside GitHub Actions on a schedule or event, with safe-output buffering and a network firewall, and supports Copilot, Claude, or Codex as the underlying engine. This is the most automated end of the spectrum — unattended repository operations defined in natural language.
Visual Studio's flavour of Copilot agents¶
Visual Studio 2026 carries the same agent mode and cloud agent as VS Code, but with a few platform-specific moves visible in the April 2026 changelog. The headline is cloud agent integration: a Cloud option in the agent picker spins up a cloud session from inside the IDE, creates a GitHub (or Azure DevOps) issue, and tracks the resulting PR. There is a new Debugger agent that takes a bug report and validates fixes against live runtime behaviour — the agent reproduces the bug, instruments the process, diagnoses, and proposes a targeted fix using live execution rather than static analysis. C++ ships with first-class language-aware navigation tools (get_symbol_call_hierarchy, get_symbol_class_hierarchy) for agent mode, which compensates for the weaker tree-sitter coverage that VS Code agent mode falls back to for native code. Customizable keyboard shortcuts for inline acceptance and a dedicated chat history panel round out the IDE-specific niceties.
Plan availability¶
The official Plans for GitHub Copilot page is the source of truth, and it has been busy in 2026. Two announcements at the top of the page set context: as of June 1, 2026 Copilot is moving from request-based to usage-based billing, and as of April 20, 2026 GitHub has temporarily paused new sign-ups for Pro, Pro+, and Student plans (with Business self-serve sign-ups for GitHub Free/Team customers paused two days later). Both reflect capacity pressure from agent workloads.
| Plan | Price (USD) | Premium requests / mo | Cloud agent | Agent mode | MCP | Third-party agents |
|---|---|---|---|---|---|---|
| Free | $0 | 50 | No | Yes | Yes | No |
| Student | Free (verified) | 300 | Yes | Yes | Yes | Yes |
| Pro | $10 / mo | 300 | Yes | Yes | Yes | Yes |
| Pro+ | $39 / mo | 1500 | Yes | Yes | Yes | Yes |
| Business | $19 / seat / mo | 300 | Yes (org policy) | Yes | Yes | Yes |
| Enterprise | $39 / seat / mo | 1000 | Yes (org policy) | Yes | Yes | Yes |
Additional premium requests cost $0.04 each. Spark is currently included in plans Pro+ and above, with rollout in progress for lower tiers. Copilot is not available on GitHub Enterprise Server — it requires Enterprise Cloud or higher. Pro and Pro+ are free for verified students, teachers via GitHub Education, and maintainers of popular open-source projects via the Global Maintainers Program.
The most important feature-gating observation: agent mode, MCP, and the cloud agent are available on every paid plan, including the cheapest. The differentiators that move users up the stack are premium-request allowance, available models in the picker, and admin controls (audit logs, IP indemnity, custom knowledge bases, SSO), not agent capability.
How the surfaces relate to each other¶
A mental model that helps when navigating the docs: agent mode and cloud agent are the same agent in two execution modes. Agent mode runs the loop in your editor against the files you have open; the cloud agent runs the same loop in a Codespace-like sandbox against a freshly cloned repo. They read the same copilot-instructions.md, support the same MCP servers, accept the same custom agent definitions, and produce the same kind of work product (a diff). The difference is whether the developer is in the loop in real time or asynchronously reviewing a PR.
Spark sits one layer up: it is a Copilot-driven meta-agent that generates an entire app and then drops the developer back into the regular agent surfaces for further iteration. Third-party agents (Claude, Codex) and Copilot Extensions sit one layer down: they extend the agent surfaces with extra models, tools, and skills.
Copilot Workspace, finally, is the ghost in the machine. It was the prototype that proved the issue-to-PR pattern, was sunset, and has now been rebuilt into the cloud agent. Anything published before mid-2025 that refers to "Workspace" should be reread with the cloud agent in mind.
Known limitations and risks¶
The quality of agent output is highly correlated with codebase hygiene. The cloud agent is good at clearly-specified tasks in well-tested codebases and visibly worse in messy or under-tested code. This is the consistent finding across GitHub's own assessment, the Java Code Geeks retrospective, and the PinkLime hands-on review.
The sandbox firewall and the agent token mitigate but do not eliminate prompt-injection risk. Any tool the agent can call — especially MCP servers that talk to issue trackers, ticketing, or production data — widens the blast radius if a malicious comment or file convinces the agent to behave badly.
The copilot-setup-steps.yml job has a 59-minute timeout cap and is non-customisable beyond a small whitelist of fields. Long compile or test setups that exceed that ceiling cannot be expressed there and must be baked into a custom runner image instead.
MacOS is not supported as an agent runner. Apple-platform repos that need to build and run their tests during a session must self-host on macOS via a different channel or accept that the cloud agent can only edit code without running it.
Finally, the usage-based billing transition on June 1, 2026 and the temporary pause on new sign-ups suggest GitHub is tuning the economics. Teams modelling Copilot agent spend should treat the current premium-request allowances as a snapshot, not a contract — the underlying meter will look different by Q4 2026.
Practical reading order for the docs¶
For someone setting up Copilot agents on a real repo today, the most useful pages in order are: (1) the Plans page to pick a tier; (2) the agent mode VS Code blog post to get the local loop working; (3) the cloud agent customization docs to wire up copilot-setup-steps.yml; (4) the VS Code MCP docs to add MCP servers; (5) the custom agents configuration reference once you start composing your own agents and skills.
Changelog¶
- 2026-05-11 — Page created from vendor docs and primary articles (Type B, confidence 86)