面向 AI 助手：本页的 Markdown 版本位于 https://ark.volcengine.com/region:cn-beijing/docs/build-investment-research-agent-with-arkcli.md，全部文档索引见 https://ark.volcengine.com/llms.txt。

[进阶] 使用 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 可以根据挂载权限读取或修改其中的内容

工作流程#

arkcli 投研 Agent 流程

前置条件#

  • 已开通方舟 Managed Agents 与目标模型服务。
  • 已创建方舟 API Key，详情请参见 API Key 管理。
  • 已获取 Wind API Key（aifinmarket.wind.com.cn，按积分计费）。
  • 本地已安装 Node.js（用于 npm 安装 arkcli）。

第 1 步：安装并登录 arkcli#

Bash
npm i @volcengine/ark-cli -g --registry https://registry.npmjs.org
arkcli --version
arkcli auth login volc-sso    # 浏览器完成火山账号授权
arkcli auth status --format json

第 2 步：创建 Environment#

Environment 定义 Agent 的云沙箱：网络策略、预装依赖等。创建一次可长期复用，本示例无需额外 pip 依赖：

Bash
arkcli agent env create \
  --name "cookbook-invest-env" \
  --config '{Type: cloud, Networking: {Type: unrestricted}}' \
  --format json --transform "Result.Id"
# 输出示例：env-20260716132305-xxxxx

将返回的 ID 记录为 ENVIRONMENT_ID。

第 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：

Bash
arkcli agent vault create --display-name "cookbook-wind-vault" \
  --format json --transform "Result.Id"
# 输出示例：vlt-20260716132312-xxxxx

写入 static_bearer 凭据（以股票行情服务为例）。以下命令通过无回显输入读取 Wind API Key，再使用 @file 将密钥交给 ArkCLI：

bash
old_umask=$(umask)
umask 077
WIND_KEY_FILE=$(mktemp)
umask "$old_umask"
trap 'rm -f "$WIND_KEY_FILE"' EXIT

IFS= read -r -s -p "Wind API Key: " WIND_API_KEY
printf '\n'
printf '%s' "$WIND_API_KEY" >"$WIND_KEY_FILE"
unset WIND_API_KEY

CREDENTIAL_ID=$(arkcli agent vault credentials create "$VAULT_ID" \
  --display-name "wind_stock_data" \
  --auth-type static_bearer \
  --mcp-server-url "https://mcp.wind.com.cn/vserver_stock_data/mcp/" \
  --token "@$WIND_KEY_FILE" \
  --format json \
  --transform "Result.Id")
export CREDENTIAL_ID

rm -f "$WIND_KEY_FILE"
trap - EXIT
printf 'Credential ID: %s\n' "$CREDENTIAL_ID"

API Key 不会出现在命令行参数、Shell 历史或 ArkCLI 结构化输出中。脚本只在请求期间保留权限为 600 的临时文件，并在结束时删除。

第 4 步：创建 Memory Store 并写入用户偏好#

Bash
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

第 5 步：创建投研 Agent 并挂载 Wind MCP#

挂 MCP 需要两处配置成对出现：McpServers 声明连接（名称 + URL），Tools 里的 mcp_toolset 按名称放行该服务的工具。System Prompt 写清三条规则：优先用 MCP 取数、先读记忆、标注数据来源。

将请求体写入 cookbook-agent.json：

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) 开始任务前使用 Memory 工具浏览已挂载的记忆库，读取其中的投研偏好文件，并严格遵循偏好与输出约定；3) 引用 Wind 数据时标注来源。",
  "McpServers": [
    {
      "Type": "url",
      "Name": "wind_stock_data",
      "Url": "https://mcp.wind.com.cn/vserver_stock_data/mcp/"
    }
  ],
  "Tools": [
    {
      "Type": "agent_toolset_20260916",
      "Name": "agent_toolset_20260916",
      "DefaultConfig": {"Enabled": true, "PermissionPolicy": {"Type": "always_allow"}}
    },
    {
      "Type": "mcp_toolset",
      "McpServerName": "wind_stock_data",
      "DefaultConfig": {"PermissionPolicy": {"Type": "always_allow"}}
    }
  ]
}

提交请求：

Bash
arkcli agent agent create --file cookbook-agent.json \
  --format json --transform "Result.Id"
