---
title: "Agent 总览"
description: "基于 Cursor 官方 Agent 文档解释 instructions、tools、model、checkpoints、queue 和模式选择。"
verifiedAt: "2026-05-09"
---

Cursor Agent 是能独立完成复杂编码任务的助手。官方文档说明，它可以编辑代码、运行 terminal commands、搜索代码库和 web，并围绕不同 frontier models 调整 instructions 和 tools。

学习 Agent 的关键不是“它能不能改代码”，而是理解三件事：它由 instructions、tools、model 组成；它会在任务中调用很多工具；它会用 checkpoints 和 queued messages 支撑更长的迭代。

> [!NOTE]
> **阅读目标**：读完本章，你应该能判断什么时候用 Agent、Ask、Plan、Debug，并知道 Agent 做任务时哪些证据必须审查。

## 1. Agent 的三个组成部分

官方 Agent 文档把 agent 拆成三部分。

| 组件 | 官方含义 | 你要控制什么 |
| --- | --- | --- |
| Instructions | system prompt（系统提示词，模型每次推理前看到的隐性指令）和 rules，指导 agent 行为 | 项目 rules、团队约束、任务边界 |
| Tools | 文件编辑、代码库搜索、terminal、browser 等 | 哪些工具可用，哪些要人工确认 |
| Model | 你为任务选择的 agent model | 复杂度、成本、上下文和速度 |

Cursor 会为不同模型调整 instructions 和 tools。用户不需要手工适配每个模型，但仍要定义任务边界和验收方式。

```mermaid
flowchart TD
  Goal["用户任务"] --> Agent["Cursor Agent"]
  Agent --> Instructions["Instructions / Rules"]
  Agent --> Tools["Tools"]
  Agent --> Model["Model"]
  Tools --> Search["Codebase / Web search"]
  Tools --> Edit["Read / Edit files"]
  Tools --> Terminal["Run shell commands"]
  Tools --> Browser["Browser screenshots / tests"]
  Edit --> Diff["Diff view"]
  Terminal --> Output["Command output"]
  Browser --> Evidence["Visual evidence"]
```

## 2. Tools 是 Agent 的工作手

官方列出的 tools 包括：

| Tool | 用途 |
| --- | --- |
| Semantic search | 在 indexed codebase 中按含义搜索 |
| Search files and folders | 找文件名、目录结构、关键词和 pattern |
| Web | 生成搜索查询并执行 web searches |
| Fetch Rules | 根据 type 和 description 获取相关 rules |
| Read files | 读取文本和图片文件，并把图片加入视觉模型上下文 |
| Edit files | 建议并应用文件编辑 |
| Run shell commands | 执行 terminal 命令并监控输出 |
| Browser | 控制浏览器截图、测试应用、验证视觉变化 |
| Image generation | 生成 UI mockup、产品素材或架构图 |
| Ask questions | 任务中提出澄清问题 |

官方还说明 Agent 一次任务中的 tool calls 没有数量上限。对真实项目来说，这意味着你不能只看最终回复，要看它到底读了什么、改了什么、跑了什么命令。

## 3. Checkpoints 是本地回退，不是 Git 替代

官方文档说明，Agent 会在重要改动前自动创建 checkpoints，保存 modified files 的状态。如果 Agent 走错，可以在 chat timeline 中点击 checkpoint 预览并 restore。

关键边界：

- Checkpoints 存在本地。
- 它们和 Git 分开。
- 只适合撤销 Agent changes。
- 永久版本管理仍然用 Git。

> [!IMPORTANT]
> Checkpoint 能帮你撤回 Agent 的一次错误方向，但不能代替 commit、branch、PR 和 code review。

## 4. Queued messages 和立即消息

官方文档说明，Agent 工作时可以排队后续指令：

| 操作 | 行为 |
| --- | --- |
| 输入下一条并按 Enter | 加入 queue，等当前任务完成后顺序执行 |
| 拖动 queued messages | 调整执行顺序 |
| `Cmd+Enter` | 立即发送，绕过 queue，追加到最近 user message |

实操上，排队适合“等当前小步骤结束后继续”。如果 Agent 已经走偏，用 Stop 或立即消息重定向，不要连续塞多个互相冲突的 queued messages。

<details>
<summary>深读：为什么 Agent 工具越多，任务边界越重要</summary>

Cursor Agent 可以搜索、读文件、改文件、跑命令、控浏览器、生成图片和提问。工具越多，它越容易把一个模糊目标扩展成一串副作用动作。

所以商业级 prompt 必须写目标、范围、允许工具、禁止动作和验收证据。比如“只读解释当前目录，不要修改文件”与“修复并运行测试”是完全不同的授权级别。
</details>

## 5. 模式选择

官方 Help Center 给出四种模式判断。

| Mode | Best for | Can edit files |
| --- | --- | --- |
| Agent | 构建功能、重构、修 bug | Yes |
| Ask | 理解代码、探索架构 | No |
| Plan | 复杂功能，先审方案 | Yes，审批后 |
| Debug | 需要运行时证据的疑难 bug | Yes |

切换方式：

- `Shift + Tab` 循环模式。
- Agent panel 的 mode picker dropdown。

官方提醒：每个 mode 使用自己的 context，切换模式会开启新的 context window；换任务最好开新 chat。

## 本章自检

完成本章后，用这 3 个问题检查自己是否真正理解：

1. Cursor Agent 的 instructions、tools、model 各自负责什么？
2. Checkpoints 和 Git 的边界是什么？
3. Ask、Agent、Plan、Debug 分别适合什么任务？

通过标准：你能给一个真实任务选择模式，并写清楚允许工具、回退方式和验收证据。

## 官方来源

- [Cursor Agent Overview](https://cursor.com/docs/agent/overview.md) —— 官方说明 Agent 三组件、tools、checkpoints 和 queued messages。
- [Cursor Agent Help](https://cursor.com/help/ai-features/agent.md) —— Help Center 说明 Agent mode、Ask / Plan / Debug、Restore Checkpoint 和模式切换。

## 接下来去哪

<Cards>
  <Card title="Plan Mode" description="较大任务先进入 Plan Mode，审查方案再构建。" href="/docs/cursor/official/01-agent-workflow/12-plan-mode" />
  <Card title="Agent Review" description="改完以后用 Agent Review 审查本地变更。" href="/docs/cursor/official/01-agent-workflow/15-agent-review" />
</Cards>
