Claude Managed Agents Architecture: How Anthropic's Agent Platform Works Under the Hood
The Problem: Understanding What’s Under the Hood
When I first started working with Claude Managed Agents, I kept asking myself: “What exactly happens when an agent runs?” I’d configure my agent, set up tools, maybe add some memory—but the black box nature of it all frustrated me. How does Claude decide when to use a tool? What manages the execution loop? Where does the memory actually live?
If you’re building production agents, you can’t afford to treat the platform as magic. You need to understand the architecture to debug issues, optimize performance, and design agents that actually work reliably. So I dug into the documentation, ran experiments, and mapped out what’s really happening.
Here’s what I found.
The Architecture: Five Layers, One Coherent System
Claude Managed Agents isn’t just a model with some APIs bolted on. It’s a layered architecture where each component has a specific responsibility. Think of it like an operating system for AI agents:
┌─────────────────────────────────────────────────────────┐│ AGENT PLATFORM LAYER ││ (Scheduling, Monitoring, Coordination, Resource Mgmt) │├─────────────────────────────────────────────────────────┤│ ││ ┌─────────────────────────────────────────────────┐ ││ │ Layer 1: Claude Model (Reasoning Engine) │ ││ │ - Decision making │ ││ │ - Planning & reasoning │ ││ │ - Natural language understanding │ ││ └─────────────────────────────────────────────────┘ ││ ↓ ││ ┌─────────────────────────────────────────────────┐ ││ │ Layer 2: Agent Loop (Orchestration) │ ││ │ - Observe → Act → Verify cycle │ ││ │ - Iteration management │ ││ │ - State tracking │ ││ └─────────────────────────────────────────────────┘ ││ ↓ ││ ┌─────────────────────────────────────────────────┐ ││ │ Layer 3: Tools & Skills (Action Capabilities) │ ││ │ - API calls │ ││ │ - File operations │ ││ │ - Database queries │ ││ │ - Custom skills │ ││ └─────────────────────────────────────────────────┘ ││ ↓ ││ ┌─────────────────────────────────────────────────┐ ││ │ Layer 4: Memory (Persistent Context) │ ││ │ - Session persistence │ ││ │ - Long-term context storage │ ││ │ - Context window management │ ││ └─────────────────────────────────────────────────┘ ││ ↓ ││ ┌─────────────────────────────────────────────────┐ ││ │ Layer 5: Sandbox (Execution Environment) │ ││ │ - Security isolation │ ││ │ - Resource limits │ ││ │ - Controlled execution │ ││ └─────────────────────────────────────────────────┘ ││ │└─────────────────────────────────────────────────────────┘Each layer depends on the layers below it, and the platform layer wraps everything to provide OS-like services. Let me break down what each layer actually does.
Layer 1: The Claude Model (The Brain)
This is where the reasoning happens. When you configure a Managed Agent, you’re choosing which Claude model powers it:
# When you create an agent, this is what you're configuring at the model layeragent_config = { "model": "claude-sonnet-4-5", # The reasoning engine "system_prompt": "You are a helpful agent...", "capabilities": ["reasoning", "planning", "decision_making"]}The model layer is responsible for:
- Understanding goals: Parsing what you want the agent to accomplish
- Planning: Breaking down complex tasks into steps
- Decision making: Choosing which tools to use and when
- Reasoning: Understanding context and drawing conclusions
But here’s the key insight: the model doesn’t run in a vacuum. It’s embedded in a loop.
Layer 2: The Agent Loop (The Heartbeat)
This is where the “observe → act → verify” pattern lives. The agent loop is the orchestration engine that keeps the agent running:
┌────────────────────────────────────────────────────────┐│ AGENT LOOP ││ ││ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││ │ OBSERVE │───▶│ ACT │───▶│ VERIFY │ ││ └──────────┘ └──────────┘ └──────────┘ ││ ▲ │ ││ └─────────────────────────────────┘ ││ ││ Each iteration: ││ 1. Observe: Gather current state & context ││ 2. Act: Model decides and executes tool/action ││ 3. Verify: Check if goal achieved, continue if not │└────────────────────────────────────────────────────────┘When I ran my first agent, I imagined it was a single call to Claude. But what actually happens looks more like this:
# Conceptual representation of the agent loopclass AgentLoop: def __init__(self, model, tools, max_iterations=100): self.model = model self.tools = tools self.max_iterations = max_iterations
def execute(self, goal): iteration = 0 while iteration < self.max_iterations: # OBSERVE: Gather current state observation = self.observe_state()
# ACT: Model decides what to do decision = self.model.decide( goal=goal, observation=observation, tools_available=self.tools.available() )
# Execute the decided action action_result = self.execute_action(decision)
# VERIFY: Check if we're done if self.verify_completion(goal, action_result): return action_result
iteration += 1The loop continues until either:
- The goal is achieved (verified)
- Max iterations reached
- An error occurs
This loop is why agents can be autonomous—they don’t just respond once, they iterate toward a goal.
Layer 3: Tools & Skills (The Hands)
The model layer decides what to do, but the tools layer actually does it. Tools are the action capabilities that let agents interact with the world:
# Example tool configurationtools_config = [ # API calls { "type": "api_call", "name": "fetch_webpage", "permissions": ["https://*.example.com/*"], "rate_limit": 100 # requests per minute },
# File operations { "type": "file_operation", "permissions": { "read": ["/data/input/*"], "write": ["/data/output/*"] } },
# Database queries { "type": "database_query", "connection": "postgresql://...", "allowed_tables": ["public.documents", "public.users"] },
# Memory tool (beta feature) { "type": "memory_20250818", "name": "memory", "persistent": True }]The key insight here: tools are capabilities, not just functions. Each tool has:
- Permissions: What it’s allowed to access
- Constraints: Rate limits, resource limits
- Schemas: Expected inputs and outputs
When the model decides to use a tool, the platform layer handles the execution, checks permissions, and returns the result back to the loop.
Layer 4: Memory (The Long-Term Context)
This is where things get interesting. The memory layer (currently in beta) enables persistent context across sessions:
┌─────────────────────────────────────────────────────────┐│ MEMORY LAYER ││ ││ ┌─────────────────┐ ┌─────────────────────────┐ ││ │ Session Memory │ │ Persistent Memory │ ││ │ │ │ │ ││ │ - Current task │ │ - Cross-session context │ ││ │ - Recent tools │ │ - Learned preferences │ ││ │ - Immediate ctx │ │ - Long-term facts │ ││ └─────────────────┘ └─────────────────────────┘ ││ ││ Context Window Management: ││ - Automatic summarization when approaching limits ││ - Tool use retention policies ││ - Smart eviction of low-value context │└─────────────────────────────────────────────────────────┘The memory tool configuration looks like this:
memory_config = { "type": "memory_20250818", "name": "memory", "context_management": { # Control how context is managed "edits": [ { "type": "clear_tool_uses_20250919", "trigger": { "value": 100000 # Clear tool uses when 100k tokens used } } ] }}Why does this matter? Because without memory, every agent session starts from zero. With memory, your agent can:
- Remember user preferences across sessions
- Build on previous work
- Maintain consistency in long-running projects
Layer 5: Sandbox (The Security Boundary)
The sandbox layer is the security isolation that prevents agents from running wild. It’s what keeps a rogue agent from deleting your production database:
sandbox_config = { "isolation_level": "strict",
# What operations are allowed "allowed_operations": { "file_read": True, "file_write": False, # Read-only by default "network": ["https://api.example.com/*"], "subprocess": False },
# Resource limits "limits": { "memory_mb": 512, "cpu_seconds": 60, "file_size_mb": 10 },
# Timeout "execution_timeout_seconds": 300}The sandbox provides:
- Isolation: Agent code runs in a contained environment
- Resource limits: Prevents runaway resource consumption
- Permission enforcement: Tool calls are checked against allowed operations
- Audit trail: All actions are logged for review
The Platform Layer: The Operating System for Agents
All five layers are wrapped by the platform layer, which provides OS-like services:
┌─────────────────────────────────────────────────────────────────┐│ PLATFORM LAYER (Agent OS) ││ ││ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ││ │ Scheduling │ │ Monitoring │ │ Coordination │ ││ │ │ │ │ │ │ ││ │ - Job queues │ │ - Logging │ │ - Multi- │ ││ │ - Priorities │ │ - Metrics │ │ agent msg │ ││ │ - Retries │ │ - Alerts │ │ - Handoff │ ││ └──────────────┘ └──────────────┘ └──────────────┘ ││ ││ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ││ │ Memory │ │ Sandbox │ │ Tools │ ││ │ Management │ │ Management │ │ Registry │ ││ └──────────────┘ └──────────────┘ └──────────────┘ ││ │└─────────────────────────────────────────────────────────────────┘This is why it’s called a “managed” agent—the platform manages all the complexity. You configure the layers, and the platform handles:
- Scheduling: When agents run, in what order, with what priorities
- Monitoring: Logging, metrics, alerting on failures
- Coordination: Multi-agent communication and handoffs
- Resource management: Memory allocation, tool registry, sandbox lifecycle
Putting It All Together: A Complete Agent Configuration
Here’s what a fully configured Managed Agent looks like in practice:
managed_agent_config = { # Layer 1: Model "model": "claude-sonnet-4-5", "system_prompt": """You are a research agent. Your goal is to gather information from the web and synthesize it into a report.""",
# Layer 2: Agent Loop "agent_loop": { "pattern": "observe_act_verify", "max_iterations": 50, "timeout_seconds": 600 },
# Layer 3: Tools "tools": [ {"type": "web_fetch", "name": "fetch"}, {"type": "memory_20250818", "name": "memory"}, {"type": "file_operation", "name": "file_write", "permissions": {"write": ["/output/*"]}} ],
# Layer 4: Memory "memory": { "persistent": True, "context_management": { "edits": [ { "type": "clear_tool_uses_20250919", "trigger": {"value": 80000} } ] } },
# Layer 5: Sandbox "sandbox": { "isolation": "strict", "allowed_operations": { "network": ["https://*"], "file_write": True }, "limits": { "memory_mb": 1024, "timeout_seconds": 600 } }}Why Understanding Architecture Matters
When I started treating Managed Agents as a black box, I made predictable mistakes:
- Misconfigured tools: Not understanding the tools layer led to permission errors
- Context window issues: Not managing memory properly caused truncation
- Timeout failures: Not understanding loop iteration limits led to incomplete runs
Once I understood the layers, everything made sense:
- Debugging: I knew which layer to investigate for each type of failure
- Optimization: I could tune parameters at the right layer
- Design: I could architect agents that leveraged each layer’s strengths
Key Takeaways
-
Five layers, clear responsibilities: Model (reasoning), Loop (orchestration), Tools (actions), Memory (context), Sandbox (security)
-
The loop is the heartbeat: Agents aren’t single calls—they’re iterative observe-act-verify cycles
-
Memory enables persistence: Cross-session context is what makes agents feel intelligent over time
-
Sandbox is non-negotiable: Security isolation is built into the architecture, not bolted on
-
Platform manages complexity: The “Agent OS” handles scheduling, monitoring, and coordination
Understanding this architecture transformed how I build agents. Instead of cargo-culting configurations, I could reason about what each layer needed and why.
The next time your agent behaves unexpectedly, ask yourself: which layer is responsible? That question alone will save you hours of debugging.
Final Words + More Resources
My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me
Here are also the most important links from this article along with some further resources that will help you in this scope:
Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!
Comments