AI Agent 工作流
VizChat 用 root_agent + on-demand skill 编排，把搜索、推荐、执行三阶段闭环做到对话内可见。
为什么是多 Agent
单次 LLM 调用能力有限：上下文窗口固定、工具选择笨拙、长期规划差。VizChat 基于 Google ADK（Agent Development Kit）搭了一套单 root_agent + 按需加载 skill 的系统——主对话编排器始终在线，专项能力（如 widget 创建）通过 ADK skill 机制按需加载，避免上下文被不相关的工具污染。
主 Agent 的职责是编排——它根据用户意图调用合适的工具或子 Agent，自己不直接生成最终的 widget 内容。
三阶段闭环
一次"帮我加一个销售柱状图"的对话，内部典型链路：
阶段 1：搜索
主 Agent 调用：
web_search：如果 prompt 提到外部数据（"最新苹果股价"），调用 Serper API 搜索read_yaml_path：读取当前画布已有 widget，避免重复- 文档/PDF/链接读取：通过
reader_tools提取上下文
阶段 2：推荐
调用子 Agent widget_recommender_agent，由它基于 widget 描述库判断应该用哪种 widget 类型（bar-chart? infographic? widget?）。推荐结果包括：类型名、理由、数据 schema 示例。
如果 marketplace 里没有合适的现有 widget，主 Agent 会触发 create-widget skill——这是一个按需加载的能力包，激活后暴露 6 个 widget 编辑工具（scaffold / write / read / compile / check / publish），让主 Agent 在同一对话内完成"AI 帮你写 widget"全流程。
阶段 3：执行
主 Agent 拿到推荐后，调用 node_operations 工具集：
create_widget：生成 widget 的初始 YAMLedit_yaml_path：对已有 widget 做精确字段修改validate_board：修改完成后验证整张画布合法（schema、id 唯一性、连线端点）
如果走的是 create-widget skill，最终产物是一个 user-scoped widget（默认 PRIVATE，仅 owner 可见但 root_agent 可推荐使用）；主 Agent 通过 emit_client_action 工具通知前端打开 widget 编辑器 tab，让你随时回看、微调或决定是否 publish 到 marketplace。
Agent 可用工具一览
当前注册的工具集（代码位置：apps/vizchat-api/app/ai/adk/）：
| 工具模块 | 职责 |
|---|---|
board_editor | 读写画布 YAML（核心） |
node_operations | 增删改查 widget |
workspace_document_tools | 访问工作区其他文档（读跨文件上下文） |
reader_tools | 读 PDF / URL / 图片内容 |
web_search | 实时 web 搜索（Serper） |
code_execution | Python 代码执行（数据处理） |
emit_client_action | 触发前端 UI 副作用（打开文档 / toast / 刷新） |
create-widget skill | 按需加载，6 个 widget 编辑工具 |
create-widget skill 的 6 个工具默认不暴露给 LLM——只有当主 Agent 调 load_skill('create-widget') 激活后，才会进入工具列表。这避免了"用户只是问个简单问题，结果上下文被一堆 widget 工具占满"的浪费。
触发 Agent 的方式
- 对话栏打字：最常见入口
- Slash 命令：
/chart、/widget、/search快速触发特定工作流 - 选中 widget + 对话：把 widget 作为"焦点上下文"，AI 只改这一个 widget
- 上传 PDF / URL：文件上传会自动触发
reader_tools提取内容
详见 对话功能详解。
成本与模型
默认主模型由 AdkConfig.get_root_model() 决定（VizChat 当前使用 Qwen 3.5 系列）。通过 BYOK 可以切换到你自己的 OpenAI / Anthropic / OpenRouter / 通义千问 key——一旦走 BYOK，平台积分不消耗，只消耗你 key 的原生配额。
每次 Agent 调用消耗的积分记录在 usage_record 表，按 token 成本 × 2 倍 markup × $1 = 1000 credits 换算。详见 积分系统。