Building a Data Analyst Agent with Claude Managed Agents and File Mounting

Claude Managed Agents allow you to deploy reusable, sandboxed LLM analysts that process files mounted via the Files API, ensuring raw data never reaches the inference endpoint while maintaining full filesystem access for complex computations.

The anthropics/claude-cookbooks repository demonstrates how to build a production-grade data analyst agent using Claude Managed Agents and secure file mounting. This architecture isolates sensitive datasets inside containerized environments while leveraging Claude's reasoning capabilities to generate reports, visualizations, and statistical analyses.

Architecture of Claude Managed Agents

Claude Managed Agents consist of three tightly coupled components that separate configuration from execution context. According to the implementation in managed_agents/data_analyst_agent.ipynb, this architecture enables versioned, reusable analytics workflows.

Agent Definition

The agent definition is a JSON configuration specifying the model, version, system prompt, and available tools. In managed_agents/data_analyst_agent.ipynb at line 208, the data analyst agent is created once and subsequently referenced by its id and version in every session. This immutable definition ensures consistent behavior across multiple analysis runs.

Environment

The environment encapsulates static resources including the Docker image, tool definitions, and secrets. The notebook re-uses the same managed-agent environment for all runs; only session-specific files change between executions. This separation allows teams to maintain a single Python runtime or custom library set across diverse analysis tasks.

Session

The session binds an agent definition to a concrete environment and handles resource mounting. At line 235 of managed_agents/data_analyst_agent.ipynb, the session creation includes resources=[{"type":"file","file_id":dataset.id,"mount_path":MOUNT_PATH}], which attaches the CSV dataset to a fixed path inside the container while streaming execution events back to the notebook.

How File Mounting Works in Managed Sessions

When you start a session, the Files API places any resources entries under /mnt/session/uploads/<mount_path> as read-only volumes. The agent can copy these files to writable locations at /mnt/user or /tmp before processing, then write final outputs to /mnt/session/outputs/ for later retrieval.

This design achieves two critical goals: the sandbox remains isolated from the host system, and the raw CSV bytes never travel to Claude's inference endpoint, minimizing token usage and preserving data privacy.

Step-by-Step Implementation Walkthrough

The managed_agents/data_analyst_agent.ipynb notebook implements the complete data analyst workflow through four distinct phases.

1. Upload the Dataset via the Files API

First, upload your dataset to obtain a persistent file_id. This identifier references the data without exposing its contents in API calls.

2. Create a Session with Mounted Resources

Construct a session that mounts the uploaded file at a specific container path. The mount path must align with the read-only uploads directory structure.

3. Execute the Analysis with Contextual Prompts

The agent receives a system prompt defined at line 383 of the notebook: "You are a senior data analyst..." The user question explicitly references the mounted path (/mnt/session/uploads/data.csv), allowing the agent to locate and load the data using Python tools inside the sandbox.

4. Retrieve Output Artifacts

After processing, the agent writes reports (HTML, CSV, or images) to the outputs directory. Your application can then download these files from the session with full audit trails.

Code Example: Creating a Data Analysis Session

This Python implementation mirrors the production pattern found in managed_agents/data_analyst_agent.ipynb, demonstrating file upload, session creation with mounting, message passing, and output retrieval:

# 1️⃣ Upload a CSV and get a file ID

uploaded = client.files.upload(file=open("sales.csv", "rb"))
MOUNT_PATH = "/mnt/session/uploads/data.csv"

# 2️⃣ Build the session with the mounted file

session = client.sessions.create(
    agent={"type": "agent", "id": ANALYST_AGENT_ID, "version": "2024-09-01"},
    resources=[{"type": "file", "file_id": uploaded.id, "mount_path": MOUNT_PATH}],
)

# 3️⃣ Send the analyst prompt (the notebook does this automatically)

question = """
Please analyze the sales data and produce a short report.
The data is mounted at /mnt/session/uploads/data.csv
"""
client.sessions.send_message(session.id, {"role": "user", "content": question})

# 4️⃣ Stream events and capture the HTML report once the agent finishes

for event in client.sessions.stream(session.id):
    if event.type == "assistant.message":
        report_url = event.content["attachments"][0]["url"]
        html = client.files.download(report_url).text
        display(HTML(html))

Advanced Mounting: GitHub Repositories and Beyond

File mounting extends beyond individual CSVs to complex data structures. The managed_agents/CMA_orchestrate_issue_to_pr.ipynb notebook at line 220 demonstrates mounting an entire GitHub repository using the github_repository resource type:

resources = [
    {
        "type": "github_repository",
        "repo_url": "https://github.com/example/project",
        "mount_path": "/workspace/project",
    }
]
session = client.sessions.create(agent=..., resources=resources)

This pattern supports any file type—CSV, JSON, PDFs, or codebases—enabling the agent to perform cross-file analysis within a single containerized environment.

Reusability and Versioning Patterns

The managed agent architecture emphasizes versioned immutability and resource sharing:

• Agent definitions are versioned, allowing you to iterate on prompts or tool sets without breaking existing sessions
• Environments can be shared across many agents, standardizing the Python runtime and custom libraries
• Mount paths remain consistent across session types, simplifying the transition from development notebooks to production pipelines

The managed_agents/slack_data_bot.ipynb notebook illustrates this reusability by re-uploading CSVs, mounting them dynamically, and injecting mount paths into user questions using the same architectural pattern.

Summary

• Claude Managed Agents separate agent definitions, environments, and sessions to create reusable, isolated analytics workflows
• File mounting occurs via the resources parameter in client.sessions.create(), placing files at read-only paths under /mnt/session/uploads/
• Raw data privacy is preserved because datasets never reach Claude's inference endpoint; only the file ID and mount path are transmitted
• Output retrieval happens through /mnt/session/outputs/, with the agent writing reports that you download via the Files API
• Repository mounting supports github_repository resources for analyzing entire codebases, as demonstrated in managed_agents/CMA_orchestrate_issue_to_pr.ipynb

Frequently Asked Questions

What is the difference between a Managed Agent and a regular Claude API call?

A Managed Agent runs inside a sandboxed container with its own filesystem, tools, and environment variables, whereas a standard Claude API call processes text in a stateless request. Managed Agents maintain session state, can write files to disk, and execute code against mounted data sources without exposing raw bytes to the inference API.

Where are mounted files stored inside the managed container?

Mounted files appear at /mnt/session/uploads/<mount_path> as read-only volumes. The agent can copy these to writable directories at /mnt/user or /tmp for processing, and must write final outputs to /mnt/session/outputs/ for the host application to retrieve.

Can I write files back from the agent to my local system?

Yes, but indirectly. The agent writes to /mnt/session/outputs/ inside the container. Your application then uses the Files API to download these artifacts from the session. This two-step process maintains sandbox security while enabling data export.

How do I mount an entire code repository instead of individual files?

Use the github_repository resource type in your resources array, as shown in managed_agents/CMA_orchestrate_issue_to_pr.ipynb at line 220. Specify the repository URL and desired mount path (e.g., /workspace/project), and the system clones the repo into the session container before the agent starts executing.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}