Claude Managed Agents Overview: Three-Layer Architecture of Sessions / Agents / Environments APIs

Chapter 29: Managed Agents Overview: Projects, Artifacts, and Agent Lifecycle

29.1 What Are Managed Agents?

In Anthropic's product architecture, Managed Agents refers to agent instances that run on the Claude.ai platform, with the platform itself handling all infrastructure concerns. Unlike API-based agents — where developers must provision servers, manage databases, implement session state, and handle scaling — Managed Agents abstract all of that away. Teams interact with the agent through a managed interface and focus entirely on business logic.

The defining characteristics of Managed Agents:

1. Platform-hosted infrastructure — Session persistence, memory storage, and tool execution environments are managed by Claude.ai, not the developer
2. Projects integration — Agents can be associated with Projects, gaining persistent knowledge bases and persistent custom instructions
3. Artifacts generation — Agents produce interactive, renderable outputs: code, charts, web pages, diagrams
4. Built-in lifecycle management — Pause, resume, version history, and sharing are handled at the platform layer

Managed Agents vs API Agents

29.2 Projects: Persistent Agent Workspaces

Projects are the most important feature in Claude.ai's Managed Agents offering. They elevate single conversations into persistent, specialized workspaces with durable memory across sessions.

Anatomy of a Project

┌──────────────────────────────────────────────┐
│                   Project                     │
│                                              │
│  ┌─────────────────┐  ┌───────────────────┐  │
│  │  Knowledge Base  │  │ Custom Instructions│  │
│  │  (RAG-indexed   │  │ (System prompt     │  │
│  │   documents)    │  │  extension)        │  │
│  └─────────────────┘  └───────────────────┘  │
│                                              │
│  ┌────────────────────────────────────────┐  │
│  │        Conversation History            │  │
│  │  (All conversations within Project)    │  │
│  └────────────────────────────────────────┘  │
│                                              │
│  ┌──────────────┐  ┌───────────────────────┐ │
│  │   Artifacts   │  │   Built-in Tools      │ │
│  │   (Outputs)   │  │   (Search, Code exec) │ │
│  └──────────────┘  └───────────────────────┘ │
└──────────────────────────────────────────────┘

Knowledge Base

The Project knowledge base allows uploading and indexing documents that Claude can access across all conversations within that Project.

Supported file types:

• Text: .txt, .md, .csv
• Documents: .pdf, .docx
• Code: .py, .js, .ts, .go, and many more
• Data: .json, .yaml

How it works under the hood:

When a file is uploaded, Claude.ai automatically handles the full RAG pipeline:

1. Document parsing (text extraction)
2. Semantic chunking
3. Embedding vector generation
4. Vector index construction

During conversations, Claude retrieves the most relevant document chunks based on the user's message and injects them into context — this is the platform-managed RAG system described in Chapter 28, but with zero engineering effort from the user.

Knowledge base curation principles:

Recommended content:
├── Core reference documents (high retrieval frequency)
│   ├── API documentation
│   ├── Technical specifications
│   └── System architecture documents
├── Examples and patterns (provide reference models)
│   ├── Code templates
│   └── Worked examples
└── Background materials (provide context)
    ├── Team conventions
    └── Project history and decisions

Avoid:
├── Very large files (>10MB per file degrades chunking quality)
├── Highly repetitive content (dilutes retrieval precision)
└── Sensitive data (passwords, keys, personal information)

Custom Instructions

Custom Instructions are a Project-scoped system prompt extension, automatically prepended to every conversation in the Project.

Example — Code Review Project:

## Your Role
You are a senior Python backend code reviewer with deep expertise in
FastAPI, PostgreSQL, and microservices architecture.

## Review Standards
For every code submission, you must check:
1. **Security**: SQL injection, auth bypass, sensitive data exposure
2. **Performance**: N+1 queries, synchronous blocking I/O, resource leaks
3. **Code quality**: Functions >50 lines need refactor suggestions; snake_case naming
4. **Test coverage**: Critical paths must have corresponding unit tests

## Output Format
For each issue:

[SEVERITY] filename:line_number Problem description Recommended fix

Severity: CRITICAL (must fix) / HIGH (strongly recommended) / MEDIUM (suggested) / LOW (optional)

## Team Context
Team uses Python 3.11+, PEP 8, pytest for testing.
No print() for logging — must use structlog.
All database queries must use parameterized statements.

The power of Custom Instructions is that they encode institutional knowledge — team conventions, quality standards, domain context — that would otherwise require repetitive prompting in every conversation.

29.3 Artifacts: Interactive Output Artifacts

Artifacts are Claude.ai's signature differentiating capability. Rather than generating only text, Claude can produce renderable, interactive, deployable outputs that users can preview, modify, and use directly.

Artifact Types

