GitHub Copilot Guide: Custom Agents and Subagent Orchestration

InYourLeague Research · 2026-09-05

Answer in brief

GitHub Copilot supports custom agents and subagent orchestration through the Copilot SDK and GitHub Copilot CLI, enabling developers to define specialized agents with scoped tools, dedicated system prompts, and isolated execution contexts. The runtime automatically delegates tasks to temporary subagents based on intent inference or explicit selection, streaming lifecycle events back to the parent session while preserving main context cleanliness. No product-specific selectable model ID has been verified for this entry.

Key facts at a glance

Failure modes and verification

FAQ

What is the primary architectural purpose of using subagents in GitHub Copilot?

Subagents run tasks inside a dedicated, temporary context window. This architecture allows specialized prompts and tool outputs to execute without cluttering the parent session’s context window, preserving space for high-level coordination as documented in the Copilot SDK Custom Agents Guide.

Does subagent context isolation provide a filesystem security sandbox?

No. Subagent context isolation and scoped tool allowlists restrict conversation context and tool availability, but they do not establish a filesystem security sandbox boundary. Developers must rely on explicit permission callbacks and underlying runtime isolation mechanisms rather than assuming context boundaries prevent filesystem changes.

Which custom agent takes precedence if defined in both CLI repository and user directories?

When a custom agent with the same name exists in both the user home directory (~/.copilot/agents/) and the project repository directory (.github/agents/), GitHub Copilot CLI prioritizes the agent definition from the user home directory, as explained in the Copilot CLI Custom Agents Guide.

Do subagents automatically inherit skills defined at the parent session level in Copilot SDK?

No, subagents do not inherit skills from the parent session. Skills are opt-in per agent. To make a skill available to a custom agent, its name must be explicitly declared in the agent’s skills configuration array, which eagerly injects instructions at startup from the session’s skillDirectories.

Which specific AI model IDs are officially verified as selectable defaults for this entry?

No product-specific selectable model ID has been verified for this entry. Identifiers such as gpt-5.4 appearing in Copilot SDK code examples illustrate configuration parameters rather than verified fixed defaults or an exhaustive list of supported models.

Sources and freshness

• Official source
• Official source
• Last verified: 2026-09-05

Extended guide

Architectural Overview of GitHub Copilot Custom Agents

GitHub Copilot allows developers to structure complex AI tasks by defining custom agents that the Copilot runtime orchestrates as subagents within a single session. Custom agents are lightweight configurations attached to an active session in the Copilot SDK or loaded as agent profiles in GitHub Copilot CLI. When a user issues a request, the runtime evaluates the task requirements against agent descriptions, automatically spinning up an isolated subagent context with its own system prompt, tool restrictions, and optional MCP servers. This isolated execution window prevents specialized operations from cluttering the parent session’s context window, allowing the main agent to focus on higher-level planning and workflow coordination.

Note that a restricted tool allowlist, workspace path, or context isolation does not prove a filesystem sandbox or security boundary. The official documentation establishes context and tool access restrictions, but those operational behaviors do not establish a separate filesystem security sandbox boundary. Furthermore, no product-specific selectable model ID has been verified for this entry; model identifiers shown in SDK session examples (such as an example setting of gpt-5.4) illustrate configuration options rather than fixed product defaults or an exhaustive list of supported models.

Custom Agent Configuration Reference

In the Copilot SDK, custom agents are passed via the customAgents property during session initialization, or pre-selected using the agent property. In GitHub Copilot CLI, custom agents are stored as Markdown files ending in .agent.md either at the repository level (.github/agents/) or the user home directory (~/.copilot/agents/). If identical names exist in both locations, the user directory configuration takes precedence.

Numbered Implementation Workflow

1. Define the Agent Profile: In the Copilot SDK, declare an object in the customAgents array containing name, description, prompt, and explicit tools (e.g., ["grep", "glob", "view"]). In the CLI, run /agent, choose project or user scope, and supply instructions manually or through Copilot prompts to generate <name>.agent.md.
2. Configure Context and Tool Scope: Restrict access to destructive tools when defining read-only agents, attach MCP servers if external data integrations are required, and declare skills resolved from session-level skillDirectories.
3. Set Session Pre-selection or Inference: Optionally configure agent: "<name>" in SDK session configuration (equivalent to session.rpc.agent.select()) to activate the agent immediately, or leave infer: true for automatic intent routing.
4. Execute Subagent Delegation: Dispatch prompts through the parent session. The runtime performs intent matching, selects the matching agent, executes isolated subagent logic, streams events (subagent.started, subagent.completed), and integrates outputs back into the parent response.
5. Perform Handoff Review: Inspect generated code, issues, or plan proposals. In the CLI interactive creation flow, choose Review content to review and alter generated agent files before finalizing execution.

Deployment Checklist

• Agent name uses lowercase letters and hyphens for consistency across CLI and SDK invocations.
• Agent description explicitly specifies capabilities, trigger words (e.g., seccheck), and target use cases to assist runtime inference.
• Tool access is restricted using explicit tool arrays rather than leaving default unconstrained access.
• Skills are explicitly listed under skills if required, recognizing that subagents do not inherit skills from parent sessions.
• Precedence rules between ~/.copilot/agents/ and .github/agents/ are verified so user configurations do not unintentionally override repository agents.
• Lifecycle events streaming to the parent session are captured to monitor subagent progress and review handoff results.

For official details, refer to the Copilot SDK Custom Agents Guide and the Copilot CLI Custom Agents Guide.