本文的整体技术路线如下流程图所示：

 

  
下载生成文件：Python脚本、JSON汇总、Excel报告
 

摘要

本文探讨如何基于Anthropic Python SDK构建Claude Managed Agent智能体，实现对销售数据的全流程自动化分析。文章回答了以下核心问题：(1)Claude Managed Agent的架构组成与运行机制是什么；(2)如何使用Python SDK配置云端沙箱环境并上传数据文件；(3)如何通过事件流实时监控智能体的工具调用与执行状态；(4)如何将智能体生成的Python脚本、JSON汇总文件和Excel报告自动下载到本地。本文提供的方案覆盖从智能体创建到资源清理的完整生命周期，适用于需要多步骤自动化执行的各类数据分析任务。

Abstract

This article explores how to build a Claude Managed Agent using Anthropic’s Python SDK for end-to-end automated sales data analysis. It addresses the following core questions: (1) The architectural components and operational mechanism of Claude Managed Agents; (2) How to configure a cloud sandbox environment and upload data files via the Python SDK; (3) How to monitor agent tool calls and execution status in real-time through event streaming; (4) How to automatically download Python scripts, JSON summaries, and Excel reports generated by the agent. The solution covers the complete lifecycle from agent creation to resource cleanup, suitable for various multi-step automated execution tasks in data analysis.

Managed Agent智能体核心架构

在动手实现之前，有必要先理解Claude Managed Agent的架构设计。这好比一位项目经理统筹团队工作（行业术语：任务编排引擎），而非每位成员各自独立响应问题。Claude Managed Agent由四个核心部分构成：

智能体（Agent）

可复用的配置单元，包含模型选择（如claude-sonnet-5）、系统提示词、工具集和技能（Skills）。一次创建后可在多个会话中复用，无需重复配置。系统提示词定义了智能体的角色和行为边界。

环境（Environment）

智能体的执行场所，支持两种类型：Anthropic提供的云端沙箱，以及用户自建的托管沙箱。本文使用云端沙箱方案，它为智能体提供了隔离的工作空间，可安全地读取挂载文件、执行代码和运行命令。

会话（Session）

智能体的运行实例，连接了智能体配置、执行环境和任务所需资源（如数据文件）。一次会话对应一个具体任务的完整执行周期。会话在智能体完成所有工作后进入空闲状态。

事件（Events）

会话执行过程中交换的消息、工具调用、执行结果和状态变更记录。完整的事件历史为任务追溯、审计和结果验证提供了详细依据。

答辩高频提问：Managed Agent与传统API调用模式的核心区别是什么？——标准答案：传统模式下开发者需自行实现”发送提示→等待响应→解析工具调用→执行→回传结果”的循环逻辑；而Managed Agent将这些环节交由Anthropic托管，开发者只需定义智能体配置和任务目标，由其自主完成多步骤编排，显著降低开发复杂度和维护成本。

环境准备与SDK集成

前置条件

执行本文方案需要Python 3.12以上版本、Anthropic Console账号以及至少5美金的API额度。API密钥需存储为ANTHROPIC_API_KEY环境变量，避免直接写入代码。

对于Windows环境，在PowerShell中执行：

$env:ANTHROPIC_API_KEY="your-api-key-here"

第一轮对话：基础智能体创建与环境搭建

我需要在Anthropic平台上构建一个托管智能体来执行数据分析任务。请帮我完成基础配置：安装anthropic Python SDK，从环境变量读取API密钥，初始化客户端并启用Managed Agents的Beta功能。同时创建一个资源追踪字典来记录后续创建的所有资源ID，方便最后清理。请先列出完整的操作步骤，再生成代码。

首先安装官方Python SDK：

%pip install -q --upgrade anthropic

接下来从环境变量加载API密钥并初始化客户端。将密钥置于代码外部比直接硬编码更安全，尤其在项目共享或推送至代码仓库时：

from anthropic import Anthropic
secret_key = os.environ.get("ANTHROPIC_API_KEY")
assert secret_key, "请在环境变量或本地.env文件中设置ANTHROPIC_API_KEY"

