本教程演示如何使用方舟 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 的消息、工具调用与状态变化 | # 工作流程 ![图片](https://arkdocs.tos-cn-beijing.volces.com/flowcharts/tutorials/new-202607241201.svg) # 前置条件 * 已开通方舟 Managed Agents 和目标模型服务。 * 已创建 API Key，详情请参见 [API Key 管理](https://docs.volcengine.com/docs/88760/2647722)。 * 本地已安装 `curl` 和 `jq`。 * 准备一个 CSV 文件，例如 `test_csv.csv`。将 API Key、Base URL 和常用配置配置为环境变量： ```Bash export ARK_API_KEY="你的方舟 API Key" export ARK_BASE_URL="https://ark.cn-beijing.volces.com/api/v3" export MODEL_ID="doubao-seed-2-1-pro-260628" export TOOLSET_TYPE="agent_toolset_20260701" export DATA_PATH="./test_csv.csv" ```

注意

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

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

说明

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

```Bash environment=$(curl -sS --fail-with-body "$ARK_BASE_URL/environments" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d @- <<'EOF' { "name": "data-analyst-env", "description": "用于 CSV 数据分析报告生成的托管沙箱环境。", "config": { "type": "cloud", "networking": {"type": "unrestricted"}, "packages": { "pip": ["pandas", "plotly"] } } } EOF ) ENVIRONMENT_ID=$(jq -er '.id' <<<"$environment") echo "Environment: $ENVIRONMENT_ID" ```

注意

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

