Inline Sub-Agents

An inline Copilot sub-agent is a named agent definition embedded directly in a workflow markdown file. Instead of creating a separate file in .github/agents/, you define the agent’s frontmatter and instructions in a dedicated section of the same workflow file.

Syntax

Start a sub-agent block with a level-2 heading in the following form:

## agent: `name`

When a matching ## end agent: \name`marker is present, the block continues until that marker even if the block contains other##headings. Without an explicit end marker, the block continues until the next##` heading or end of file.

Explicit end marker

Add a closing heading to bound the block explicitly instead of relying on the next ## heading or EOF:

## agent: `name`
...
## end agent: `name`

## agent: `file-summarizer`
---
description: Summarizes files
---
You are a file summarization assistant.
## end agent: `file-summarizer`

Use the explicit end marker when:

• The sub-agent block is embedded in the middle of a document — for example, brought in via an import — so content that follows it is not accidentally swallowed into the block.
• The sub-agent’s own instructions need to contain ## headings (structured guidance, section breaks, etc.) without those headings being mistaken for the block’s boundary.

Without an explicit end marker, the block still ends at the next ## heading or EOF, matching the original behavior.

When a sub-agent block is brought in via {{#runtime-import ...}} and has no explicit end marker of its own, the runtime import resolver automatically inserts one at the point the implicit boundary would otherwise fall, so the imported block can never expand to swallow content spliced in after it (a subsequent import, or the rest of the workflow body). Authoring an explicit end marker is still recommended for clarity, but this makes every runtime import import-safe by default.

Name constraints

• Must start with a lowercase letter (a–z)
• May contain only a–z, 0–9, _, and -
• Examples: file-summarizer, code_reviewer, pr-analyst

Structure

Each sub-agent block contains:

1. YAML frontmatter (optional) — wrapped in --- delimiters
2. Instructions — natural language prompt for the agent

## agent: `file-summarizer`
---
model: claude-haiku-4.5
description: Summarizes the content of a file in a few concise sentences
---
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.

Frontmatter fields

Field	Required	Description
model	No	AI model to use (e.g. claude-haiku-4.5). Defaults to the parent workflow’s model.
description	No	Short description of the sub-agent’s purpose.

Runtime behavior

At runtime, each inline sub-agent block is extracted to a location that the AI engine can access natively. The destination path depends on the engine:

Engine	Destination path
copilot	.github/agents/<name>.agent.md
claude	.claude/agents/<name>.md
codex	.codex/agents/<name>.md
gemini	.gemini/agents/<name>.md

To use a sub-agent, instruct the parent workflow’s prompt to invoke it by name:

## Test Requirements

15. **Sub-Agent Testing**: Use the `file-summarizer` sub-agent to summarize the
    file `.github/workflows/smoke-copilot.md`. Verify the sub-agent returns a
    brief summary (2–4 sentences). Mark this test as ✗ if the sub-agent is
    unavailable or returns an error.

Example: File Summarization Sub-Agent

The following excerpt shows a full workflow that defines and uses an inline sub-agent.

---
on:
  workflow_dispatch:

engine: copilot
---

# File Summary Task

Use the `file-summarizer` sub-agent to summarize `README.md` and add a comment
to the current pull request with the result.

## agent: `file-summarizer`
---
model: claude-haiku-4.5
description: Summarizes the content of a file in a few concise sentences
---
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.

The sub-agent block at the bottom is extracted before the workflow runs and has no effect on the parent workflow’s instructions.

Example: Multiple Sub-Agents in One Workflow

A single workflow file may contain more than one sub-agent block. Each block starts with its own ## agent: \name`heading and ends at a matching## end agent: `name`marker, the next##` heading, or EOF.

## agent: `summarizer`
---
model: claude-haiku-4.5
description: Summarizes files concisely
---
Summarize the given file in 2–4 sentences.

## agent: `reviewer`
---
model: claude-sonnet-4.5
description: Reviews code for quality issues
---
Review the given code for bugs, style issues, and potential improvements.

Related Documentation

• Importing Copilot Agent Files — Importing agents from .github/agents/
• DeterministicOps — Combining deterministic steps with AI reasoning
• Markdown — Workflow markdown body reference
• Workflow Structure — Overall workflow file organization
• Frontmatter — YAML configuration options