AI Agent 工作流
VizChat 用单个 Agent + 按需加载的组件构建 skill——收集上下文、找到或做出组件、写入文档、验证，全过程对话内可见。
系统形态
VizChat 基于 Google ADK 运行一个 Agent：常用工具直接可用，而"新建一个组件"这类专项能力只在真正需要时才加载。把不常用的工具挡在默认工具列表之外，简单问题就不会把一堆无关工具拖进上下文。
这个 Agent 不只是给建议——它通过工具调用直接读写你的文档，整个过程在对话里可见。
一次请求的流转
一次"帮我加一个销售柱状图"的请求，大致经过这几个阶段。
收集上下文
按你的诉求，Agent 可能会：
read_yaml_path——读当前文档，在已有内容上改，而不是重复造get_document/search_documents——取你引用或上传的工作空间文档get_webpage——读取网页或链接search_web——需要外部数据时联网检索run_python——在数据进入组件前做计算或整形，跑在云端沙箱里（带 numpy、pandas 的 Python，无网络、无 shell）；超出这些的计算可以在本地完整环境里运行
找组件
search_widgets 在同一个池子里检索内置组件与用户发布的组件；describe_widget 再返回该组件实际接受的字段与操作。你收藏过的、或用 @ 提到的组件会被优先考虑。
如果都不合适，Agent 会加载 vizchat-widget skill——一个按需加载的能力包，激活后暴露整条组件构建工具链，让它在同一对话内完成新组件的构建与发布。产物默认仅你自己可见；Agent 可以用 show_widget 打开组件编辑器，方便你回看、微调或决定是否发布。
写入与验证
组件及其数据被写进文档，后续修改用 edit_yaml_path 做精确路径编辑。编辑完成后，check_board 检查文档结构、引用的组件是否都已创建、引用的工作空间文档是否存在。
Agent 可用工具一览
| 领域 | 工具 |
|---|---|
| 文档编辑与验证 | read_yaml_path、edit_yaml_path、check_board、list_board_widget_updates、update_board_widgets |
| 组件发现 | search_widgets、describe_widget |
| 工作空间与文件 | list_workspaces、list_documents、get_document、search_documents、create_document、edit_document、move_document、delete_document |
| 展示结果 | show_board、show_widget（在工作台打开 board 或组件） |
| 网页 | search_web、get_webpage |
| 计算 | run_python |
| 前端副作用 | emit_client_action（弹提示、刷新文档） |
| 按需 skill | vizchat-widget——组件构建工具（create_widget、get_widget、compile_widget、publish_widget、get_widget_merge、resolve_widget_merge、list_widget_history、restore_widget），需要时才加载 |
触发 Agent 的方式
- 对话栏打字：最常见入口
- 选中组件 + 对话：把该组件作为"焦点上下文"
- 用
@引用文档：把 Agent 指向某个具体的工作空间文件 - 上传文件：上传的文档会被解析，可直接读取
详见 对话写作技巧。
成本与模型
模型在对话栏里由你自己选：两个官方槽位（Smart / Fast，默认 Fast），以及你通过 BYOK 配置的个人模型——一旦走 BYOK，平台积分不消耗，只消耗你 key 的原生配额。
每次 Agent 调用的积分消耗按会话记录。详见 积分系统。