# 第 2 步：定义分析 Agent Environment 创建完成后，创建 Agent。Agent 包含模型、System Prompt 和工具等配置，是 Session 执行任务时使用的核心资源。System Prompt 用于约束 Agent 的分析流程和输出格式，例如数据校验、统计分析、图表生成以及最终报告的组织方式。创建完成后，Agent 可以被多个 Session 复用。先把 System Prompt 保存为变量： ```Bash ANALYST_SYSTEM_PROMPT='你是一名资深数据分析师，负责把 CSV 数据集转成可直接交付的 HTML 分析报告。工作目标：输出一份面向业务方可直接阅读的报告。报告应包含摘要、关键指标、图表、主要发现、数据质量说明和行动建议。工作原则： 1. 先读取并理解原始 CSV 的结构，再开始分析。必须明确区分"原始输入字段"和"分析过程中派生出的字段"。 2. 所有关于数据规模、行列数、字段名、缺失值、重复值的描述，都必须基于原始 CSV，不得基于清洗后或派生后的 dataframe。 3. 大表先抽样查看，再按需全量聚合，避免无意义地打印整表。 4. 所有结论必须由具体数字支撑；不能只给判断，不给证据。 5. 使用 pandas 完成清洗与聚合，使用 plotly 生成交互式图表。 6. 生成至少 3 张图表，并在图表之间写简短说明，解释图表反映的业务洞察。 7. 为最终的报告生成一个 HTML 文件。交付要求： 1. 生成可直接交付的 report.html，要求为单文件、自包含 HTML，可离线浏览，不依赖任何外部资源。 2. 报告内容至少包括： - Executive Summary - Key Metrics - Data Quality Notes - 3 个以上图表及对应洞察 - Action Recommendations 分析与表述要求： 1. 优先呈现最有行动价值的发现。 2. 建议必须区分"数据支持的结论"和"需要进一步验证的假设"。 3. 如果样本时间很短、缺少关键字段或无法支撑因果判断，必须明确写出限制。 4. 不得编造不存在的字段、维度、业务背景或结论。执行要求： 1. 读取原始 CSV 后，先记录： - 原始行数 - 原始列数 - 原始列名 - 缺失值情况 - 重复值情况 2. 所有 KPI、Top N、占比、均值、毛利率等数字，在写入报告前必须再次校验。 3. 如果发现数据不足以支撑某个结论，应降低结论强度，而不是强行给出确定性判断。保存前请完成自检，确保： 1. 报告中的数据质量信息和关键指标与原始 CSV 及计算结果一致。 2. report.html 不依赖任何外部资源。 3. HTML 内容完整有效，不包含无效字段、占位内容或语法错误。' ``` 再创建 Agent，将上述 System Prompt 与工具一起提交： ```Bash agent_payload=$(jq -n \ --arg name "data-analyst-agent" \ --arg model "$MODEL_ID" \ --arg system "$ANALYST_SYSTEM_PROMPT" \ --arg toolset "$TOOLSET_TYPE" \ '{ name: $name, description: "把 CSV 数据集分析成带交互图表的 HTML 报告。", model: {id: $model, speed: "standard"}, system: $system, tools: [{ type: $toolset, default_config: { enabled: true, permission_policy: {type: "always_allow"} } }], skills: [], mcp_servers: [], metadata: {scenario: "data_analyst_report"} }') agent=$(curl -sS --fail-with-body "$ARK_BASE_URL/agents" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d "$agent_payload") AGENT_ID=$(jq -er '.id' <<<"$agent") echo "Agent: $AGENT_ID" ``` # 第 3 步：上传待分析数据上传输入文件有多种方式，本示例通过 Files API 上传 CSV 并获取 `FILE_ID`，后续创建 Session 时通过该 ID 引用文件。文件上传采用异步处理，需要等待文件状态变为 `active` 后再继续后续流程，以确保文件已完成处理并可以正常使用。 ```Bash file=$(curl -sS --fail-with-body "$ARK_BASE_URL/files" \ -H "Authorization: Bearer $ARK_API_KEY" \ -F 'purpose=agent' \ -F "file=@${DATA_PATH}") FILE_ID=$(jq -er '.id' <<<"$file") echo "File: $FILE_ID" for _ in $(seq 1 60); do file_info=$(curl -sS --fail-with-body "$ARK_BASE_URL/files/$FILE_ID" \ -H "Authorization: Bearer $ARK_API_KEY") file_status=$(jq -r '.status // "active"' <<<"$file_info") [[ "$file_status" == "active" ]] && break [[ "$file_status" == "failed" ]] && { echo "$file_info" >&2; exit 1; } sleep 2 done ``` # 第 4 步：创建 Session 并挂载数据 Session 表示一次具体的运行实例，用于关联 Agent、Environment 和输入资源。创建 Session 时，通过 `resources` 指定需要挂载的文件，平台会将其映射到沙箱中的 `/mnt/session/uploads/` 目录，供 Agent 在执行过程中访问。Session 创建完成后即进入就绪状态，但不会自动开始执行任务，需在后续发送事件触发执行。 ```Bash UPLOAD_NAME=$(basename "$DATA_PATH") MOUNT_PATH="/mnt/session/uploads/$UPLOAD_NAME" session_payload=$(jq -n \ --arg agent "$AGENT_ID" \ --arg env "$ENVIRONMENT_ID" \ --arg file "$FILE_ID" \ --arg name "$UPLOAD_NAME" \ '{ agent: $agent, environment_id: $env, title: "CSV data analysis", resources: [{type: "file", file_id: $file, mount_path: $name}], metadata: {scenario: "data_analyst_report"} }') session=$(curl -sS --fail-with-body "$ARK_BASE_URL/sessions" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d "$session_payload") SESSION_ID=$(jq -er '.id' <<<"$session") echo "Session: $SESSION_ID" ``` # 第 5 步：下发分析任务 Session 创建完成后并不会自动执行任务，需要向 `/sessions/{session_id}/events` 接口发送一条 `user.message` 事件，作为本次任务的输入，告知 Agent 需要完成的分析内容。事件采用追加（append\-only）的方式写入，会作为 Session 历史的一部分保存，并参与后续对话和任务执行。 ```Bash analysis_prompt=$(cat </dev/null ``` # 第 6 步：实时观测执行过程任务提交后，Agent 会在云端完成推理、代码执行、数据处理和图表生成等操作。通过订阅 Session 的 SSE 事件流可以实时获取执行进度，包括模型输出、工具调用以及任务状态变化。当收到 `session.status_idle` 事件时，表示本次任务已执行完成，可以结束监听。 ```Bash curl -N -sS --fail-with-body "$ARK_BASE_URL/sessions/$SESSION_ID/events/stream" \ -H "Authorization: Bearer $ARK_API_KEY" | while IFS= read -r line; do [[ "$line" == data:* ]] || continue data="${line#data: }" type=$(jq -r '.type // empty' <<<"$data" 2>/dev/null || true) case "$type" in agent.message) jq -r '.content[]? | select(.type == "text") | .text' <<<"$data" ;; agent.tool_use) echo "[tool] $(jq -r '.name // "unknown"' <<<"$data")" ;; session.status_idle) echo "Agent finished." break ;; session.status_terminated) echo "Session terminated." break ;; esac done ``` 主要事件类型： |事件类型 |含义 | |---|---| |`agent.message` |Agent 返回的文本消息 | |`agent.tool_use` |Agent 正在调用工具 | |`agent.tool_result` |工具执行结果 | |`session.status_idle` |本轮任务结束 | |`session.status_terminated` |Session 已终止，需要排查原因 | # 第 7 步：取回分析报告任务完成后，可以通过 Session ID（`scope_id`）查询本次执行生成的文件。Agent 运行过程中产生的报告、图表等文件都会关联到对应的 Session。当查询结果中出现生成的 HTML 文件时，说明分析报告已经生成。 ```Bash curl -sS --fail-with-body "$ARK_BASE_URL/files?scope_id=$SESSION_ID" \ -H "Authorization: Bearer $ARK_API_KEY" | jq '.data[]? | {id, filename, bytes, status}' ``` 生成的文件可以通过控制台下载到本地，方便查看、分享或归档。 # 第 8 步：清理资源分析完成后，可根据需要清理本次运行产生的资源。Session 和上传文件属于临时资源，会占用平台配额，确认结果已保存后可及时删除。Agent 和 Environment 通常作为可复用资源保留，用于后续任务。再次执行分析时，只需创建新的 Session 并引用已有的 Agent、Environment 和输入文件即可。 ```Bash curl -sS --fail-with-body -X DELETE \ "$ARK_BASE_URL/sessions/$SESSION_ID" \ -H "Authorization: Bearer $ARK_API_KEY" curl -sS --fail-with-body -X DELETE \ "$ARK_BASE_URL/files/$FILE_ID" \ -H "Authorization: Bearer $ARK_API_KEY" curl -sS --fail-with-body -X DELETE \ "$ARK_BASE_URL/environments/$ENVIRONMENT_ID" \ -H "Authorization: Bearer $ARK_API_KEY" ```

警告

删除 Session 前，请确认已下载或转存所需文件。Session 中生成的文件属于临时资源，删除 Session 后将无法继续访问。如需长期保存分析报告或其他产物，建议将其存储至 TOS 等持久化存储服务。

# 完整执行顺序 1. 设置 `ARK_API_KEY`、`ARK_BASE_URL`、`MODEL_ID`、`DATA_PATH` 等环境变量。 2. 创建或复用 Environment，确保包含 `pandas` 和 `plotly`。 3. 创建 Agent。 4. 上传 CSV。 5. 创建 Session 并挂载 CSV。 6. 发送 `user.message`。 7. 订阅事件流直到 `session.status_idle`。 8. 按 `scope_id` 查询 Session 产物。 9. 下载生成文件到本地。 10. 按需清理 Session、输入文件与 Environment。

火山方舟