火山方舟
火山方舟
资源
请输入
- 文档首页
火山方舟实践教程Managed Agent[进阶] 构建从 CSV 到交互式报告的数据分析 Agent
复制全文
下载 pdf[进阶] 构建从 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 管理。
- 本地已安装 curl 和 jq。
- 准备一个 CSV 文件，例如 test_csv.csv。
将 API Key、Base URL 和常用配置配置为环境变量：
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。
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 保存为变量：
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 与工具一起提交：
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 后再继续后续流程，以确保文件已完成处理并可以正常使用。
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 创建完成后即进入就绪状态，但不会自动开始执行任务，需在后续发送事件触发执行。
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 历史的一部分保存，并参与后续对话和任务执行。
analysis_prompt=$(cat <<EOF
分析挂载在 $MOUNT_PATH 的 CSV 数据集。
请完成：
1. 识别字段含义、数据规模和明显质量问题。
2. 找出收入、品类、区域、时间趋势或用户行为中的关键发现。
3. 至少生成 3 张 plotly 交互图表。
4. 输出一个 HTML 报告，包含摘要、图表、关键数字和行动建议。
EOF
)
events_payload=$(jq -n --arg text "$analysis_prompt" \
'{events: [{type: "user.message", content: [{type: "text", text: $text}]}]}')
curl -sS --fail-with-body "$ARK_BASE_URL/sessions/$SESSION_ID/events" \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d "$events_payload" >/dev/null
第 6 步：实时观测执行过程
任务提交后，Agent 会在云端完成推理、代码执行、数据处理和图表生成等操作。通过订阅 Session 的 SSE 事件流可以实时获取执行进度，包括模型输出、工具调用以及任务状态变化。当收到 session.status_idle 事件时，表示本次任务已执行完成，可以结束监听。
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 文件时，说明分析报告已经生成。
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 和输入文件即可。
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 前，先确认所需文件的存储位置。使用方舟公共 TOS 时，删除 Session 会清理关联产物，需要提前下载；使用自己的 TOS Bucket 时，删除 Session 不会删除 Bucket 中的对象，你需要继续管理对象生命周期。
完整执行顺序
- 设置 ARK_API_KEY、ARK_BASE_URL、MODEL_ID、DATA_PATH 等环境变量。
- 创建或复用 Environment，确保包含 pandas 和 plotly。
- 创建 Agent。
- 上传 CSV。
- 创建 Session 并挂载 CSV。
- 发送 user.message。
- 订阅事件流直到 session.status_idle。
- 按 scope_id 查询 Session 产物。
- 下载生成文件到本地。
- 按需清理 Session、输入文件与 Environment。
最近更新时间：2026.08.27 11:36:07
这个页面对您有帮助吗？
有用
有用
无用
无用