火山方舟
火山方舟
资源
请输入
- 文档首页
火山方舟实践教程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 | 跨会话长期记忆库。Agent 可以根据挂载权限读取或修改其中的内容 |
工作流程
前置条件
- 已开通方舟 Managed Agents 与目标模型服务。
- 方舟 API Key：已创建方舟 API Key，详情请参见 API Key 管理。
- 已获取 Wind API Key（aifinmarket.wind.com.cn，按积分计费）。
- 本地已安装 Node.js（用于 npm 安装 arkcli）。
第 1 步：安装并登录 arkcli
注意
arkcli 创建和管理 Agent、Environment、Session、Vault、Memory Store 前，必须先完成火山账号 SSO 登录；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 依赖：
注意
线上创建 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：
写入 static_bearer 凭据（以股票行情服务为例）。以下命令通过无回显输入读取 Wind API Key，再使用 @file 将密钥交给 ArkCLI：
API Key 不会出现在命令行参数、Shell 历史或 ArkCLI 结构化输出中。脚本只在请求期间保留权限为 600 的临时文件，并在结束时删除。
说明
创建凭据时平台会立即对目标 MCP 服务做握手探测。创建成功（返回 vcrd- 开头的凭据 ID）即代表 Key 有效，等于免费得到一次同步校验。
说明
生产使用建议给每个需要的 Wind MCP 服务各建一条凭据（每条对应一个 mcp_server_url），Agent 即可全域取数。本教程为保持最小可跑通，只挂股票行情服务 vserver_stock_data。
第 4 步：创建 Memory Store 并写入用户偏好
注意
Memory Store 的内容不会自动注入模型上下文。请在 System Prompt 中明确要求 Agent 在开始任务前读取已挂载的投研偏好。
第 5 步：创建投研 Agent 并挂载 Wind MCP
挂 MCP 需要两处配置成对出现：McpServers 声明连接（名称 + URL），Tools 里的 mcp_toolset 按名称放行该服务的工具。System Prompt 写清三条规则：优先用 MCP 取数、先读记忆、标注数据来源。
将请求体写入 cookbook-agent.json：
提交请求：
注意
复杂配置建议整体走 --file 传 JSON 请求体，字段使用 arkcli 接受的 PascalCase。--tool @文件名 这种单参数文件引用语法不可用，会报 YAML 解析错误。
注意
McpServers[].Name 必须与 mcp_toolset.McpServerName 逐字一致；Vault 凭据则按 mcp_server_url 与这里的 Url 匹配注入。三处对齐，鉴权才能生效。
注意
agent_toolset_20260916 是内置工具集（bash / read / write / edit / glob / grep / web_fetch / web_search）。Tools 字段是全量替换语义：只要显式传了 Tools，就必须把内置工具集和 mcp_toolset 放在同一个数组里，否则 Agent 会失去内置工具。
将返回的 ID 记录为 AGENT_ID。
第 6 步：创建 Session 并一次挂上 Vault 与 Memory
注意
--resource 里的字段名必须使用 PascalCase（MemoryStoreId）。写成 snake_case（memory_store_id）字段会被静默丢弃，报错 resources[0].memory_store_id is required：报错信息用的是 snake_case，容易造成混淆。
将返回的 ID 记录为 SESSION_ID。
第 7 步：下发投研任务并持续接收事件
Session 创建后处于就绪状态，不会自动执行任务。使用 --stream 发送 user.message，让 ArkCLI 在同一条命令中持续接收事件，并通过事件位置补偿发送与建连之间的事件：
不要先执行不带等待参数的 events send，再单独启动 +tail。两个命令之间存在监听空窗，容易让终端漏掉任务开始阶段的事件。
第 8 步：回查执行过程
方式一：继续观察已有 Session
第 7 步的 --stream 已覆盖本轮实时观测。只有需要在另一个终端继续观察已有 Session 时，才使用 +tail。
方式二：结构化拉取历史事件
主要事件类型：
事件类型 | 含义 |
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 | 本轮任务结束 |
一次成功任务的典型事件轨迹：
说明
若 --stream、+tail 或 events stream 出现 awaiting headers 超时，不影响任务在云端执行，改用 events list 轮询同一个 Session，避免重复发送原任务。
第 9 步：取回分析报告
Agent 写入沙箱的产物会自动登记到 Files API，按 Session 维度可查：
注意
file list 默认按 --purpose user_data 过滤，而 Agent 生成的产物 purpose 是 agent。不带 --purpose agent 参数会得到空列表，误以为没有产物。
文件可以在方舟控制台对应 Session 页下载。本示例使用方舟公共 TOS，你需要在平台 TTL 到期前下载报告。需要长期保留报告时，为 Environment 配置自己的 TOS Bucket，并在 TOS 中管理对象生命周期。
第 10 步：清理资源
确认报告已转存后，按依赖顺序清理本次创建的资源。Agent 与 Environment 通常留作复用，本教程为演示做完整清理：
警告
只删除本次创建、且记录了精确 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）以 read_only 权限挂载 Memory。
- 使用 events send --stream 下发 user.message，持续观测到 session.status_idle。
- 需要恢复观测时，使用 +tail 或 events list 回查同一个 Session。
- file list --session-id ... --purpose agent 取回产物并转存。
- 按精确 ID 清理临时资源。
进阶方向
- 全域数据：给需要的 MCP 服务各建一条 Vault 凭据并全部挂到 Agent，覆盖更多数据面。
- 领域技能：把 MCP 路由规则、参数契约、指标词典打包成自定义 Skill（arkcli agent skill create --zip）挂给 Agent，取数精准度更高。
- 多智能体：通过 Multiagent 配置把个股研究员、行业分析师、宏观经济学家组成 coordinator 协作团队，详情请参见 用多智能体团队生成定制销售提案 。
- 工程化：应用后端可以按需改用对应 REST API，配合调度器与推送渠道构建完整投研平台。
注意
方舟按 token、沙箱时长与工具调用计费，第三方 MCP 服务按其自身计费策略结算。单次复杂投研任务可消耗数十万 input tokens，请留意用量。所有产出仅供参考，不构成投资建议。
最近更新时间：2026.10.28 19:53:17
这个页面对您有帮助吗？
有用
有用
无用
无用