Managed Agent当前通过Anthropic的Beta API提供，managed-agents-2026-04-01 Beta标识用于启用该功能。官方SDK会自动为Managed Agents请求附加所需的Beta请求头，但后续列举和下载会话文件时也需要此标识：

BETA_VERSION = "managed-agents-2026-04-01"
ai_client = Anthropic(api_key=secret_key)

创建资源追踪字典，用于存储所有后续创建的资源ID。此设计确保即使某个步骤执行失败，清理环节仍能定位并移除已创建的资源：

print("✓ Anthropic客户端初始化完成")

创建Managed Agent智能体

第二轮对话：智能体与沙箱环境创建

基础环境已就绪。现在请帮我创建一个名为”销售数据分析智能体”的Managed Agent，使用claude-sonnet-5模型。系统提示应当指导它像一个细致的数据分析师那样工作：始终先检查/workspace目录下的挂载文件，用代码执行工具进行量化分析，汇总结果保存至/mnt/session/outputs。请为其配备agent_toolset工具集和xlsx技能。另外，创建一个网络受限的云端沙箱执行环境。注意所有变量名和资源标识符要与第一步的追踪字典匹配。

# 创建Managed Agent智能体，定义模型、行为规范和技能
data_agent = ai_client.beta.agents.create(
    "你是一名细致的数据分析师。在处理数据请求时，始终先读取 "
    "挂载在/workspace目录下的文件，使用代码执行工具进行量化分析，"
    "输出简洁的数值结果。使用XLSX技能处理电子表格相关工作。"
    "将最终成果保存到/mnt/session/outputs目录。"
    # 此处省略了工具集详细类型声明和技能的具体配置参数，完整代码请在文末获取
    {"type": "agent_toolset_20260401"},
    {"type": "anthropic", "skill_id": "xlsx"},
)
resource_ids["agent_id"] = data_agent.id
print(f"✓ 智能体已创建: {data_agent.id}")

agent_toolset_20260401工具集赋予智能体在会话中调用Anthropic内置工具的能力，而xlsx技能为电子表格的创建和分析提供任务专属指引。Anthropic还提供了针对PPT文稿、Word文档和PDF工作流的预制技能。

知识延伸：从架构层面看，工具集和技能扮演不同角色。工具集属于能力层——好比给智能体配备了扳手和螺丝刀（行业术语：执行原语）；技能属于知识层——相当于附赠了一本操作手册（行业术语：领域知识注入）。两者协同，使智能体既能执行操作，又懂得如何正确地执行。

配置云端沙箱执行环境

执行环境是智能体运行的安全沙箱，为智能体提供了独立的工作空间来读取挂载文件、执行代码和运行命令。本文采用Anthropic云端环境，网络模式设置为受限：

sandbox_env = ai_client.beta.environments.create(
    "networking": {"type": "limited"},
)
resource_ids["env_id"] = sandbox_env.id
print(f"✓ 云沙箱环境已创建: {sandbox_env.id}")

答辩高频提问：云端沙箱的”受限网络”模式具体限制了哪些能力？——标准答案：受限模式下，智能体无法主动发起外部网络请求（如调用第三方API、访问外部数据库），但可通过挂载的文件资源读取数据。此设计在保证代码执行灵活性的同时，有效防范数据泄露和未授权外部访问风险。

输出示例：

✓ 云沙箱环境已创建: env_01FzWACEf9UJDL65ovBPA1zf

数据文件上传与完整性验证

在执行分析任务之前，需要将本地销售数据文件上传至Anthropic的Files API，以便后续挂载到沙箱环境中供智能体读取。

本文使用的示例数据集sales_data.csv包含12行月度销售记录。上传前先验证文件存在性和数据行数：

data_file = Path("sales_data.csv")
assert data_file.exists(), f"输入文件缺失: {data_file.resolve()}"
line_count = sum(1 for _ in data_file.open(encoding="utf-8")) - 1
assert line_count == 12, f"预期12行数据，实际发现{line_count}行"
uploaded_file = ai_client.beta.files.upload(file=data_file)
resource_ids["file_id"] = uploaded_file.id
print(f"✓ 文件已上传 {data_file}: {uploaded_file.id} ({line_count}行)")

