CLI Agent 不是另一套系统。它是一个 Yao Agent,只是多加了一个文件:`sandbox.yao`。
## 唯一的区别
在 Yao Agent 中,框架调用 `executeLLMStream` —— LLM 处理消息并返回补全结果。在 CLI Agent 中,同一套框架改为调用 `executeSandboxV2Stream` —— Claude Code 在容器内运行,处理消息,将输出流式传回。
```
Yao Agent:
Create Hook → [ executeLLMStream ] → Next Hook
↑
LLM(通过 connector)
CLI Agent:
Create Hook → [ executeSandboxV2Stream ] → Next Hook
↑
容器内的 Claude Code(Runner)
```
其余一切不变:
- Hook 函数签名完全相同(`Create`、`Next`)
- `ctx.memory.*`、`ctx.mcp.*`、`ctx.agent.*`、`ctx.llm.*` 均可使用
- MCP 工具、提示词预设、委托 —— 全部一样
- Next Hook 中的 `payload` 结构相同
## 激活方式
框架在助手加载时检测 `sandbox.yao`:
```
assistants/my-agent/
├── package.yao ← 不需要 sandbox 字段
├── prompts.yml ← 可选(成为 Claude Code 的 system prompt)
├── sandbox.yao ← 该文件激活 CLI Agent 模式
└── src/
└── index.ts
```
若 `sandbox.yao` 存在,框架将:
1. 初始化 Computer(容器或宿主机)
2. 调用 `Runner.Prepare()` —— 复制 Skills、执行 prepare 步骤、写入 MCP 配置
3. 运行 **Create Hook**(与 Yao Agent 相同)
4. 调用 `Runner.Stream()` 替代 `LLM.Stream()`
5. 运行 **Next Hook**(与 Yao Agent 相同)
6. 调用 `Runner.Cleanup()` —— 终止进程,清理会话状态
## Runner 接口
Runner 是封装 Claude Code 的插件,实现三个方法:
```
Runner.Prepare(computer, config) → 准备环境(安装工具、复制文件)
Runner.Stream(messages, handler) → 运行 Claude Code,将输出流式传回
Runner.Cleanup(computer) → 终止进程,清理会话状态
```
`Runner.Stream` 接收的 `completionMessages` 与 LLM 收到的完全相同 —— 即 system prompt 加上完整的对话历史。Claude Code 通过这些消息理解任务。
当前可用的 Runner 是 `claude`(同时注册为 `claude` 和 `claude/cli`)。
## 什么时候用 CLI Agent
当任务需要给 Agent 对计算机环境的广泛自主控制权时,添加 `sandbox.yao`:
- **Computer Use** —— Agent 需要操作桌面、浏览器或 GUI 应用
- **沙箱隔离** —— 执行过程必须被隔离,Agent 不能触碰宿主系统
- **充分授权** —— Agent 需要自由安装包、执行任意命令、修改文件系统,并且可以安全地"犯错"
- **SKILL 生态** —— 可复用能力包,封装专项多步工作流
框架目前支持 `claude` Runner(Claude Code),未来版本将支持更多 Runner。
## 下一步
为你的助手添加 `sandbox.yao`。
→ **[沙箱配置](./sandbox)**