Visual Studio Code introduces custom agents as a way to configure Artificial Intelligence personas that align with specific development roles and tasks, such as security review, planning, solution architecture, or code implementation. Each custom agent bundles its own instructions, tool set, and optional handoffs so developers can quickly switch between specialized configurations without manually adjusting tools or prompts. Custom agents are defined in .agent.md Markdown files, can live either in a workspace or in a user profile, and can be reused in background agents and cloud agents so autonomous tasks share the same tailored behavior.
Custom agents are particularly useful for separating capabilities and responsibilities across different phases of development. A planning agent can be restricted to read-only tools to avoid accidental edits and focus on research, context gathering, and detailed implementation plans, while an implementation agent can be given full editing tools to apply the plan in code. Instructions in the agent body define how the Artificial Intelligence should operate, for example emphasizing security-focused review or step-by-step planning. Handoffs extend this model by enabling guided, multi-step workflows: after a response, interactive buttons can move the user from a planning agent to an implementation agent, from implementation to review, or from writing failing tests to writing passing tests, with relevant context and a pre-filled prompt that can optionally auto-submit when send: true.
The .agent.md format uses YAML frontmatter to configure behavior, including description, name, argument-hint, tools, agents, model, user-invocable, disable-model-invocation, target, mcp-servers, and handoffs fields. The tools list can include built-in tools, tool sets, Model Context Protocol tools, or extension tools, and the agents field controls which subagents may be invoked. The infer property is deprecated in favor of user-invocable and disable-model-invocation, which together allow separate control over visibility in the agents dropdown and subagent invocation. Developers can also use Claude-style agents in a .claude/agents folder with plain .md files and Claude-specific frontmatter, and Visual Studio Code maps Claude tool names to corresponding tools. Custom agents can be created manually via Configure Custom Agents or generated using Artificial Intelligence with commands like /create-agent, extracted from existing conversations, organized in workspace, profile, or organization-level locations, and shared across teams with discovery controlled by settings such as github.copilot.chat.organizationCustomAgents.enabled. The agents dropdown can be customized to show or hide specific agents, tool list resolution follows a defined priority between prompt files and agents, and diagnostics views help inspect all loaded customizations and troubleshoot issues.