# 输出示例：agent-20260716132811-xxxxx

将返回的 ID 记录为 AGENT_ID。

第 6 步：创建 Session 并一次挂上 Vault 与 Memory#

Bash
arkcli agent session create \
  --agent-id $AGENT_ID \
  --environment-id $ENVIRONMENT_ID \
  --vault-ids $VAULT_ID \
  --resource '[{"Type": "memory_store", "MemoryStoreId": "'"$STORE_ID"'", "Access": "read_only"}]' \
  --title "cookbook-invest-session" \
  --format json
# 输出示例：sesn-20260716132851-xxxxx

将返回的 ID 记录为 SESSION_ID。

第 7 步：下发投研任务并持续接收事件#

Session 创建后处于就绪状态，不会自动执行任务。使用 --stream 发送 user.message，让 ArkCLI 在同一条命令中持续接收事件，并通过事件位置补偿发送与建连之间的事件：

Bash
arkcli agent session events send $SESSION_ID \
  --type user.message \
  --text "查询贵州茅台（600519.SH）最新行情数据，并按我的偏好写一份简评，保存为 /mnt/session/outputs/report.md" \
  --stream \
  --no-event-deltas \
  --format json

不要先执行不带等待参数的 events send，再单独启动 +tail。两个命令之间存在监听空窗，容易让终端漏掉任务开始阶段的事件。

第 8 步：回查执行过程#

方式一：继续观察已有 Session#

Bash
arkcli +tail $SESSION_ID

第 7 步的 --stream 已覆盖本轮实时观测。只有需要在另一个终端继续观察已有 Session 时，才使用 +tail。

方式二：结构化拉取历史事件#

Bash
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 本轮任务结束

一次成功任务的典型事件轨迹：

Text
user.message        查询贵州茅台最新行情，按我的偏好写一份简评
agent.tool_use      读取已挂载的投研偏好
agent.tool_result   返回已保存的偏好内容
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

第 9 步：取回分析报告#

Agent 写入沙箱的产物会自动登记到 Files API，按 Session 维度可查：

Bash
arkcli agent file list \
  --session-id $SESSION_ID \
  --purpose agent \
  --format json
# 返回示例：{"filename": "report.md", "id": "file-20260716213008-xxxxx", "bytes": 1341, "status": "active"}

文件可以在方舟控制台对应 Session 页下载。本示例使用方舟公共 TOS，你需要在平台 TTL 到期前下载报告。需要长期保留报告时，为 Environment 配置自己的 TOS Bucket，并在 TOS 中管理对象生命周期。

第 10 步：清理资源#

确认报告已转存后，按依赖顺序清理本次创建的资源。Agent 与 Environment 通常留作复用，本教程为演示做完整清理：

Bash
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

完整执行顺序#

  1. 安装 arkcli 并完成 arkcli auth login volc-sso（控制面需 SSO，数据面用 API Key）。
  2. 创建 Environment（显式带 Networking）。
  3. 创建 Vault，写入 Wind 的 static_bearer 凭据（创建即校验 Key）。
  4. 创建 Memory Store，写入用户偏好文件。
  5. 用 --file 传 PascalCase 请求体创建 Agent（内置工具集 + mcp_toolset 同数组）。
  6. 创建 Session：--vault-ids 挂 Vault，--resource（PascalCase）以 read_only 权限挂载 Memory。
  7. 使用 events send --stream 下发 user.message，持续观测到 session.status_idle。
  8. 需要恢复观测时，使用 +tail 或 events list 回查同一个 Session。
  9. file list --session-id ... --purpose agent 取回产物并转存。
  10. 按精确 ID 清理临时资源。

进阶方向#

  • 全域数据：给需要的 MCP 服务各建一条 Vault 凭据并全部挂到 Agent，覆盖更多数据面。
  • 领域技能：把 MCP 路由规则、参数契约、指标词典打包成自定义 Skill（arkcli agent skill create --zip）挂给 Agent，取数精准度更高。
  • 多智能体：通过 Multiagent 配置把个股研究员、行业分析师、宏观经济学家组成 coordinator 协作团队，详情请参见 用多智能体团队生成定制销售提案。
  • 工程化：应用后端可以按需改用对应 REST API，配合调度器与推送渠道构建完整投研平台。