Code Artifacts

• Trigger: Request for standalone, runnable code
• Display: Syntax-highlighted code editor view
• Languages: Python, JavaScript, TypeScript, SQL, Shell, and more
• Special capability: Some code types execute in a browser sandbox

SVG Artifacts

• Trigger: Request for vector graphics, icons, or diagrams
• Display: Live-rendered vector graphic
• Use cases: Architecture diagrams, flowcharts, brand sketches, data visualizations

HTML Artifacts

• Trigger: Request for a complete, runnable web page
• Display: Inline browser preview with full interactivity
• Capabilities: Full HTML/CSS/JavaScript, external CDN access (Bootstrap, Chart.js), animations, forms, local state

React Artifacts

• Trigger: Request for interactive React components
• Display: Real-time compiled and rendered React component
• Available libraries: shadcn/ui, lucide-react, Recharts, and other pre-installed packages
• Use cases: Dashboards, form components, interactive charts, small utility apps

Mermaid Artifacts

• Trigger: Request for flowcharts, sequence diagrams, ER diagrams
• Display: Live-rendered diagram
• Supported types:
  • flowchart — process flows
  • sequenceDiagram — system interaction sequences
  • erDiagram — database schemas
  • gantt — project timelines
  • classDiagram — OOP structures
  • mindmap — concept maps

Markdown Artifacts

• Trigger: Long-form documents, reports, specifications
• Display: Rendered rich text
• Distinction from chat: Markdown Artifacts can be independently saved, exported, and versioned

Artifact Lifecycle

Create → Preview → Iterate → Version History → Export/Deploy
  ↑                    │
  └────────────────────┘ (Multiple revision cycles)

Claude.ai maintains full version history for Artifacts. Users can inspect any prior version or roll back to an earlier state — a critical feature when iterating on complex outputs.

29.4 Agent Lifecycle

Conversation Lifecycle

Initialize
  │
  ├─ Load Project config (Custom Instructions + Knowledge Base)
  │
  ├─ Active
  │   ├─ User message → RAG retrieval → Context assembly → Inference → Response
  │   ├─ Artifact creation and versioning
  │   └─ Tool execution (code, search, file access)
  │
  ├─ Archived
  │   └─ History preserved; can be reactivated
  │
  └─ Deleted
      └─ Permanent removal

Memory Model Within Projects

Projects implement a three-tier memory model:

Notably, memory does not automatically transfer between separate conversations within a Project. If a user discusses a decision in Conversation A, Claude will not know about it in Conversation B unless the relevant information is in the Knowledge Base or Custom Instructions. This is a key architectural distinction from a Memory Tool-enabled API agent.

29.5 Built-In Tools

Managed Agents have access to platform-provided tools without any implementation work.

Web Search

Claude can proactively search the internet for real-time information:

• Triggers when: user asks about recent events, live data, or information requiring verification
• Sources: public web pages, news outlets
• Limitation: cannot access content behind login walls

Python Sandbox (Code Execution)

Claude can execute Python code in a secure sandbox environment:

Sandbox characteristics:
- Python 3.x runtime
- Pre-installed: numpy, pandas, matplotlib, scikit-learn, and others
- Isolated filesystem (no host access)
- Limited network access
- Execution timeout enforced

Typical uses: data analysis, chart generation, mathematical verification, data transformation.

File Processing

Within supported features, Claude can read content from files uploaded to the Project Knowledge Base and generate exportable files within Artifacts.

29.6 When to Use Managed Agents vs API Agents

Managed Agents are the right choice when:

• Building a team knowledge assistant (technical docs, company standards)
• Code review and analysis workflows
• Report generation and data analysis
• Rapid prototyping and MVP validation
• Individual productivity tooling

API Agents are required when:

• Integrating with private systems (internal databases, enterprise ERP, proprietary APIs)
• Custom tool definitions are needed (call internal services)
• Complex multi-agent orchestration is required
• Real-time data stream processing is involved
• Data compliance requires information never leaving the corporate network (GDPR, HIPAA, national data sovereignty laws)

Summary

Managed Agents represent Anthropic's answer to the question: "How do I get powerful agent capabilities without the engineering overhead?" Through Projects (knowledge base + custom instructions), Artifacts (interactive outputs), and platform-provided tools, Claude.ai abstracts the complex infrastructure work of building production agents.

Key concepts:

• Projects = Persistent workspaces with knowledge base, instructions, and conversation history
• Artifacts = Code, SVG, HTML, React, Mermaid — interactive, versionable outputs
• Built-in tools = Web search, Python execution, file handling
• Lifecycle = Conversation-scoped, with project-level knowledge persistence

The next chapter provides a deep dive into using Claude Projects effectively: knowledge base architecture, Custom Instructions design patterns, and team collaboration workflows.