火山方舟
火山方舟
资源
请输入
- 文档首页
火山方舟实践教程Managed Agent[进阶] 使用 arkcli 构建集成 Vault 与 Memory 的投研 Agent
复制全文
下载 pdf[进阶] 使用 arkcli 构建集成 Vault 与 Memory 的投研 Agent
文档反馈
问问助手本教程演示如何使用官方命令行工具 arkcli 构建一个具备 MCP 直连取数、Vault 密钥托管、Memory 长期记忆 三项能力的投研 Agent。教程以 Wind 行情 MCP 为例，完整走一遍从「安装登录 → 创建资源 → 下发任务 → 观测执行 → 取回报告 → 清理资源」的闭环。
场景说明
投研场景有一个典型诉求：分析师希望 AI 助手「懂行情、懂我」。「懂行情」意味着行情、财务等结构化数据必须使用专业数据源；「懂我」意味着助手要记住用户的关注板块、输出格式等长期偏好，不必每次对话重复交代。
这两个诉求恰好对应 Managed Agents 的两项进阶能力：
- Vault 让第三方数据服务的密钥托管在平台侧、按 MCP 服务地址自动注入鉴权，密钥全程不进沙箱。
- Memory Store 让用户偏好以文件形式挂载到每个会话，Agent 在执行前先读取并遵循。
环节 | 内容 |
输入 | 一句自然语言任务，例如「查询贵州茅台最新行情，按我的偏好写一份简评」 |
过程 | Agent 读取挂载的记忆文件，调用 Wind MCP 工具取行情（鉴权由 Vault 注入），按偏好撰写报告 |
输出 | report.md，结论先行、关键数据用表格、风险提示单独成段（这些约定全部来自记忆文件） |
观测 | arkcli +tail 或 events list 查看 Agent 消息、工具调用与状态变化 |
你将完成什么
- 安装并登录 arkcli，理解控制面与数据面的认证边界。
- 创建 Environment。
- 创建 Vault 并托管 Wind 密钥（static_bearer 凭据）。
- 创建 Memory Store 并写入一条用户偏好。
- 创建挂载 Wind MCP 的投研 Agent。
- 创建 Session 并一次性挂上 Vault 与 Memory。
- 下发任务、通过事件流观测执行、取回报告文件。
- 按精确 ID 清理本次创建的全部资源。
核心概念
对象 | 说明 |
Agent | 可版本化、可复用的配置模板，封装模型、System Prompt、工具集与 MCP 连接 |
Environment | Agent 运行所在的云沙箱定义，决定网络策略与预装依赖，一次创建多次复用 |
Session | 一次具体的运行实例，把 Agent、Environment、Vault 和 Memory 等资源绑在一起 |
Event | Session 内的追加式事件流：用 user.message 下发任务，实时收到消息、工具调用与状态变化 |
Vault | 平台侧密钥保管库。static_bearer 凭据按 MCP 服务 URL 匹配注入 Bearer 鉴权，密钥不进沙箱 |
Memory Store | 跨会话长期记忆库。记忆以只读文件挂载到沙箱 /mnt/memory/<store-id>/ 子目录 |
工作流程
前置条件
- 已开通方舟 Managed Agents 与目标模型服务。
- 已创建方舟 API Key，详情请参见 API Key 管理。
- 已获取 Wind API Key（aifinmarket.wind.com.cn，按积分计费）。
- 本地已安装 Node.js（用于 npm 安装 arkcli）。
第 1 步：安装并登录 arkcli
npm i @volcengine/ark-cli -g --registry https://registry.npmjs.org
arkcli --version
arkcli auth login volc-sso # 浏览器完成火山账号授权
arkcli auth status --format json
注意
arkcli 的控制面命令（创建、管理 Agent、Environment、Session、Vault、Memory Store）走 OpenTOP，必须完成火山账号 SSO 登录，纯 API Key 会被拒绝；数据面命令（events、files、+tail）用方舟 API Key 即可。这一点与 curl 直调 REST API（全程仅需 API Key）不同。
注意
如果账号装过 Agent Plan 套餐，其 profile 的 base_url 是 /api/plan/v3，数据面命令会返回 404。使用 arkcli profile list 查看，并在命令前加 --profile <按量 profile 名> 切到控制台按量 profile。
第 2 步：创建 Environment
Environment 定义 Agent 的云沙箱：网络策略、预装依赖等。创建一次可长期复用，本示例无需额外 pip 依赖：
arkcli agent env create \
--name "cookbook-invest-env" \
--config '{Type: cloud, Networking: {Type: unrestricted}}' \
--format json --transform "Result.Id"
# 输出示例：env-20260716132305-xxxxx
注意
线上创建 cloud 类型环境必须显式携带 Networking 配置。仅传 {Type: cloud} 会被后端校验拒绝，报错 config.networking 缺失。
将返回的 ID 记录为 ENVIRONMENT_ID。
说明
本示例创建的 Environment 未配置产物存储，因此报告使用方舟公共 TOS。需要将报告长期保存在自己的 TOS Bucket 时，通过控制台或 Environment API 配置 config.tos，详情请参见 配置产物存储。
第 3 步：创建 Vault 并写入 Wind 凭据
Wind 提供多个 MCP 数据服务，地址形如 https://mcp.wind.com.cn/vserver_<name>/mcp/，以 Bearer Key 鉴权。传统做法是把 Key 写进环境变量带入沙箱，泄漏面较大。Managed Agents 的做法是：把 Key 存成 Vault 里的 static_bearer 凭据，Session 挂载该 Vault 后，平台在连接对应 MCP URL 时自动注入 Bearer 鉴权。密钥全程不进沙箱、不进提示词、不进事件流。
创建 Vault：
arkcli agent vault create --display-name "cookbook-wind-vault" \
--format json --transform "Result.Id"
# 输出示例：vlt-20260716132312-xxxxx
写入 static_bearer 凭据（以股票行情服务为例）：
cat <<'EOF' | arkcli agent vault credentials create $VAULT_ID --format json
{
"display_name": "wind_stock_data",
"auth": {
"type": "static_bearer",
"mcp_server_url": "https://mcp.wind.com.cn/vserver_stock_data/mcp/",
"token": "你的 WIND_API_KEY"
}
}
EOF
说明
创建凭据时平台会立即对目标 MCP 服务做握手探测。创建成功（返回 vcrd- 开头的凭据 ID）即代表 Key 有效，等于免费得到一次同步校验。
说明
生产使用建议给每个需要的 Wind MCP 服务各建一条凭据（每条对应一个 mcp_server_url），Agent 即可全域取数。本教程为保持最小可跑通，只挂股票行情服务 vserver_stock_data。
第 4 步：创建 Memory Store 并写入用户偏好
arkcli agent memory-store create \
--name "cookbook-user-memory" \
--description "投研偏好与输出约定" \
--format json --transform "Result.Id"
# 输出示例：memstore-20260716132317-xxxxx
arkcli agent memory-store memories create $STORE_ID \
--path "/投研偏好.md" \
--content "# 用户投研偏好
- 长期关注：白酒、半导体行业
- 输出格式：结论先行，正文不超过 300 字，关键数据用表格
- 风险提示必须单独成段" \
--format json
注意
Memory 是「文件挂载」语义，不是「上下文注入」语义。挂载后记忆以只读文件出现在沙箱 /mnt/memory/<store-id>/ 子目录下，平台不会替应用把内容自动塞进模型上下文。因此必须在 System Prompt 里明确指示 Agent「先执行 ls -R /mnt/memory 找到并读取全部记忆文件」——只写「浏览记忆目录」这类模糊指引，Agent 用顶层通配符（如 cat /mnt/memory/*.md）匹配不到子目录里的文件，会误判「没有记忆」。
第 5 步：创建投研 Agent 并挂载 Wind MCP
挂 MCP 需要两处配置成对出现：McpServers 声明连接（名称 + URL），Tools 里的 mcp_toolset 按名称放行该服务的工具。System Prompt 写清三条规则：优先用 MCP 取数、先读记忆、标注数据来源。
将请求体写入 cookbook-agent.json：
{
"Name": "cookbook投研分析师",
"Description": "Wind MCP + Memory 演示用投研 Agent",
"Model": {"Id": "doubao-seed-2-1-pro-260628", "Speed": "standard"},
"System": "你是一名 A 股投研分析师。规则：1) 行情、财务等结构化数据必须优先调用 wind_stock_data MCP 工具获取，单次调用单标的，日期格式 yyyyMMdd；2) 若挂载了记忆目录（/mnt/memory），记忆文件位于其下的 memstore-* 子目录内，开始任务前先执行 ls -R /mnt/memory 找到并读取全部 .md 记忆文件，严格遵循其中的偏好与输出约定；3) 引用 Wind 数据时标注来源。",
"McpServers": [
{
"Type": "url",
"Name": "wind_stock_data",
"Url": "https://mcp.wind.com.cn/vserver_stock_data/mcp/"
}
],
"Tools": [
{
"Type": "agent_toolset_20260701",
"Name": "agent_toolset_20260701",
"DefaultConfig": {"Enabled": true, "PermissionPolicy": {"Type": "always_allow"}}
},
{
"Type": "mcp_toolset",
"McpServerName": "wind_stock_data",
"DefaultConfig": {"PermissionPolicy": {"Type": "always_allow"}}
}
]
}
提交请求：
arkcli agent agent create --file cookbook-agent.json \
--format json --transform "Result.Id"
# 输出示例：agent-20260716132811-xxxxx
注意
复杂配置建议整体走 --file 传 JSON 请求体，字段使用 PascalCase（与 OpenTOP 契约对齐）。--tool @文件名 这种单参数文件引用语法不可用，会报 YAML 解析错误。
注意
McpServers[].Name 必须与 mcp_toolset.McpServerName 逐字一致；Vault 凭据则按 mcp_server_url 与这里的 Url 匹配注入。三处对齐，鉴权才能生效。
注意
agent_toolset_20260701 是内置工具集（bash / read / write / edit / glob / grep / web_fetch / web_search）。Tools 字段是全量替换语义：只要显式传了 Tools，就必须把内置工具集和 mcp_toolset 放在同一个数组里，否则 Agent 会失去内置工具。
将返回的 ID 记录为 AGENT_ID。
第 6 步：创建 Session 并一次挂上 Vault 与 Memory
arkcli agent session create \
--agent-id $AGENT_ID \
--environment-id $ENVIRONMENT_ID \
--vault-ids $VAULT_ID \
--resource '[{"Type": "memory_store", "MemoryStoreId": "'"$STORE_ID"'", "Instructions": "用户长期记忆（偏好与输出约定）。记忆文件位于本目录下的 memstore-* 子目录内，先 ls -R 找到并读取全部 .md 文件再开始任务。"}]' \
--title "cookbook-invest-session" \
--format json
# 输出示例：sesn-20260716132851-xxxxx
注意
--resource 里的字段名必须使用 PascalCase（MemoryStoreId）。写成 snake_case（memory_store_id）字段会被静默丢弃，报错 resources[0].memory_store_id is required——报错信息用的是 snake_case，容易造成混淆。
说明
Instructions 是记忆挂载中唯一会自动进入 Agent 上下文的文字。把目录结构和标准动作写死在这里（与 System Prompt 形成双保险），Agent 就不需要盲目探索文件系统。
将返回的 ID 记录为 SESSION_ID。
第 7 步：下发投研任务
Session 创建后处于就绪状态，不会自动执行任务。发送一条 user.message 事件触发执行：
arkcli agent session events send $SESSION_ID \
--type user.message \
--text "查询贵州茅台（600519.SH）最新行情数据，并按我的偏好写一份简评，保存为 /mnt/session/outputs/report.md" \
--format json
第 8 步：观测执行过程
方式一：实时事件流
arkcli +tail $SESSION_ID
方式二：结构化拉取历史事件
arkcli agent session events list $SESSION_ID --limit 100 --format json
主要事件类型：
事件类型 | 含义 |
agent.thinking | Agent 思考中（信号级事件） |
agent.tool_use / agent.tool_result | 内置工具调用与结果（bash、read、write 等） |
agent.mcp_tool_use / agent.mcp_tool_result | MCP 工具调用与结果，观察 Wind 取数就看它 |
agent.message | Agent 返回的文本消息 |
span.model_request_start / span.model_request_end | 一次模型请求的起止，end 携带 token 用量 |
session.status_idle | 本轮任务结束 |
一次成功任务的典型事件轨迹：
user.message 查询贵州茅台最新行情，按我的偏好写一份简评
agent.tool_use bash: ls -R /mnt/memory -- 按指引定位记忆
agent.tool_use read: /mnt/memory/memstore-.../投研偏好.md -- 读取偏好
agent.mcp_tool_use wind_stock_data/get_stock_price_indicators -- Wind 取数（Vault 注入鉴权）
agent.mcp_tool_use wind_stock_data/get_stock_price_indicators
agent.tool_use write: /mnt/session/outputs/report.md -- 按偏好写入报告
agent.message 已按你的投研偏好完成，保存至 /mnt/session/outputs/report.md
session.status_idle
说明
若 +tail 或 events stream 出现 awaiting headers 超时，不影响任务在云端执行，改用 events list 轮询兜底即可。
第 9 步：取回分析报告
Agent 写入沙箱的产物会自动登记到 Files API，按 Session 维度可查：
arkcli agent file list \
--session-id $SESSION_ID \
--purpose agent \
--format json
# 返回示例：{"filename": "report.md", "id": "file-20260716213008-xxxxx", "bytes": 1341, "status": "active"}
注意
file list 默认按 --purpose user_data 过滤，而 Agent 生成的产物 purpose 是 agent。不带 --purpose agent 参数会得到空列表，误以为没有产物。
文件可以在方舟控制台对应 Session 页下载。本示例使用方舟公共 TOS，你需要在平台 TTL 到期前下载报告。需要长期保留报告时，为 Environment 配置自己的 TOS Bucket，并在 TOS 中管理对象生命周期。
第 10 步：清理资源
确认报告已转存后，按依赖顺序清理本次创建的资源。Agent 与 Environment 通常留作复用，本教程为演示做完整清理：
arkcli agent session delete $SESSION_ID --yes
arkcli agent vault credentials delete $VAULT_ID $CREDENTIAL_ID --yes
arkcli agent vault delete $VAULT_ID --yes
arkcli agent memory-store delete $STORE_ID --yes
arkcli agent agent delete $AGENT_ID --yes
arkcli agent env delete $ENVIRONMENT_ID --yes
警告
只删除本次创建、且记录了精确 ID 的资源。切勿按名称模糊匹配批量删除——企业账号下的资源可能被多人或多系统共享，误删不可恢复。删除类命令在非交互环境（脚本或 CI）中不带 --yes 时会返回 requires_confirmation 而不执行，这是有意的安全设计。
完整执行顺序
- 安装 arkcli 并完成 arkcli auth login volc-sso（控制面需 SSO，数据面用 API Key）。
- 创建 Environment（显式带 Networking）。
- 创建 Vault，写入 Wind 的 static_bearer 凭据（创建即校验 Key）。
- 创建 Memory Store，写入用户偏好文件。
- 用 --file 传 PascalCase 请求体创建 Agent（内置工具集 + mcp_toolset 同数组）。
- 创建 Session：--vault-ids 挂 Vault，--resource（PascalCase）挂 Memory 并写清 Instructions。
- 发送 user.message 下发任务。
- +tail 或 events list 观测直到 session.status_idle。
- file list --session-id ... --purpose agent 取回产物并转存。
- 按精确 ID 清理临时资源。
进阶方向
- 全域数据：给需要的 MCP 服务各建一条 Vault 凭据并全部挂到 Agent，覆盖更多数据面。
- 领域技能：把 MCP 路由规则、参数契约、指标词典打包成自定义 Skill（arkcli agent skill create --zip）挂给 Agent，取数精准度更高。
- 多智能体：通过 Multiagent 配置把个股研究员、行业分析师、宏观经济学家组成 coordinator 协作团队，详情请参见 用多智能体团队生成定制销售提案。
- 工程化：每条 arkcli 命令都是 /api/v3 与 OpenTOP 接口的封装，应用后端可直接改调 REST API，配合调度器与推送渠道即可长成完整投研平台。
注意
方舟按 token、沙箱时长与工具调用计费，第三方 MCP 服务按其自身计费策略结算。单次复杂投研任务可消耗数十万 input tokens，请留意用量。所有产出仅供参考，不构成投资建议。
最近更新时间：2026.08.27 11:36:07
这个页面对您有帮助吗？
有用
有用
无用
无用