For AI agents: the complete documentation index is available at https://a3s-lab.github.io/UI/llms.txt, the full documentation bundle is available at https://a3s-lab.github.io/UI/llms-full.txt, and this page is available as Markdown at https://a3s-lab.github.io/UI/components/tool-call.md.

工具调用

工具调用把一次外部能力执行拆成可审计的名称、参数、进度、结果和恢复动作。默认摘要只回答“正在做什么、由谁执行、处于什么状态”,展开后才显示可能很长的输入输出。

运行中的仓库检索
检索权限边界实现search · rg "permission|policy" src1.8 s运行中
工作目录 /workspace/ui调用 ID call_8f42输出已脱敏
参数JSON
{"query":"permission|policy","path":"src","limit":200}
实时输出3 个匹配
src/security/policy.ts:42: export function authorize(...)
src/runtime/permission.ts:18: type PermissionDecision = ...
tests/policy.spec.ts:71: expect(decision).toEqual(...)
68%

产品边界

工具调用不是日志容器。它必须保留用户判断一次执行是否可信所需的信息,同时避免把提供方内部字段直接倾倒到界面。

  • 标题使用业务动作,例如“读取配置”,而不是只有 shell_command。
  • 状态必须区分准备、等待批准、运行、成功、拒绝、失败、超时和中断。
  • 危险操作在执行前进入 awaiting,并由宿主提供明确的批准与拒绝动作。
  • 输入、输出和错误分区展示;长内容保留滚动边界,不能撑破任务时间线。
  • 重试、停止、复制或打开文件等动作发送事件,网络、权限和审计仍由宿主负责。

控制器

方法结果
setState(state, options)同步状态、状态文案、耗时与错误,并发送状态事件
setProgress(value)设置 0–100 的确定进度;非数字恢复为不确定进度
appendOutput(chunk)追加流式输出并发送 a3s:tool-output-change
setOutput(output)原子替换输出,适合非流式结果
openCall() / close() / toggle(force)控制原生 <details>
runAction(action)经过可取消的授权事件后发送宿主动作
getState()返回只读状态、进度、耗时、输出和展开快照

状态优先使用 preparing、awaiting、running、succeeded、failed、denied、timed-out 与 interrupted。旧的 queued、waiting、success、cancelled 和 error 仍为兼容状态。

无障碍与安全

摘要中的动作名称和状态不能只靠颜色或图标表达。运行时使用 aria-busy,等待授权时把焦点送到真实按钮,完成后用一条礼貌型状态播报结果。渲染前必须移除令牌、Cookie、密钥和用户隐私;复制动作只复制已经脱敏的可见输出。