✨ 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 as a beta on the Claude API: a hosted harness that runs Claude as an autonomous agent in Anthropic's cloud. Inside Claude Code, the multi-agent tool is subagents. This guide explains both and where a CLAUDE.md fits. This is the definitive guide: what managed agents are, how they work, and how Brainfile configurations unlock their full potential.

Free by email: a practical Claude Code tip every Tuesday and Thursday, plus a Sunday recap.

Get Brainfile Pro — $99/mo → Annual Plan — $999/yr (save $189)

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

Shared

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

Table of Contents

What are Claude Managed Agents?
How multi-agent work runs in Claude Code
An agent roster: 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?

Checked against Anthropic's Managed Agents overview and Claude Code subagents docs on 2026-10-08. Claude Managed Agents is a beta on the Claude API, not a Claude Code feature: Anthropic calls it a "pre-built, configurable agent harness that runs in managed infrastructure." Your application creates an agent (model, system prompt, tools, MCP servers, skills), an environment (an Anthropic cloud sandbox or your own) and long-running sessions, all through the API with the managed-agents-2026-04-01 beta header. An earlier version of this page called it part of Claude Code and said it was configured with AGENTS.md; neither is true.

The orchestrator-and-specialists pattern the rest of this page describes is what Claude Code's subagents do inside a session. Claude delegates to a subagent automatically when a task matches its description (or you @-mention one), subagents can run in the background in parallel, and each returns a summary to the main conversation. Claude can 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 Multi-Agent Work Runs 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 the descriptions of the subagents in .claude/agents/ to see 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 in your CLAUDE.md and subagent files.

Where AGENTS.md fits (it doesn't, here)

Anthropic's docs do not use AGENTS.md to configure Managed Agents or subagents. Managed Agents are defined through the API; Claude Code subagents are Markdown files in .claude/agents/. AGENTS.md is a cross-tool project-instructions file that Claude Code reads only when a repository has no CLAUDE.md (Claude Code memory docs). The roster below is written as one file for readability; to run it in Claude Code, put each role in its own .claude/agents/<name>.md file.

An Agent Roster: Defining Your Agent Network

Here is an example agent roster for a software engineering team's PR review and release workflow, written as one file for readability. In Claude Code, each role becomes its own subagent file.

# Agent roster (example): one .claude/agents/<name>.md file per role
# 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 roster 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.

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.

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.

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.

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 — and subagents load project instructions too unless set to skip them — 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 configuration. 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 .claude/agents/ files 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

Skill configurations you write for common workflows — PR review pipeline, content pipeline, security audit, customer support triage. Write each skill once, customize the parameters, and reuse it across workflows.

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 subagent files, runs identically every time
Setup time per workflow	Per workflow, from scratch	Faster after the first one — reuse your own skill files
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, with Brainfile's files as the CLAUDE.md base. This takes 15 to 30 minutes on first setup and runs autonomously on every subsequent PR.

Step 1: Put Brainfile's files in your repository

Start the free 30-day Brainfile trial (no card) and run the cloud pull in your repository root. It writes the Autopilot protocol, a CLAUDE.md starter and brain/ files. Brainfile does not ship subagent files or a skill library; you add those in step 3.

# In your project root, after starting the trial at brainfile.io/trial,
# run the pull command from your welcome email. Then:
mv CLAUDE.starter.md CLAUDE.md
mkdir -p .claude/agents  # subagent files: yours to write (step 3)

Step 2: Configure CLAUDE.md With Your Stack Context

Open CLAUDE.md and fill in your stack details, conventions, and architectural decisions. Brainfile's CLAUDE.md starter and /start interview cover your stack, conventions and key decisions; add sections for 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: Write Subagent Files for Your Workflow

Write subagent files (.claude/agents/) for 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 follows from your CLAUDE.md.

## Customization points (CLAUDE.md or the subagent files)

# 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 configuration, 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 subagent-file adjustments needed. Expect a few iterations before the output matches your standards.

Time to first useful output: Expect a few iterations. Most of the work is adding to CLAUDE.md the context each agent needs, which also improves every other Claude Code session.

Managed Agents vs. Subagents vs. Slash Commands

These are two different products, not two phases of one. Sources: Claude Code subagents docs, Managed Agents overview (checked 2026-10-08).

Feature	Claude Code subagents	Claude Managed Agents
What it is	Specialist assistants inside your Claude Code session	A hosted agent harness on the Claude API (beta)
Where it runs	Your machine, or a Claude Code cloud session	An Anthropic cloud sandbox or a self-hosted sandbox
How it starts	Claude delegates when a task matches the subagent's description, or you @-mention it	Your application creates a session and sends events over the API
Defined in	Markdown files in .claude/agents/	API objects: agent, environment, session
Parallelism	Can run in the background while you keep working	Each session is its own running agent
State	Returns a summary to the main conversation	Stateful: history, sandbox state and outputs stored server-side
Billing	Your Claude plan or API usage	Claude API usage

For work in your own repository, subagents are the tool, and a CLAUDE.md gives every one of them the same context. Managed Agents fit agents that your own product runs in the cloud. Brainfile ships the CLAUDE.md side either way.

Frequently Asked Questions

What are Claude Managed Agents?

Claude Managed Agents is a beta on the Claude API (beta header managed-agents-2026-04-01) that Anthropic describes as a pre-built, configurable agent harness that runs in managed infrastructure. You define an agent (model, system prompt, tools, MCP servers, skills), an environment and sessions through the API, and Anthropic runs it in a cloud or self-hosted sandbox. It is not a Claude Code setting; inside Claude Code the multi-agent tool is subagents.

How do Claude Managed Agents differ from Claude Code subagents?

Subagents run inside your Claude Code session: Markdown files in .claude/agents/ that Claude delegates to automatically when a task matches their description, or that you @-mention. They can run in the background in parallel and return a summary to the main conversation. Managed Agents are separate: a Claude API beta where your application creates long-running, stateful sessions that Anthropic hosts. Choose subagents for work on your machine in a Claude Code session, Managed Agents for agents your own product runs in the cloud.

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

Managed Agents need a Claude API key and the managed-agents-2026-04-01 beta header; Anthropic says access is enabled by default for all API accounts. It is billed through the API, not through a Claude Pro or Max plan. Claude Code subagents work on any plan that includes Claude Code.

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?

In Claude Code, CLAUDE.md is the project instruction file every session loads. AGENTS.md is a cross-tool instruction file that Claude Code reads only when a repository has no CLAUDE.md. Neither file configures Managed Agents, which are defined through the API, and subagents are defined in .claude/agents/. Brainfile ships the CLAUDE.md side.

Get Brainfile for the CLAUDE.md Side of Managed Agents

Brainfile gives you the Autopilot protocol, 10 pattern files (CLAUDE.md starter, brain/ backlog and ledger, memory) and a weekly freshness feed. Pro adds 15 role packs. Subagent files and skills stay yours to write.