执行后输出类似：

✓ 文件已上传 sales_data.csv: file_011Cch3EubJkswPdo3gMBvM2 (12行)

创建执行会话并挂载数据

会话是连接智能体、执行环境和资源的桥梁。此处将上传的CSV文件挂载至沙箱内的/workspace/sales_data.csv路径：

work_session = ai_client.beta.sessions.create(
    environment_id=sandbox_env.id,
    "file_id": uploaded_file.id,
    "mount_path": "/workspace/sales_data.csv",
)
resource_ids["session_id"] = work_session.id
print(f"✓ 执行会话已创建: {work_session.id}")

创建会话后智能体并不会立即开始工作——它需要收到user.message事件后才激活任务执行。

流式监控智能体任务执行

第三轮对话：任务执行与结果下载

会话和文件都已准备好。现在请帮我向智能体发送一个分析任务，要求它：(1)读取/workspace/sales_data.csv；(2)编写Python分析脚本并执行；(3)生成JSON格式的汇总数据；(4)创建包含原始数据、月度利润和汇总表的Excel报告。需要通过事件流实时监控智能体的工作进度，显示它调用了哪些工具、输出了什么内容。任务完成后请列出会话的历史事件，并将生成的所有文件下载到本地outputs目录。

以下代码启动事件流监听，发送任务消息，并实时展示智能体的工作过程。智能体在执行期间会自主调用read、bash、write、edit等工具来完成任务：

执行过程中可以看到智能体依次调用各类工具（如read读取技能说明、bash运行脚本、write创建文件、edit修正问题），逐步完成从数据读取到报告生成的完整流水线。当智能体完成全部工作后，会话通过session.status_idle事件通知外部监听方，此时可以安全地停止事件流监听。

上图展示了智能体在执行销售数据分析时的流式输出效果，包含了Python脚本的编写过程、代码执行反馈以及最终结果的文本总结。

检索会话事件历史与下载生成文件

任务完成后，可以查看会话的完整事件历史记录并将其下载到本地：

event_history = ai_client.beta.sessions.events.list(work_session.id, order="asc")
print("--- 会话事件历史记录 ---")
for evt in event_history.data:

事件历史覆盖了从会话创建到任务完成的全过程，为后续审查提供了完整的追溯链条。

接下来下载智能体生成的所有文件：

os.makedirs("outputs", exist_ok=True)
file_content = ai_client.beta.files.download(fobj.id, betas=[BETA_VERSION])
save_path = os.path.join("outputs", fobj.filename)
file_content.write_to_file(save_path)
local_outputs.append(save_path)
print(f" 已下载 {fobj.id} -> {save_path}")
print(f" 跳过 {fobj.id}: {err}")

最后验证所有预期文件是否均已成功下载。

生成结果详细分析

智能体生成的三份输出文件各自承担不同角色，形成从代码、数据到报表的完整输出链路：

智能体在执行中不仅生成了这些文件，还通过LibreOffice对Excel工作簿进行了公式重算和循环引用检查，确保输出结果的可靠性。

上图为智能体生成的分析脚本，包含数据加载、指标计算和输出写入的完整流程，代码可在本地独立运行。

JSON汇总文件以结构化格式存储了分析结果，便于程序化消费和自动化流程对接。

Excel报告以可视化方式呈现月度数据，包含营收、成本、利润、利润率、汇总值和图表。

分析结果数据汇总

针对sales_data.csv中的12条月度记录，验证结果如下：

• 总营收：32,900
• 总成本：14,750
• 总利润：18,150
• 月均利润：1,512.50
• 最优月份：12月（利润2,550）
• 最差月份：1月（利润400）

Managed Agent与传统API调用方式对比

资源清理

Managed Agent相关资源会持续存在直到显式删除，因此任务完成后及时清理尤为重要。活跃的会话和环境若长期闲置将产生不必要的API费用。

