Inline Sub-Agents

Define specialised agents directly in a workflow markdown file. At runtime, sub-agent sections are extracted (after {{#runtime-import}} macros resolve) and written to the engine-specific agents directory for the engine CLI to discover.

---

Syntax

Define a sub-agent with a level-2 Markdown heading of the form ## agent: \name``:

## agent: `file-summarizer`
---
description: Summarizes the content of a file in a few concise sentences
model: small
---
You are a file summarization assistant. When given a file path, read the
file and return a brief summary (2–4 sentences) describing its purpose
and key contents. Be concise and factual.

Name rules

• Must be enclosed in backticks: `name`
• Lowercase only: [a-z][a-z0-9_-]*
• Examples: `planner`, `file-summarizer`, `code-reviewer`

Block boundary

The block ends at the next ## heading (any level-2 heading) or at EOF — no explicit end marker is needed. Place sub-agent blocks at the bottom of the file, after all main workflow content.

Frontmatter fields

Only two fields are supported inside a sub-agent frontmatter block:

Field	Required	Default	Notes
description	No	—	Human-readable summary of the sub-agent's role
model	No	"inherited"	Model override; "inherited" uses the parent workflow's model. Prefer model aliases (e.g. small, large) over specific model IDs for portability.

Prefer model aliases over model IDs. Built-in aliases resolve to the best available model for each provider, so they continue to work as models are updated. Commonly used aliases for sub-agents:

Alias	Resolves to	When to use
small	mini → haiku, gpt-5-mini, gpt-5-nano, gemini-flash	Cheap, fast tasks: extraction, classification, formatting
large	sonnet, gpt-5-pro, gpt-5, gemini-pro	Complex reasoning or synthesis tasks
inherited	Parent workflow model	Default — use when the sub-agent needs the same capability as the parent

All other fields (engine, tools, network, etc.) are stripped at runtime with a warning. Sub-agents inherit the parent's engine, tool access, and network configuration.

---

Engine-Specific Placement

Sub-agent files are written to the directory and with the extension each engine natively expects:

Engine	Directory	Extension
Copilot (default)	.agents/agents/	.agent.md
Claude	.claude/agents/	.md
Codex	.codex/agents/	.md
Gemini	.gemini/agents/	.md

The engine is detected at compile time from the engine: field and injected as GH_AW_ENGINE_ID into the interpolation step's environment.

---

MCP Access in Sub-Agents

Sub-agents do not have their own MCP servers — they run within the parent's agent environment without independent tool config. To give them file system and shell access, enable on the parent workflow:

• cli-proxy: true — GitHub CLI proxy for authenticated gh calls. Recommended for any sub-agent that reads/writes repo content.
• tools.github.mode: gh-proxy — routes GitHub API calls through the gh proxy sidecar; required for private repos or the GitHub MCP toolset.

---
engine: copilot
tools:
  github:
    mode: gh-proxy
  cli-proxy: true
---

---

When to Use Sub-Agents

Two main scenarios:

1 — Parallel specialised tasks with smaller models

Break a large workflow into parallel units handled by small/cheap models, then let the parent (large) model reason over the aggregated results:

# Investigate: Repository Health

## Step 1 — gather data

Use the `dependency-scanner` agent to list all outdated packages.
Use the `test-coverage` agent to summarise uncovered code paths.
Use the `secret-scanner` agent to check for leaked credentials.

## Step 2 — synthesise

Combine the three reports above into a prioritised action plan.
The top item must have a linked PR draft or issue.

## agent: `dependency-scanner`
---
description: Lists outdated npm/pip/go packages
model: small
---
Run the appropriate package-manager audit command and return a
machine-readable list of outdated packages with their current and
latest versions.

## agent: `test-coverage`
---
description: Summarises low-coverage code paths
model: small
---
Read the most recent test coverage report and list the top 5 files or
functions with coverage below 60 %. Include the file path and line range.

## agent: `secret-scanner`
---
description: Checks for potential credential leaks
model: small
---
Scan staged changes and recently modified files for patterns that
resemble API keys, tokens, or passwords. Report any findings with the
file name and approximate line number.

The parent model orchestrates; sub-agents do the heavy lifting with small at lower cost.

2 — Reusable specialised helpers

Extract repetitive sub-tasks (file summarisation, commit-message generation, code explanation) into a named sub-agent the main prompt calls by name.

---

Planner-Worker Pattern

Split work to control cost and keep context quality high:

• Main/frontier agent (planner-orchestrator): forms hypotheses, decides what evidence is needed, picks workers, synthesises conclusions
• Worker sub-agents (usually model: small): bounded retrieval, extraction, classification, verification, one-shot summarisation

Prompt workers narrowly and evidence-first (e.g. "return exact error messages and line references"), not broad analysis.

Worker outputs should be compact and structured. Do not return raw logs or large file dumps to the orchestrator.

Bounded delegation rules

• keep delegation one level deep unless gh-aw explicitly supports and validates deeper topology
• avoid recursive or open-ended sub-agent fan-out
• cap per-run worker fan-out so high-volume events cannot trigger runaway cost
• stop early with noop or safe output when a cheap worker can confidently classify a known/duplicate/stale/low-value case

See also: token-optimization.md and workflow-patterns.md.

---

Full Example

---
engine: copilot
tools:
  github:
    mode: gh-proxy
  cli-proxy: true
  bash:
    - "cat *"
    - "ls *"
---

# PR Review Assistant

1. Use the `diff-explainer` agent to produce a plain-English summary of the
   diff for PR #${{ github.event.pull_request.number }}.
2. Post the summary as a PR comment.

## agent: `diff-explainer`
---
description: Produces a plain-English summary of a pull request diff
model: small
---
You receive a unified diff. Describe each changed file in one sentence,
focusing on *what changed* and *why it matters*. Ignore formatting-only
changes. Return a bulleted list, one bullet per file.

---

Limitations

• Sub-agents do not support engine:, tools:, network:, or mcp-servers: fields — those are stripped at runtime.
• Sub-agents cannot define their own safe-output jobs.
• Sub-agent blocks must appear in the main workflow file body; they are not resolved inside imported shared files.