文档中心

火山方舟

Managed Agent

[进阶] 构建从 CSV 到交互式报告的数据分析 Agent

本教程演示如何使用方舟 Managed Agents 完成一次端到端的数据分析：上传一份 CSV 文件，由 Agent 在云沙箱中完成数据读取、清洗、统计、图表生成，并最终输出一份自包含的 HTML 分析报告。

场景说明

在企业的数据分析场景中，业务人员拿到 CSV 或 Excel 结构化数据后，往往只能看到原始记录，很难快速判断哪些信息值得关注。传统链路依赖分析师完成数据清洗、统计和可视化，响应周期长、重复性工作多。

这类场景适合交给 Managed Agents 处理：用户只需提供数据文件并描述分析目标，Agent 可以自动完成数据读取、清洗、代码执行、图表生成和结果总结，并输出一份结构清晰的分析报告。

环节	内容
输入	一个 CSV 文件，例如订单、销售、用户行为或运营数据
过程	Agent 读取文件，使用 pandas 分析数据，使用 plotly 生成交互图表
输出	一个自包含的 report.html，包含摘要、关键指标、图表和行动建议
观测	通过 Session Events SSE 查看 Agent 消息、工具调用和状态变化

你将完成什么

创建一个用于数据分析的 Environment。

创建一个可复用的数据分析 Agent。

上传 CSV 并挂载到 Session 沙箱。

发送分析任务并通过事件流观察执行过程。

查询 Session 产出的报告文件。

核心概念

动手前先厘清方舟 Managed Agents 的四个基础对象。

概念	说明
Agent	一份可版本化、可复用的配置模板，封装模型、System Prompt 和工具集。创建后得到稳定的 agent_id，可被任意 Session 引用
Environment	Agent 运行所在的云沙箱定义，决定网络策略与预装依赖，一次创建，多次复用
Session	一次具体的运行实例，把 Agent、Environment 和输入资源绑在一起。创建 Session 本身不会触发工作，需要主动下发消息
Event	Session 内的追加式事件流。客户端用 user.message 下发任务，再通过 SSE 实时收到 Agent 的消息、工具调用与状态变化

工作流程

前置条件

已开通方舟 Managed Agents 和目标模型服务。

方舟 API Key：已创建 API Key，详情请参见 API Key 管理。

本地已安装 curl 7.76.0 或更高版本，以及 jq。

准备一个 CSV 文件，例如 test_csv.csv。

将 API Key、Base URL 和常用配置配置为环境变量：

注意

API Key 用于访问账户下的模型与 Agent 资源，请仅在服务端使用，不要写入前端代码、日志或截图。

第 1 步：创建 Environment

Environment 定义 Agent 的执行环境，例如网络访问权限、预装依赖和运行配置。本示例提前安装 pandas 和 plotly，Agent 执行任务时可以直接读取 CSV 文件、生成图表，无需运行时再安装依赖。Environment 创建完成后可以长期复用，后续多个 Session 都可以基于同一个 Environment 运行。

说明

如果已经在控制台创建了包含 pandas 和 plotly 的 Environment，可以跳过本节，直接设置 ENVIRONMENT_ID。

说明

本示例未配置 config.tos，生成的报告使用方舟公共 TOS。需要将报告长期保存在自己的 TOS Bucket 时，在创建 Environment 时配置产物存储，详情请参见配置产物存储。

注意

networking.type=unrestricted 便于教程演示。生产环境应按最小可用范围收敛网络策略，只放行必要的出站主机。

第 2 步：定义分析 Agent

Environment 创建完成后，创建 Agent。Agent 包含模型、System Prompt 和工具等配置，是 Session 执行任务时使用的核心资源。System Prompt 用于约束 Agent 的分析流程和输出格式，例如数据校验、统计分析、图表生成以及最终报告的组织方式。创建完成后，Agent 可以被多个 Session 复用。

先把 System Prompt 保存为变量：

再创建 Agent，将上述 System Prompt 与工具一起提交：

第 3 步：上传待分析数据

上传输入文件有多种方式，本示例通过 Files API 上传 CSV 并获取 FILE_ID，后续创建 Session 时通过该 ID 引用文件。文件上传采用异步处理，需要等待文件状态变为 active 后再继续后续流程，以确保文件已完成处理并可以正常使用。

第 4 步：创建 Session 并挂载数据

Session 表示一次具体的运行实例，用于关联 Agent、Environment 和输入资源。创建 Session 时，通过 resources 指定需要挂载的文件，平台会将其映射到沙箱中的 /mnt/session/uploads/ 目录，供 Agent 在执行过程中访问。Session 创建完成后即进入就绪状态，但不会自动开始执行任务，需在后续发送事件触发执行。

第 5 步：建立事件流并下发分析任务

Session 创建完成后并不会自动执行任务。为了完整接收本轮事件，先建立 SSE 流并等待服务端返回 : ready，再向 /sessions/{session_id}/events 接口发送 user.message。以下函数会按该顺序编排，并持续读取到会话终态：

第 6 步：实时观测执行过程

第 5 步建立的 SSE 流会实时输出模型消息、工具调用和任务状态。run_session_turn 只有在收到 session.status_idle 且 stop_reason.type=end_turn，并且本轮至少产生一条 agent.message 时才返回成功。

如果 SSE 意外断开，函数会先建立替代流，再分页查询历史事件，补齐断线期间的事件并按事件 ID 去重。连续重连仍失败、Session 终止或服务端返回其他停止原因时，函数会返回非零状态，不会把不完整输出当作成功结果。

主要事件类型：

事件类型	含义
agent.message	Agent 返回的文本消息
agent.tool_use	Agent 正在调用工具
agent.tool_result	工具执行结果
session.status_idle	根据 stop_reason.type 判断本轮正常结束、等待操作或重试耗尽
session.status_terminated	Session 已终止，需要排查原因

第 7 步：取回分析报告

任务完成后，可以通过 Session ID（scope_id）查询本次执行生成的文件。Agent 运行过程中产生的报告、图表等文件都会关联到对应的 Session。当查询结果中出现生成的 HTML 文件时，说明分析报告已经生成。

生成的文件可以通过控制台下载到本地，方便查看、分享或归档。

第 8 步：清理资源

分析完成后，可根据需要清理本次运行产生的资源。Session 和上传文件属于临时资源，会占用平台配额，确认结果已保存后可及时删除。Agent 和 Environment 通常作为可复用资源保留，用于后续任务。再次执行分析时，只需创建新的 Session 并引用已有的 Agent、Environment 和输入文件即可。

警告

删除 Session 前，先确认所需文件的存储位置。使用方舟公共 TOS 时，删除 Session 会清理关联产物，需要提前下载；使用自己的 TOS Bucket 时，删除 Session 不会删除 Bucket 中的对象，你需要继续管理对象生命周期。

完整执行顺序

设置 ARK_API_KEY、ARK_BASE_URL、MODEL_ID、DATA_PATH 等环境变量。

创建或复用 Environment，确保包含 pandas 和 plotly。

创建 Agent。

上传 CSV。

创建 Session 并挂载 CSV。

建立事件流并等待 : ready。

发送 user.message，通过同一条事件流等待 session.status_idle 且 stop_reason.type=end_turn。

按 scope_id 查询 Session 产物。

下载生成文件到本地。

按需清理 Session、输入文件与 Environment。

最近更新时间：2026.10.28 19:53:17

这个页面对您有帮助吗？

有用

无用