Claude Agents Explained: Subagents, Agent SDK, Managed

A Claude agent is software where a Claude model plans its own steps and calls tools until a task is done. Anthropic offers four ways to build one: subagents inside Claude Code, the Claude Agent SDK library, hosted Claude Managed Agents on the API, and the tool runner in the Claude API SDKs. They differ in who hosts the loop.

“Claude agent” is used loosely, so searches mix all four together. This guide separates them, shows a minimal example of each, and tells you which to pick. Everything is checked against Anthropic’s Agent SDK overview and Managed Agents docs as of October 2026.

The four kinds of Claude agent at a glance

	Claude Code subagents	Claude Agent SDK	Claude Managed Agents	API tool runner
What it is	Specialist helpers inside a Claude Code session	Claude Code’s agent loop as a Python/TypeScript library	Hosted agent harness on the Claude API	SDK helper that loops over your own tools
Who runs the loop	Claude Code	The SDK, in your process	Anthropic	The client SDK, in your process
Who hosts it	Your machine (or Claude Code’s cloud)	You	Anthropic sandbox, or a self-hosted sandbox	You
Built-in tools	Claude Code’s tools	Read, write, edit, Bash, search, web	Bash, file ops, web search and fetch, MCP	None; you define every tool
You write	A Markdown file	A prompt plus options	Agent config plus events	Tool functions
Status (Oct 2026)	Generally available	Generally available	Beta	Beta
Best for	Splitting work in your own coding sessions	Shipping a coding or file agent in your app	Long-running, async or scheduled agents	Custom agents with narrow, app-specific tools

The short version: subagents improve your own Claude Code sessions; the other three are for building agents into products.

1. Subagents in Claude Code

Anthropic defines subagents as “specialized AI assistants that handle specific types of tasks.” Each one “runs in its own context window with a custom system prompt, specific tool access, and independent permissions.” Claude delegates to them based on their description, and they return only a summary to the main conversation.

That isolation is the point. A subagent can read fifty files or a long log, and your main session only sees the conclusion. You can also restrict tools (a read-only reviewer) or route cheap work to a faster model.

A subagent is a Markdown file with YAML frontmatter, stored in .claude/agents/ (project) or ~/.claude/agents/ (all your projects):

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Only name and description are required. Claude Code also ships built-in subagents such as Explore (fast, read-only codebase search), Plan (research during plan mode) and general-purpose.

Want ready-made ones? Collections like VoltAgent’s subagents and wshobson/agents provide dozens to copy. Our Claude Code subagents guide walks through creating, invoking and debugging them, and skills vs subagents vs hooks explains when a subagent is the wrong tool.

Pick subagents when you already use Claude Code and want specialists for review, research or testing without polluting your main context. New to Claude Code itself? Start with what Claude Code is.

2. The Claude Agent SDK

The Agent SDK “gives you the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript.” It bundles a native Claude Code binary, so you call one function and get a working agent with file editing, shell commands, web search, hooks, subagents, MCP, permissions and sessions.

Install it:

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

# Python
pip install claude-agent-sdk

A minimal bug-fixing agent from the official quickstart (Python):

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage


async def main():
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")


asyncio.run(main())

The TypeScript version uses the same query() entry point with allowedTools and permissionMode. Requirements are Node.js 18+ or Python 3.10+, and an ANTHROPIC_API_KEY from the Claude Console (Bedrock, Google Cloud, Microsoft Foundry and Claude Platform on AWS are also supported through environment variables).

Two rules worth knowing before you ship:

• Authentication: Anthropic does not allow third-party products, including Agent SDK agents, to offer claude.ai login or subscription rate limits unless previously approved. Use API keys. Our Claude API key guide covers creating and storing one.
• Branding: you may call your product “Claude Agent” or “YourAgent Powered by Claude”, but not “Claude Code”.

Not in Python or TypeScript? Run the Claude Code CLI as a subprocess with -p and --output-format json, as explained in our headless mode guide.

Pick the Agent SDK when you want a batteries-included coding or file-system agent inside your own app, CI job or internal tool, on infrastructure you control. For a step-by-step build with a custom tool and a spending cap, follow how to build an AI agent with Claude.

3. Claude Managed Agents

Managed Agents is “a pre-built, configurable agent harness that runs in managed infrastructure.” Instead of building your own loop, sandbox and tool execution, Anthropic runs them for you. Claude can read files, run commands, browse the web and run code inside a per-session sandbox.

It is built on four concepts:

Concept	What it is
Agent	The model, system prompt, tools, MCP servers and skills. Create once, reuse by ID.
Environment	Where sessions run: an Anthropic cloud sandbox or a self-hosted sandbox
Session	A running agent instance doing one task
Events	Messages between your app and the agent, streamed over server-sent events

Built-in tools cover Bash, file operations (read, write, edit, glob, grep), web search and fetch, and MCP servers. Sessions are stateful: history, sandbox files and outputs are stored server-side, and you can steer or interrupt a running agent. Scheduled deployments let an agent run on a cron schedule.

Status and caveats as of October 2026:

• Beta. All endpoints need the managed-agents-2026-04-01 header; the official SDKs add it for you.
• Access is enabled by default for Claude API accounts; you need a Console API key.
• Because it is stateful, Managed Agents is not eligible for Zero Data Retention or HIPAA BAA coverage. You can delete sessions and files through the API.

Pick Managed Agents when the work is long-running (minutes or hours), asynchronous, scheduled, or you simply don’t want to operate sandboxes yourself.

4. The Claude API tool runner (and manual loops)

The lowest layer is the plain Messages API with tool use. You define tools with a JSON schema, Claude asks to call them, your code runs them and sends results back. The SDKs’ tool runner (beta) automates that loop: it runs your tools when Claude calls them, manages conversation state and validates inputs. In Python you decorate functions with @beta_tool; in TypeScript you use betaZodTool with Zod schemas.

There are no built-in tools here. That is a feature when you want an agent that can only call your own functions, such as “look up an order” or “issue a refund”. When you need human approval or custom logging on every step, Anthropic recommends writing the loop by hand instead.

Our Claude API tutorial covers your first request and tool-use basics, and Claude API pricing explains what agent loops cost in tokens.

Pick the tool runner when you want full control, a small custom tool surface, and no dependency on Claude Code.

How to choose: a decision path

1. Are you improving your own coding workflow? Use Claude Code subagents. Done.
2. Building a product, and Anthropic should host the agent and sandbox? Use Managed Agents.
3. Building a product you host, and the agent needs files, shell and web out of the box? Use the Agent SDK.
4. Building a product with only your own tools? Use the Messages API with the tool runner or a manual loop.

A useful mental model from Anthropic’s docs: the Agent SDK and tool runner supply the harness only, and you deploy them. Managed Agents supplies the harness and the deployment.

Which model should your agent use?

All four options run Claude models, and you choose which. Larger models handle long, ambiguous tasks better; smaller ones are cheaper and faster for narrow subtasks, which is why subagents often run on a lighter model than the main session. Compare the current lineup in Claude models explained.

Before you build: should it be an agent at all?

Agents cost more and take longer than a single API call. A fixed pipeline (classify, extract, summarise) usually works better as one or two plain requests. Reach for an agent when the task is multi-step, hard to specify in advance, worth the extra cost, and errors can be caught by tests or review.

Whichever route you take, the pieces you build (subagents, skills, MCP servers, hooks) become part of your Claude kit, and many of them carry over between Claude Code, the Agent SDK and Managed Agents.