Subagents

Subagents are specialized agents that handle delegated tasks with their own context, tools, and system prompts.

Using with AgentSession

import { createAgentSession } from '@philschmid/agent';

const session = createAgentSession({
  model: 'gemini-3-flash-preview',
  tools: ['read', 'bash', 'subagent'],  // Enable subagent tool
});

session.send('Delegate the documentation task to the docs-writer subagent');

Discovery Sources

Subagents are loaded from multiple sources with a defined precedence. When two subagents share the same name, the first match wins:

1. Project (.agent/subagents/) — highest priority
2. Global (~/.agent/subagents/) — shared across projects
3. Built-in (shipped with @philschmid/agent) — lowest priority

# Override project artifacts path (default: .agent)
export AGENT_ARTIFACTS_PATH=".agent"

# Override global artifacts path (default: ~/.agent)
export AGENT_GLOBAL_ARTIFACTS_PATH="/custom/global/path"

Directory Structure

.agent/
└── subagents/
    ├── code-reviewer.md
    ├── api-designer.md
    └── test-writer.md

Subagent Format

---
name: code-reviewer
description: Reviews code for quality, security, and best practices
tools:
  - read
  - grep
skills:
  - code-standards
model: gemini-2.5-pro
---

You are an expert code reviewer with deep experience in:
- Security vulnerability detection
- Performance optimization
- Code style and maintainability

## Review Process
1. Read the file under review
2. Search for related code with grep
3. Identify issues and improvements

Required Fields

Field	Type	Description
name	string	Unique identifier
description	string	Brief summary of the subagent’s purpose

Optional Fields

Field	Type	Description
tools	string[]	List of tool names the subagent can use
skills	string[]	Skills to inject into the subagent’s system instruction
model	string	Override the default model

Skill Injection

When a subagent declares skills in its frontmatter, those skills are automatically loaded and their content is injected into the subagent’s system instruction. This gives the subagent specialized knowledge without duplicating instructions.

---
name: docs-writer
description: Writes documentation
skills:
  - docs-style-guide
  - api-conventions
---

The subagent will receive the full content of both docs-style-guide and api-conventions skills as part of its system prompt.

Loading Subagents

import { loadSubagents, type ArtifactLayer } from '@philschmid/agent';

// Load from all default sources (project + global + built-in)
const subagents = loadSubagents();

// Load from specific layers
const subagents = loadSubagents([
  { path: '.agent', source: 'project' },
]);

Subagent Type

type Subagent = {
  name: string;         // From frontmatter
  description: string;  // From frontmatter
  tools?: string[];     // Tool names to enable
  skills?: string[];    // Skill names to inject
  model?: string;       // Model override
  content: string;      // System instruction (body)
  source: 'project' | 'global' | 'builtin';
};

Disabling Subagents

Disable specific subagents by name:

# Via environment variable (comma-separated)
export AGENT_DISABLED_SUBAGENTS="general-purpose,other-agent"

Or in settings.json:

{
  "disabledSubagents": ["general-purpose"]
}

Skills vs Subagents

Aspect	Skills	Subagents
Purpose	Teach the current agent procedures	Separate worker with own context
Context	Shares parent context	Isolated context window
Tools	Uses parent’s tools	Can have restricted tool access
Model	Same as parent	Can use different model
Format	Directory with SKILL.md	Single .md file

Use skills when you want to add knowledge to the current agent. Use subagents when you need isolation or specialized capabilities.

Best Practices

1. Limit tool access: Give subagents only the tools they need
2. Clear system prompts: Write specific, focused instructions
3. Use skills for shared knowledge: Reference skills instead of duplicating
4. Choose appropriate models: Use faster models for simple tasks
5. Define output formats: Specify how results should be structured
6. Override built-ins: Create a project subagent with the same name to customize

---

Next Steps

• Skills: Reusable instruction packages
• Session: Multi-turn conversations with subagents
• Hooks: Intercept subagent delegations