A Complete Guide to Anthropic’s Claude Managed Agents and the Harness Platform

Core Concepts

Claude Managed Agents are built around four tightly coupled concepts that together form the Harness orchestration engine.

1. Agent (the intelligent entity)

An Agent is a reusable configuration that defines the model, system prompt, enabled tools, and optional MCP services. Creating an agent returns an agent.id that can be reused across sessions.

from anthropic import Anthropic
client = Anthropic()
agent = client.beta.agents.create(
    name="Code Reviewer",
    model="claude-sonnet-4-6",
    system="You are a senior code reviewer. Review code for bugs, performance issues, and security vulnerabilities. Be direct and specific.",
    tools=[{"type": "agent_toolset_20260401"}]
)
print(agent.id)  # ag_01ABC...

The built‑in agent_toolset_20260401 bundle includes Bash, file read/write/edit, code search (Glob/Grep), and web access. Individual tools can be disabled if not needed.

Agents are versioned; each update creates a new version that can be inspected or pinned to a session for safe production rollout.

2. Environment (execution template)

An Environment defines the runtime context—dependency packages, network rules, and mounted files. It is created once and cached for fast session startup.

environment = client.beta.environments.create(
    name="python-dev",
    config={
        "type": "cloud",
        "packages": {
            "pip": ["pytest", "requests", "pandas"],
            "apt": ["git", "curl"]
        },
        "networking": {"type": "unrestricted"}
    }
)

Network mode defaults to unrestricted but can be switched to limited with a domain whitelist for sensitive workloads.

You can also mount a GitHub repository directly, allowing the agent to treat the repo like a local project.

environment = client.beta.environments.create(
    name="my-repo-env",
    config={
        "type": "cloud",
        "github": {"repository": "myorg/myrepo", "branch": "main"},
        "packages": {"pip": ["pytest"]},
        "networking": {"type": "unrestricted"}
    }
)

3. Session (runtime instance)

A Session is a container that runs an Agent inside a specific Environment. Each session has its own filesystem, processes, and network namespace, ensuring isolation between concurrent runs.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)
print(session.id)   # ses_01XYZ...
print(session.status)  # "running"

Sessions persist until manually closed or timed out, preserving state across multiple turns, similar to Claude Code’s continuous conversation mode.

4. Events (communication channel)

Events provide a Server‑Sent Events (SSE) stream that lets you send user messages to the running agent and receive real‑time responses, tool invocations, and status updates.