会话必须处于空闲状态方可删除。以下清理代码逐一移除会话、文件、环境，并归档智能体。每个操作均包裹在辅助函数中，确保单个步骤失败不会阻断后续清理：

def cleanup_resource(label, cleanup_func):
    print(f"· 无法删除 {label}: {err}")
    if resource_ids["session_id"]:
cleanup_resource("会话", lambda: ai_client.beta.sessions.delete(resource_ids["session_id"]))
    if resource_ids["file_id"]:
cleanup_resource("上传文件", lambda: ai_client.beta.files.delete(resource_ids["file_id"]))
    if resource_ids["env_id"]:
cleanup_resource("云沙箱环境", lambda: ai_client.beta.environments.delete(resource_ids["env_id"]))
    if resource_ids["agent_id"]:
cleanup_resource("智能体(已归档)", lambda: ai_client.beta.agents.archive(resource_ids["agent_id"]))
    print("\n🎉 资源清理完毕，智能体已归档，其余资源已删除")

执行后输出：

✓ 会话已删除: session_01FzWBoBhzQbPhv8dGr3mpcd
✓ 上传文件已删除: file_011Cch3EubJkswPdo3gMBvM2
✓ 云沙箱环境已删除: env_01FzWACEf9UJDL65ovBPA1zf
✓ 智能体(已归档): agent_01FzW3g3mgb2b5WW4T8K3wHd
🎉 资源清理完毕，智能体已归档，其余资源已删除

总结

核心问题与解决方案

• 问题一：如何构建一个能够自主完成多步骤数据分析任务的AI智能体？

• 解决方案： 利用Anthropic Managed Agent框架，通过声明式配置定义智能体的模型、系统提示词、工具集和技能，使其在收到任务后自主完成从数据读取、代码编写、脚本执行到报告生成的完整流水线，无需开发者编写循环逻辑。

• 问题二：智能体如何在安全受控的环境中执行任意代码？

• 解决方案： 通过云端沙箱环境提供隔离的执行空间，网络模式设置为受限以防止数据外泄。智能体仅能访问挂载的文件资源和沙箱内的工具，无法主动发起外部网络请求。

• 问题三：如何确保智能体生成的结果可靠且可复现？

• 解决方案： 会话的完整事件历史提供了详细的追溯记录；生成的Python脚本可独立运行以验证结果；Excel报告采用公式驱动而非硬编码数值，经LibreOffice重算校验。

技术创新与业务价值

1. 自动化闭环：从数据上传、任务指派到结果下载和资源清理，实现了无需人工介入的完整自动化闭环，大幅提升分析效率
2. 声明式配置：智能体的能力和行为通过声明式配置定义（模型、工具集、技能），可复用、可版本化，降低重复开发成本
3. 安全隔离执行：云端沙箱结合受限网络策略，在保证代码执行灵活性的同时确保数据安全
4. 全链路可追溯：事件流和会话历史提供了从用户请求到最终输出的完整审计链

本文的实践表明，对于12行销售数据的一次完整分析流程，Managed Agent能以约0.25美元的成本完成代码编写、执行、纠错和报告生成的全过程。对于更大规模的数据分析任务，通过合理配置智能体的工具和技能组合，可进一步发挥其在自动化分析场景中的价值。

答辩高频提问：在实际应用中，Managed Agent与传统脚本定时任务的本质区别是什么？——标准答案：传统脚本任务的逻辑是”固定流程、固定输入”，而Managed Agent具有”自适应决策”能力：它可以先读取数据评估结构，再决定采用何种分析策略，经代码执行后发现异常时自行修正，这种闭环推理—执行—验证的模式是传统脚本无法实现的。

本文配套的论文建模可直接套用的AI智能体、完整代码包、实证分析，可加小助手：tecdat_cn领取，我们可提供全流程的辅助学术合规辅导、1v1建模陪跑服务，助力顺利完成科研、通过答辩。

作者系机器学习与数据分析领域分析师，拥有多年数据挖掘与AI智能体开发经验。