✨ New — April 2026 Claude Code Multi-Agent Orchestration

Claude Managed Agents:
How They Work & How to Use Them

Anthropic launched Claude Managed Agents in April 2026 — enabling Claude Code to spawn, orchestrate, and manage multiple specialist AI agents in a single autonomous workflow. This is the definitive guide: what managed agents are, how they work, and how Brainfile configurations unlock their full potential.

Get Brainfile Agent OS — $99/mo → Annual Plan — $999/yr (Save 15%)

Published April 2026 14 min read For Claude Code users who want autonomous multi-agent workflows

Parallel

specialist agents running simultaneously — code review, testing, docs, deployment in one workflow

Persistent

agents maintain context across sessions, not just within a single conversation

Orchestrated

Claude routes tasks automatically — no manual invocation of each agent

10x Better

with Brainfile — every agent gets shared knowledge, conventions, and structured playbooks

Table of Contents

What are Claude Managed Agents?
How managed agents work in Claude Code
The AGENTS.md file: defining your agent network
Real-world use cases for managed agents
Why Brainfile configurations supercharge managed agents
Step-by-step: setting up your first managed agent workflow
Managed agents vs. subagents vs. slash commands
Frequently asked questions

What Are Claude Managed Agents?

Claude Managed Agents is a feature Anthropic shipped in April 2026 as part of Claude Code. It allows Claude to act as an orchestrator — spawning, directing, and managing multiple specialist AI agents that work in parallel or in sequence to complete complex, multi-step tasks.

Before managed agents, Claude Code operated as a single, sequential AI assistant. You could use subagents via slash commands, but each agent was invoked manually and operated independently within a single session. Managed agents change this fundamentally: Claude can now autonomously decide to spawn a specialist, hand off a subtask, collect the result, and synthesize across multiple parallel workstreams — without you manually directing each step.

The key shift: With managed agents, Claude moves from assistant to orchestrator. Instead of you managing Claude's workflow, Claude manages its own network of specialized agents — routing the right work to the right specialist, collecting results, and synthesizing a unified output. You define the goal. Claude manages the execution.

Think of it as the difference between being a manager who personally handles every task versus being a manager who has a team of specialists. Claude Managed Agents gives Claude Code a team. The orchestrating Claude coordinates; specialist agents execute. The result is faster, higher-quality output on complex tasks that benefit from specialization and parallelism.

🏗

Orchestrator Agent

The top-level Claude instance that reads the task, decomposes it into subtasks, assigns each subtask to the right specialist agent, and synthesizes results into the final output.

🔍

Specialist Agents

Focused Claude instances with narrow, defined roles — code reviewer, test writer, documentation generator, security scanner. Each runs in its own context and returns structured output.

🔁

Parallel Execution

Multiple specialist agents run simultaneously. Code review, test generation, and documentation can happen at the same time, not sequentially — cutting total workflow time dramatically.

📋

Structured Handoffs

Agents communicate through defined interfaces — structured output formats that the orchestrator can parse and route. No ambiguous hand-waving between agents.

How Managed Agents Work in Claude Code

Understanding the mechanics of managed agents helps you configure them effectively. Here is the step-by-step execution model when you submit a task to a managed agent workflow in Claude Code.

Task Intake & Decomposition

The orchestrator receives your task. It reads your AGENTS.md configuration to understand the available specialist agents and their capabilities, then decomposes the task into discrete subtasks that can be assigned to appropriate specialists.

Context Loading

Both the orchestrator and each specialist agent load relevant context — CLAUDE.md operating system, brain/ directory knowledge, and any task-specific context. This is where Brainfile configurations provide massive value: every agent starts with your full knowledge base loaded automatically.

Parallel Dispatch

Subtasks are dispatched to specialist agents in parallel where dependencies allow. A code review agent, a test generation agent, and a documentation agent can all run simultaneously on the same codebase change — each focused on its specialty.

Specialist Execution

Each specialist agent runs its focused task — reviewing code against your security checklist, writing tests against your testing strategy, generating docs in your format — using the shared context from your Brainfile configuration to ground its output in your standards.

