Subagents

You can create subagents in three ways: | Method | Description | |--------|-------------| | Programmatic | Use ClaudeCode.Agent structs with the agents option in start_link/1 or stream/3 (recommended for SDK applications) | | Filesystem-based | Define agents as markdown files in .claude/agents/ directories (see defining subagents as files) | | Built-in general-purpose | Claude can invoke the built-in general-purpose subagent at any time via the Agent tool without you defining anything | This guide focuses on the programmatic approach, which is recommended for SDK applications. When you define subagents, Claude determines whether to invoke them based on each subagent's description field. Write clear descriptions that explain when the subagent should be used, and Claude will automatically delegate appropriate tasks. You can also explicitly request a subagent by name in your prompt (for example, "Use the code-reviewer agent to...").

> Official Documentation: This guide is based on the official Claude Agent SDK documentation. Examples are adapted for Elixir. Define and invoke subagents to isolate context, run tasks in parallel, and apply specialized instructions in your Claude Agent SDK applications. Subagents are separate agent instances that your main agent can spawn to handle focused subtasks. Use subagents to isolate context for focused subtasks, run multiple analyses in parallel, and apply specialized instructions without bloating the main agent's prompt. This guide explains how to define and use subagents in the SDK using the agents option.

Each subagent runs in its own fresh conversation. Intermediate tool calls and results stay inside the subagent; only its final message returns to the parent. See What subagents inherit for exactly what's in the subagent's context. Example: a research-assistant subagent can explore dozens of files without any of that content accumulating in the main conversation. The parent receives a concise summary, not every file the subagent read.

Multiple subagents can run concurrently, dramatically speeding up complex workflows. Example: during a code review, you can run style-checker, security-scanner, and test-coverage subagents simultaneously, reducing review time from minutes to seconds.