在深入之前，有必要了解 Yao Agent 是如何执行一次请求的。本页解释执行模型、完整目录结构，以及你将在三种模式中如何做出选择。
## 执行模型
每次 Agent 请求都经过以下流水线：
```
用户消息
│
▼
┌─────────────┐
│ Create Hook │ ← 可选的 TypeScript 函数，在执行器之前运行
└──────┬──────┘
│
▼
┌─────────────┐
│ 执行器 │ ← LLM / CLI Agent (OpenCode, Claude Code, Codex 等) / 你自己的代码
└──────┬──────┘
│
▼
┌─────────────┐
│ Next Hook │ ← 可选的 TypeScript 函数，在执行器之后运行
└──────┬──────┘
│
▼
响应
```
**执行器槽里放的是什么，决定了 Agent 的类型。** 两侧的 Hook 无论中间是什么，都使用同一套接口。
## 三种执行模式
### 模式一：LLM（OpenAI / Anthropic API 等）
默认模式。配置 `connector` 和 `prompts.yml`——LLM 负责所有推理和响应生成。
```
Create Hook → [ LLM (OpenAI / Anthropic API 等) ] → Next Hook
```
适合：对话助理、问答、内容生成——任何你希望由 LLM 主导响应的场景。
### 模式二：CLI Agent（OpenCode、Claude Code、Codex 等）
添加 `sandbox.yao` 文件，将一个基于 CLI 的编程 Agent 放入执行器槽。它在隔离容器中运行，拥有完整的文件系统访问权限。
```
Create Hook → [ CLI Agent (OpenCode, Claude Code, Codex 等) ] → Next Hook
```
适合：代码生成、文件操作、多步骤技术任务。这是能力最强的模式，也是大多数实际项目采用的模式。
### 模式三：Pure Hook（你的 TypeScript 代码）
写一个完全用 TypeScript 处理请求的 `Create Hook`——不涉及 LLM。使用 `ctx.Send()` 直接流式输出响应，然后 return 跳过执行器。
```
Create Hook → [ 你的 TypeScript 代码 ] → （无执行器，无 Next Hook）
```
适合：确定性逻辑、菜单路由、表单流，或任何不需要 AI 生成的响应。
---
三种模式共享同一套 Hook 接口，可以自由混合——例如在单个 `Create Hook` 里，将部分请求路由给 LLM，其他请求用纯代码处理。
## Assistant 目录结构
以下是一个完整 Assistant 目录可以包含的内容。除 `package.yao` 外都是可选的——按需添加，不必一开始就全部创建。
```
assistants/my-agent/
├── package.yao # 必须：名称、connector、权限、MCP 配置
├── prompts.yml # 默认系统提示词
├── prompts/ # 多套提示词预设（create.yml、edit.yml 等）
│ └── edit.yml
├── src/
│ └── index.ts # Hook：导出 Create 和 Next 函数
├── mcps/ # MCP 工具服务
│ ├── tools.mcp.yao # 工具服务定义
│ └── mapping/ # 工具参数 Schema
├── models/ # Agent 私有数据库模型（.mod.yao 文件）
├── pages/ # 对话时显示的 SUI 侧边栏页面
├── locales/ # 国际化文案
│ ├── en-us.yml
│ └── zh-cn.yml
├── tests/ # 测试用例
│ └── inputs.jsonl
│
└── sandbox.yao # ← 仅 CLI Agent 需要。这是 CLI Agent 与 LLM 模式
# 唯一的区别所在。
```
**LLM 模式和 CLI Agent 的目录结构完全相同，唯一区别是 `sandbox.yao`。**
## 选哪种模式？
| | Pure Hook | LLM | CLI Agent |
|---|---|---|---|
| **执行层** | 你的 TypeScript 代码 | LLM（OpenAI / Anthropic API 等） | OpenCode、Claude Code、Codex 等 |
| **适合场景** | 路由、确定性逻辑 | 对话、问答 | 代码、文件、SKILL 生态 |
| **需要 Sandbox** | 否 | 否 | 是 |
| **实际使用** | 混合进其他模式 | 轻量场景 | **大多数实际项目** |
**推荐学习路径：**
1. 从 **LLM** 模式开始——机制透明，代码量最少
2. 需要文件操作或 SKILL 生态时，转向 **CLI Agent**
3. 在任何需要确定性控制的地方加入 **Pure Hook**
## 为什么这样设计？
Yao Agent 基于一个简单的前提：AI 时代，万物皆 Agent。
每一个功能、每一个工作流、每一个业务流程——由定时任务、外部事件或用户触发，自主执行，完成后汇报结果。问题不在于"要不要"采用这个模型，而在于"如何在不失去控制的情况下"做到这一点。
这就是三模式设计的来源。
**AI 的输出本质上是非确定性的。** LLM 会漂移，CLI Agent 会做出意料之外的决策。如果不加约束，它们产生的输出难以验证、审计，也难以集成到现有系统。Hook 层——执行器之前的 `Create`，执行器之后的 `Next`——提供了一个一致的干预点：注入上下文、强制约束、验证输出、触发下游动作。AI 负责繁重的工作，你定义边界。
**真实应用不是单一模式的。** 一次对话可能需要 LLM 回答问题、CLI Agent 编写并测试代码、Pure Hook 检查权限或格式化响应——依次发生。因为三种模式共享同一套 Hook 接口，你可以自由组合：按意图路由、委托给专用 Agent、在需要确定性时回退到代码。
这是核心哲学：**笼子，而非动物。** 你决定运行什么、何时运行、输出什么。AI 强大——Yao 让它有用。
## 下一步
你现在已经理解了完整的执行模型，可以深入了：
- **[Yao Agent →](/tutorials/agent/yao-agent)** — 学习提示词、MCP 工具和 Hook，构建一个真实的助理
- **[CLI Agent →](/tutorials/agent/cli-agent)** — 如果你已准备好使用 Sandbox 和 SKILL 生态，直接跳到这里