Result Synthesis

The orchestrator collects structured outputs from all specialist agents, resolves any conflicts (e.g., the code reviewer flagged an issue that the test writer needs to account for), and synthesizes a unified final output that reflects all specialist findings.

Output Delivery & Next Steps

You receive the final synthesized output. The orchestrator can also trigger follow-up actions — filing issues, updating documentation, running specific tests — based on rules defined in your AGENTS.md configuration.

The Role of AGENTS.md

AGENTS.md is a new configuration file introduced alongside Claude Managed Agents. Where CLAUDE.md defines your operating system-level context (who Claude is, what it knows, what standards apply to all tasks), AGENTS.md defines your agent network: which specialists exist, what each handles, how they communicate, and what escalation rules govern the workflow.

Without AGENTS.md, Claude uses default managed agent behavior — functional but generic. With a properly configured AGENTS.md, you define an agent network tailored to your specific workflows and domain. Brainfile's agent configurations include both CLAUDE.md and AGENTS.md, pre-configured for common workflow types with the ability to customize for your specific needs.

The AGENTS.md File: Defining Your Agent Network

AGENTS.md is to managed agents what CLAUDE.md is to single-session Claude — the configuration layer that transforms generic capability into a precisely calibrated system. Here is what a production AGENTS.md looks like for a software engineering team using Claude Managed Agents for their PR review and release workflow.

# AGENTS.md — Managed Agent Network Configuration
# Loaded by Claude orchestrator when spawning managed agents

## Agent Roster

### code-reviewer
Role: Security, style, and architecture review of code changes
Input: Git diff or PR number
Output: Structured JSON — {violations: [], suggestions: [], severity: "pass|warn|block"}
Context: Load brain/security/review-checklist.md + brain/conventions.md
Escalate to human if: severity=block or any critical security violation

### test-generator
Role: Generate unit and integration tests for changed code
Input: Changed files + test coverage report
Output: Test files in /tests/ following brain/testing-strategy.md format
Context: Load brain/testing-strategy.md + brain/architecture/service-topology.md
Escalate to human if: Changed code is in payment or auth paths

### doc-writer
Role: Update API docs, README, and inline comments for changed functions
Input: Changed files + current docs
Output: Updated doc files in your team's format (see brain/docs/api-doc-template.md)
Context: Load brain/docs/api-doc-template.md + brain/conventions.md
Run: Only if public API surface changed

### release-notes-writer
Role: Draft release notes from PR descriptions and commit messages
Input: PR list, commit log, user-facing change detection
Output: Release notes in brain/docs/release-notes-template.md format
Context: Load brain/docs/release-notes-template.md
Run: Only on releases tagged for deployment

## Orchestration Rules

On PR submission: Run code-reviewer + test-generator in parallel
After code-reviewer passes: Run doc-writer if API surface changed
On release tag: Run release-notes-writer
Block merge if: code-reviewer returns severity=block
Auto-approve merge if: code-reviewer=pass + test-generator=pass + coverage >= 80%

## Escalation Policy

Human review required: severity=block, payment/auth changes, coverage drop > 5%
Notification channel: GitHub PR comment + Slack #engineering-alerts
SLA for human review: 4 hours during business hours, next day otherwise
    

What makes this powerful: The AGENTS.md above defines a fully autonomous PR review and release workflow. Claude spawns the right agents for each trigger, runs them in parallel where possible, enforces your quality gates automatically, and only involves a human when defined escalation conditions are met. For 80% of PRs, this workflow completes with zero human intervention beyond the initial PR submission.

Real-World Use Cases for Managed Agents

Claude Managed Agents shine on any multi-step workflow where tasks can be parallelized or benefit from specialization. Here are the highest-value use cases across software engineering, content operations, and business workflows.

Software Engineering: Full PR Review Pipeline

The most common engineering use case. A single PR submission triggers a parallel managed agent workflow: security and style review, test generation for changed code, documentation updates for changed APIs, and a release notes draft if the PR is tagged for release. All four agents run in parallel, complete in minutes, and the orchestrator synthesizes findings into a single PR comment with clear pass/fail status on each gate. What previously required four separate manual steps — each requiring context-loading and setup — becomes one autonomous workflow.

