Agents

Specialized AI workers with focused roles and tool access

Concept

What is an Agent?

A markdown file defining a specialized AI persona -- what model, which tools, what role.

Personas, Not Prompts

While skills tell the AI what to do, agents define who does it. Think of agents as team members with different expertise. A code reviewer agent uses Opus for deep reasoning. A file lookup agent uses Haiku for speed. Each agent has exactly the tools it needs — nothing more.

The Key Difference: Isolation

A skill runs inline in your main conversation — same AI, same context window, same tools. An agent runs in a separate context — fresh context window, its own system prompt, possibly a different model. The agent does its work independently and returns a summary. This is why agents are used for heavy tasks that would bloat your main conversation.

Comparison

Agent vs Skill

Complementary concepts -- skills define tasks, agents define workers.

Aspect	Skill	Agent
Metaphor	A recipe card	A team member
Defines	What to do (instructions)	Who does it (persona)
Invoked by	User types `/command`	Skills spawn via `Agent` tool
Runs in	Main conversation (inline)	Isolated subprocess (own context)
Context window	Shares yours	Gets its own (fresh)
Model	Uses current model	Can pick a different model
Tool access	Inherits session tools	Explicit allowlist
Lifecycle	One-shot execution	Multi-turn capable

The Orchestration Pattern

In practice, skills orchestrate and agents execute. When you type /dx-plan, the skill loads into the main conversation. The skill may then spawn a dx-code-reviewer agent (Opus, read-only tools, fresh context) to do heavy analysis. The agent returns a summary, and the skill continues with the result. Users interact with skills; agents work behind the scenes.

Decision

When to Use Which?

A quick guide for plugin authors.

Create a Skill when...

The user invokes it directly (/command)
It’s a reusable workflow or process
It teaches conventions or domain knowledge
Results should stay in the main conversation
It bundles scripts or templates

Create an Agent when...

You need a different model (Haiku for speed, Opus for depth)
You need to restrict tools (read-only, no file edits)
Heavy output would bloat the main context
Other skills should delegate work to it
You want parallel execution (multiple agents at once)

Examples

Real Examples from KAI

13 agents, each matched to the right model tier.

dx-code-reviewer

Deep code review with 80%+ confidence filtering. Runs in an isolated worktree so it cannot accidentally modify your working tree.

Opus

dx-pr-reviewer

Reviews PR diffs with project conventions. Posts structured findings with severity levels and inline code patches.

Sonnet

dx-doc-searcher

Fast project knowledge lookup. user-invocable: false — it is a worker agent only, called by other skills when they need documentation context.

Haiku

Config

Key Frontmatter

Agent definition fields.

Field	Purpose	Values
`name`	Agent identifier	`dx-code-reviewer`
`model`	AI model tier	`opus / sonnet / haiku`
`tools`	Available tool list	`[read, edit, grep, bash, …]`
`memory`	Persistent memory access	`true / false`
`permissionMode`	Auto-approve tool calls	`acceptEdits / bypassPermissions`
`isolation`	Run in worktree	`worktree`
`maxTurns`	Conversation turn limit	`10, 20, 50`
`user-invocable`	Can user call directly?	`true / false`
`agents`	Subagent allowlist (Copilot/VS Code)	`[‘AgentA’, ‘AgentB’] / ’*’`

1.113+

Nested Subagents

VS Code 1.113 allows agents to spawn other agents -- enabling multi-level orchestration.

How It Works

Agents declare tools: [‘agent’] and an agents: field listing which subagents they can invoke. The parent dispatches work programmatically — the LLM decides when to spawn a subagent based on the task.

Coordinator agent frontmatter

tools:
- read
- codebase
- agent           # required for nesting
agents: ['DxCodeReview', 'DxCommit', 'DxDebug']

User Setting Required

Nested subagents are off by default. Users must enable:

VS Code settings.json

"chat.subagents.allowInvocationsFromSubagents": true

This prevents infinite recursion while allowing deep orchestration when intended. Our coordinator agents (DxAgentAll, DxBugAll, DxStepAll) now include agents: fields to leverage this when enabled.

agents: vs handoffs:

agents: enables programmatic dispatch — the LLM autonomously decides when to call subagents. handoffs: creates UI buttons — the user clicks to transition. Both can coexist in the same agent. Our coordinator templates use both: agents: for autonomous orchestration, handoffs: for manual navigation.

Model Fallback Arrays (VS Code 1.113+)

The model: field now accepts an array for prioritized fallback: model: [‘claude-opus-4-5’, ‘claude-sonnet-4-5’]. Tries the first available model, then falls back. Only relevant for Copilot/VS Code Chat (multi-provider). Claude Code continues to use tier aliases (opus, sonnet, haiku).

Copilot

Copilot Agents

Different format, same concept.

Claude Code Agents

Live in plugin agents/ directory. YAML frontmatter with model, tools, isolation.

13 agents total

Copilot CLI Agents

Live in .github/agents/. Use allowed-tools and handoffs for navigation. Invoked with @AgentName.

25 agents total

Agent Type Naming

Always use the full prefixed name: dx-core:dx-code-reviewer, NOT just dx-code-reviewer. The short name fails with “Agent type not found”.

Docs

Official Documentation

Claude Code Agents

docs.anthropic.com/en/docs/claude-code/sub-agents

Copilot Agents

docs.github.com/…/custom-agents