with client.beta.sessions.events.stream(session.id) as stream:
    client.beta.sessions.events.send(
        session.id,
        events=[{"type": "user.message", "content": [{"type": "text", "text": "Review the code in src/ for security issues"}]}]
    )
    for event in stream:
        if event.type == "agent.message":
            for block in event.content:
                if hasattr(block, "text"):
                    print(block.text, end="")
        elif event.type == "agent.tool_use":
            print(f"
[Using tool: {event.name}]")
        elif event.type == "session.status_idle":
            print("
[Agent finished]")
            break

The stream makes the entire reasoning process observable—file reads, command executions, web searches—all appear as events that can be interrupted if needed.

Full End‑to‑End Example

The following script creates a Python‑developer agent, provisions a cloud environment with common packages, starts a session, and streams a task that builds a FastAPI service with health and Fibonacci endpoints.

from anthropic import Anthropic
client = Anthropic()
# 1. Create the agent
agent = client.beta.agents.create(
    name="Python Developer",
    model="claude-sonnet-4-6",
    system="""You are an expert Python developer. When given a task:
1. Plan your approach first
2. Write clean, well‑tested code
3. Run the tests to verify everything works
4. Fix any issues before reporting completion""",
    tools=[{"type": "agent_toolset_20260401"}]
)
# 2. Create the environment
environment = client.beta.environments.create(
    name="python-env",
    config={
        "type": "cloud",
        "packages": {"pip": ["pytest", "requests", "pydantic", "fastapi", "uvicorn"]},
        "networking": {"type": "unrestricted"}
    }
)
# 3. Start the session
session = client.beta.sessions.create(agent=agent.id, environment_id=environment.id)
# 4. Send the task and stream the response
with client.beta.sessions.events.stream(session.id) as stream:
    client.beta.sessions.events.send(
        session.id,
        events=[{"type": "user.message", "content": [{"type": "text", "text": """
            Build a FastAPI app with:
            - A /health endpoint
            - A /fibonacci/{n} endpoint returning the nth Fibonacci number
            - Input validation (n between 1 and 1000)
            - Unit tests for both endpoints
            Run the tests and ensure they all pass.
        """}]}]
    )
    for event in stream:
        if event.type == "agent.message":
            for block in event.content:
                if hasattr(block, "text"):
                    print(block.text, end="")
        elif event.type == "agent.tool_use":
            print(f"
  → {event.name}")
        elif event.type == "session.status_idle":
            break

The agent plans, writes code, installs dependencies, runs tests, and streams each step back to the client.

Custom Tools and MCP Server Integration

Beyond the built‑in toolbox, you can define JSON‑Schema‑based custom tools. When the agent decides to call a tool, it sends a structured request that your service executes and returns the result.

agent = client.beta.agents.create(
    name="Deploy Assistant",
    model="claude-sonnet-4-6",
    system="You help with deployments. Use the deploy tool to trigger deployments.",
    tools=[
        {"type": "agent_toolset_20260401"},
        {
            "type": "custom",
            "name": "trigger_deploy",
            "description": "Trigger a deployment to a specified environment",
            "input_schema": {
                "type": "object",
                "properties": {
                    "service": {"type": "string", "description": "Service name"},
                    "environment": {"type": "string", "enum": ["staging", "production"]},
                    "version": {"type": "string", "description": "Version tag to deploy"}
                },
                "required": ["service", "environment", "version"]
            }
        }
    ]
)

When the agent emits a trigger_deploy event, your event‑stream handler can invoke your CI/CD pipeline, then return the deployment status.

If you already use Anthropic’s MCP (Message‑Control‑Protocol) services such as Slack, GitHub, or Jira, Managed Agents can connect directly, eliminating the need to write additional integration code.

Multi‑Agent Orchestration (Research Preview)

Managed Agents also support a preview of hierarchical orchestration: a coordinator agent can split a task and delegate subtasks to specialized worker agents.

# Create specialist agents
reviewer = client.beta.agents.create(
    name="Code Reviewer",
    model="claude-sonnet-4-6",
    system="You are an expert code reviewer. Focus on code quality, bugs, and security.",
    tools=[{"type": "agent_toolset_20260401"}]
)

tester = client.beta.agents.create(
    name="Test Writer",
    model="claude-sonnet-4-6",
    system="You write comprehensive test suites. Focus on edge cases and error handling.",
    tools=[{"type": "agent_toolset_20260401"}]
)
# Coordinator that knows about the workers
coordinator = client.beta.agents.create(
    name="Tech Lead",
    model="claude-opus-4-6",
    system="""You are a tech lead managing a code review process. You have two team members:
- Code Reviewer: Reviews code for quality, bugs, and security
- Test Writer: Writes comprehensive tests
Delegate review and testing tasks to the appropriate specialist, then synthesize their findings into a final report.""",
    tools=[{"type": "agent_toolset_20260401"}],
    agents=[
        {"agent_id": reviewer.id, "name": "Code Reviewer"},
        {"agent_id": tester.id, "name": "Test Writer"}
    ]
)

The coordinator decides when and how to split work, collects results from the workers, and produces a unified report. Currently only a single level of delegation is supported, but the pattern already resembles an AI‑powered CI/CD pipeline.

Comparison with Other Anthropic Offerings

Anthropic’s agent‑related products can be positioned by how much infrastructure you want to manage:

Messages API : Full control over loops, tool usage, and containers – best for highly custom workflows.

Agent SDK : Provides tool execution and container handling while you host the runtime – suitable when you need mature tooling but want to run it yourself.

Managed Agents : You only supply prompts and tasks; the platform handles orchestration – ideal for backend automation such as PR review, code generation, or testing.

Claude Code CLI : Local interactive development with minimal setup – aimed at individual developers.

Claude Cowork : No technical responsibilities – targeted at non‑technical users.

Pricing Details

Managed Agents are billed in two dimensions: token usage (identical to regular Anthropic APIs) and runtime seconds.

Opus 4.6: $5 per M input tokens, $25 per M output tokens.

Sonnet 4.6: $3 per M input tokens, $15 per M output tokens.

Haiku 4.5: $1 per M input tokens, $5 per M output tokens.

Runtime: $0.08 per hour, measured to the millisecond; idle time is free.

Web‑search tool: $10 per 1,000 calls.

Prompt cache hits are charged at 0.1× the normal rate.

Example cost for a one‑hour Opus 4.6 coding job that consumes 50 K input tokens, 15 K output tokens, and runs for the full hour:

Input tokens: $0.25

Output tokens: $0.375

Runtime: $0.08

Total ≈ $0.705

What You Can Build

Automated PR Review : Attach a GitHub repo, let the agent read diffs, detect bugs, run tests, and post review comments.

Self‑Healing CI/CD : On pipeline failure, spin up an agent that analyses logs, writes a fix, and opens a new PR.

Documentation Generation : Have the agent read the codebase, execute examples, and produce up‑to‑date API docs or changelogs.

Data‑Pipeline Debugging : Deploy an agent that can inspect code, logs, and monitoring data to trace failures and suggest fixes.

Code Migration Assistant : Feed legacy code and target framework docs; the agent incrementally rewrites the project.

Getting Started

Installation works for all major languages:

# Python
pip install anthropic

# TypeScript
npm install @anthropic-ai/sdk

# CLI (macOS)
brew install anthropics/tap/ant

All requests must include the beta header managed-agents-2026-04-01. The SDK automatically adds it when you use client.beta.agents and related calls.

Some preview features (multi‑agent orchestration, memory, result management) require an access request via the official form.

Final Thoughts

Managed Agents represent Anthropic’s shift from merely exposing model capabilities to offering a full‑stack agent execution platform—much like the evolution from EC2 to Lambda in the cloud world. You no longer stitch together loops, tool calls, and environments; you simply define the task and let the platform handle the rest.