Saves 4 to 6 hrs per PR review cycle

Content Operations: Research-to-Publish Pipeline

For content teams, managed agents enable a full research-to-publication workflow. The orchestrator receives a content brief, spawns a research agent (gather sources, extract key data), a writing agent (draft the piece), a fact-check agent (verify claims against sources), and an SEO agent (check keyword coverage and meta). All four work in parallel where possible, the orchestrator synthesizes into a complete draft with citations verified and SEO requirements met. One brief in, one publication-ready document out.

Saves 3 to 5 hrs per long-form content piece

Business Analysis: Data-to-Report Pipeline

Business intelligence workflows that previously required multiple manual handoffs between analysts can run as managed agent workflows. Trigger: a new data export or dashboard update. Managed agents: data analysis agent (identify trends, anomalies, key metrics), narrative agent (write the executive summary), visualization suggestion agent (recommend chart types and layouts), action items agent (extract clear next steps). The orchestrator synthesizes into a complete business report ready for stakeholder review — in the time it used to take to write the executive summary alone.

Saves 2 to 4 hrs per business intelligence report

Other High-Value Managed Agent Workflows

Codebase onboarding: New engineer joins — a managed agent workflow reads the codebase, generates architecture summary, identifies key patterns, writes a "getting started" guide, and creates a list of good first issues. Done autonomously before the engineer's first day.
Security audit pipeline: Weekly automated security review — managed agents check for new CVEs in dependencies, scan for new code patterns matching known vulnerability classes, review recent PRs for security regressions, and produce a prioritized security report.
Customer support escalation: Incoming support ticket triggers agents that classify the issue, search the knowledge base for relevant answers, draft a response, and check if a bug report should be filed — all before a human support agent even opens the ticket.
Competitive intelligence: Scheduled workflow spawning agents to monitor competitor product pages, changelog feeds, and job postings — synthesizing weekly into a competitive intelligence brief with flagged changes and strategic implications.

Why Brainfile Configurations Supercharge Managed Agents

Claude Managed Agents are powerful out of the box. But without persistent, structured context, each agent in your network still starts with limited knowledge — it knows its immediate task but not your codebase, your conventions, your standards, or your domain. Every agent prompt has to carry the full context burden, or agents produce generic output that requires heavy manual review and revision.

Brainfile configurations solve this at the operating system level. Because Brainfile's CLAUDE.md and brain/ directory are loaded at every Claude Code session start — including when managed agents are spawned — every agent in your network automatically inherits your full knowledge base. The code reviewer already knows your security checklist. The test generator already knows your testing strategy. The doc writer already knows your documentation format. No per-agent context setup required.

Without Brainfile

Each managed agent spawns with only its immediate task prompt. Code reviewer uses generic best practices. Test generator doesn't know your testing strategy. Doc writer uses a default format. Orchestrator has to include massive context blocks in every agent prompt — or accept lower-quality generic output.

With Brainfile

Every agent loads your CLAUDE.md OS and brain/ directory automatically. Code reviewer applies YOUR security checklist. Test generator follows YOUR testing strategy. Doc writer uses YOUR template. Orchestrator just specifies the task — context is already there. Higher quality, zero context overhead.

The Three Layers of Brainfile Agent Configuration

🧠

Layer 1: CLAUDE.md Intelligence

Your operating system — stack context, conventions, architectural decisions, security standards, and domain knowledge. Every agent in your network loads this automatically. Shared ground truth across your entire agent network.

📁

Layer 2: Project-Specific Rules

Per-project AGENTS.md and brain/ directories that encode domain-specific knowledge. Each project gets its own agent network configuration, while inheriting shared conventions from CLAUDE.md.

⚡

Layer 3: Skill Library

Pre-built agent skill configurations for common workflows — PR review pipeline, content pipeline, security audit, customer support triage. Drop in a skill, customize the parameters, and your managed agent workflow is live immediately.

Managed Agent Capability Comparison

Capability	Managed Agents (no config)	Managed Agents + Brainfile
Shared knowledge across agents	Manual — must include in every prompt	Automatic — CLAUDE.md loads at every agent spawn
Code review quality	Generic best practices	Against YOUR security checklist and style guide
Test generation	Generic test patterns	Follows YOUR testing strategy and coverage standards
Documentation output	Generic markdown	Your exact doc format, terminology, and style
Workflow repeatability	Re-describe workflow each run	Defined once in AGENTS.md, runs identically every time
Setup time per workflow	30-60 min per workflow	5-10 min — pre-built skill library + customize parameters
Output consistency across agents	Each agent uses its own defaults	All agents use the same conventions from CLAUDE.md

Step-by-Step: Setting Up Your First Managed Agent Workflow

Here is how to set up a working managed agent workflow for PR review using Brainfile's Agent OS configuration. This takes 15 to 30 minutes on first setup and runs autonomously on every subsequent PR.

Step 1: Install Brainfile Agent OS

Brainfile Agent OS includes the CLAUDE.md operating system, a starter brain/ directory, a pre-configured AGENTS.md for common engineering workflows, and the skill library. Clone it into the root of your repository or into a shared configuration repository that your team references.

# Clone the Brainfile Agent OS into your project root
git clone https://github.com/brainfile-io/agent-os ./brainfile

# Or, if using Brainfile via the subscriber download:
# Unzip the downloaded archive to your project root
cp CLAUDE.md ./CLAUDE.md
cp AGENTS.md ./AGENTS.md
cp -r brain/ ./brain/
    

Step 2: Configure CLAUDE.md With Your Stack Context

Open CLAUDE.md and fill in your stack details, conventions, and architectural decisions. The Brainfile Agent OS includes an annotated starter CLAUDE.md with sections for every common context type — stack, conventions, ADRs, security standards, known failure modes, and documentation formats. Most of this is a one-time setup; once it's in CLAUDE.md, every agent in your network has it automatically.

Step 3: Customize AGENTS.md for Your Workflow

The starter AGENTS.md includes pre-configured workflows for PR review, release notes, security audit, and codebase onboarding. For each workflow you want to use, review the agent roster and customization points — primarily the escalation conditions, output formats, and trigger events. For the PR review workflow, you specify your coverage threshold, your escalation channel, and which paths require human review. Everything else runs out of the box.

## Customization Points in Starter AGENTS.md

# Set your coverage threshold
COVERAGE_THRESHOLD: 80  # Change to your team's standard

# Set escalation channel
ESCALATION_CHANNEL: #engineering-alerts  # Your Slack channel

# Define paths requiring human review
HUMAN_REVIEW_PATHS: ["/payments/", "/auth/", "/admin/"]

# Set auto-approve criteria
AUTO_APPROVE: code_review=pass AND test_coverage >= COVERAGE_THRESHOLD
    

Step 4: Add Domain Knowledge to brain/

The brain/ directory is where you store the knowledge that makes your agent network smarter than a generic AI setup. For engineering teams, the highest-value brain/ files are: your security review checklist, your testing strategy document, your architecture topology map, your API documentation template, and your ADR history. Each file is loaded by the relevant agent when it needs that knowledge — you write it once, every agent uses it correctly.

Step 5: Test With a Real Workflow

Run Claude Code on a real or recent PR and invoke the managed agent PR review workflow. Watch the orchestrator decompose the PR, spawn the specialist agents, and synthesize the results. Check the output against your standards — the first run will reveal any CLAUDE.md context gaps or AGENTS.md configuration adjustments needed. Most teams need one to three iterations before the workflow output is indistinguishable from a thorough human review.

Time to first useful output: Most Brainfile subscribers report that their PR review managed agent workflow produces genuinely useful, standards-compliant output within 2 to 4 hours of initial setup. The main iteration is refining CLAUDE.md to include the context that each agent needs — a process that also improves every other Claude Code session, not just agent workflows.

Managed Agents vs. Subagents vs. Slash Commands

Claude Code has evolved through several phases of multi-agent capability. Understanding where managed agents fit relative to earlier features helps you choose the right tool for each workflow.

Feature	Slash Commands	Subagents	Managed Agents
Invocation	Manual (/command)	Manual or scripted	Autonomous — Claude decides when to spawn
Parallelism	Sequential only	Possible but manual	Automatic parallel dispatch
Context sharing	Current session only	Limited cross-agent sharing	Defined interfaces + shared CLAUDE.md
Persistence	Session-scoped	Session-scoped	Cross-session, schedulable
Orchestration logic	None — you orchestrate	Limited	Full orchestration via AGENTS.md
Best for	Single-step recurring tasks	Semi-automated workflows with human checkpoints	Fully autonomous multi-step workflows

The right answer depends on your workflow's complexity and autonomy requirements. For simple, single-step recurring tasks (generate a commit message, run a specific check, format a file), slash commands remain the best tool. For workflows requiring multiple specialized outputs with dependencies between them and minimal human intervention, managed agents are the right choice. For workflows that need human checkpoints but benefit from AI assistance at each step, subagents still have a place.

Brainfile configurations support all three modes — the CLAUDE.md and brain/ directory improve every Claude Code interaction regardless of whether you're running a slash command, a subagent, or a full managed agent workflow.

Frequently Asked Questions

What are Claude Managed Agents?

Claude Managed Agents is a feature launched by Anthropic in April 2026 that allows Claude Code to spawn, orchestrate, and manage multiple specialized AI agents as part of a single long-running workflow. Instead of a single Claude session handling all tasks sequentially, managed agents let you run specialist agents in parallel — one agent focused on code review, another on test generation, another on documentation — with Claude acting as the orchestrator that routes tasks and synthesizes results.

How do Claude Managed Agents differ from Claude Code subagents?

Claude Code subagents (launched 2025) run within a single session and are spawned manually via slash commands. Claude Managed Agents (April 2026) go further: they are persistent, schedulable, and can be orchestrated automatically by Claude without manual invocation. Managed agents maintain their own context windows, can run in parallel across multiple compute instances, and can hand off work to each other through defined interfaces — enabling truly autonomous long-running workflows that outlast a single conversation session.

Do I need a special Claude plan to use Claude Managed Agents?

Claude Managed Agents requires access to Claude Code, which is available on Claude Pro ($20/month) and Claude Team/Enterprise plans. The Anthropic API SDK also supports managed agent orchestration for developers building agent workflows programmatically. Brainfile configurations work with any Claude plan that includes Claude Code access.

How does Brainfile improve Claude Managed Agent workflows?

Without a Brainfile configuration, each managed agent starts with only the context provided in its immediate task prompt. With Brainfile, every agent in the workflow — orchestrator and specialists alike — loads your CLAUDE.md operating system and brain/ directory at session start. This means agents share your coding conventions, your architecture documentation, your security standards, and your domain knowledge automatically. You get consistent, high-quality output from every agent in the chain without manually providing context to each one.

Can I use Claude Managed Agents for non-coding workflows?

Yes. Claude Managed Agents can orchestrate any multi-step workflow where tasks can be parallelized or delegated to specialists. Common non-coding use cases include: research pipelines (gather, synthesize, draft, review), marketing workflows (brief, write copy, critique, revise), business analysis (collect data, analyze, write report, generate slides), and operations automation (monitor, triage, respond, escalate). Brainfile configurations encode domain knowledge for any of these verticals.

What is the relationship between AGENTS.md and CLAUDE.md in managed agent workflows?

CLAUDE.md is the root operating system file that every Claude Code session reads at startup — it establishes global context, conventions, and directives. AGENTS.md defines the agent network: which agent handles which task class, how agents communicate, what handoff formats to use, and escalation rules. Together they form a two-layer configuration: CLAUDE.md provides the shared knowledge base that all agents inherit, while AGENTS.md defines the orchestration logic. Both files are included in Brainfile's agent workflow configurations.

Get the Brainfile Agent OS for Managed Agents

Stop configuring agents from scratch. Brainfile includes a pre-built CLAUDE.md operating system, structured brain/ directory, AGENTS.md starter configurations for common workflows, and the skill library — so your managed agent network is production-ready in hours, not days.