# Agent Principles

## Working Definition

Agent 是一种能够围绕目标持续感知上下文、选择行动、调用工具、观察结果并调整下一步的系统。

它和普通 LLM 调用的差别不在于“会不会输出文本”，而在于是否形成了闭环：

```text
goal -> context -> plan -> action -> observation -> update -> next action
```

## Minimal Agent Loop

1. Understand the goal: 明确任务、约束和成功标准。
2. Build context: 收集当前状态、历史信息、可用工具和环境限制。
3. Decide next action: 选择回答、提问、调用工具、修改文件或停止。
4. Execute: 执行动作，并保留可观察结果。
5. Reflect: 对结果进行校验，决定继续、修正还是结束。

## Key Capabilities

### Planning

把目标拆成可执行步骤，并能在新信息出现后调整计划。

常见风险：

- 计划太细，导致执行僵硬。
- 计划太粗，导致遗漏验证。
- 计划没有退出条件，导致无效循环。

### Tool Use

工具让 Agent 能改变外部世界，例如读文件、发请求、操作浏览器、调用业务 API。

工具设计重点：

- 输入输出必须清晰。
- 错误要可恢复。
- 权限边界要显式。
- 高风险动作要有确认或审计。

### Memory

记忆不是越多越好，而是让 Agent 在正确时刻拿到正确上下文。

常见类型：

- Working memory: 当前任务上下文。
- Episodic memory: 历史任务和经验。
- Semantic memory: 稳定知识、术语、规则。
- Procedural memory: 操作流程和技能。

### Reflection and Verification

反思不是让模型空想，而是把输出和证据对齐。

有效验证包括：

- 运行测试或脚本。
- 检查 diff 和日志。
- 对比需求和结果。
- 使用独立评估器或基准集。

## Design Principles

### 1. Start From the Environment

Agent 的能力受环境限制。先搞清楚它能观察什么、能改什么、不能碰什么。

### 2. Make State Explicit

把任务状态、工具结果、决策理由和待办项显式化，减少隐式上下文丢失。

### 3. Prefer Narrow Reliable Tools

一个职责清楚、输出稳定的小工具，通常胜过一个权限很大但语义模糊的工具。

### 4. Separate Exploration From Commitment

读、查、模拟、评估属于探索；写文件、发消息、提交代码、执行交易属于承诺。两者的权限和日志要求不同。

### 5. Build Evaluation Early

Agent 系统失败经常不是因为没有能力，而是因为没有清晰的成功标准。先定义可观察指标，再谈优化。

## Common Failure Modes

| Failure | Symptom | Prevention |
| --- | --- | --- |
| Goal drift | 做着做着偏离用户目标 | 持续对照成功标准 |
| Tool hallucination | 调用不存在或参数错误的工具 | 使用结构化工具描述和校验 |
| Context loss | 忘记关键约束或历史决定 | 维护任务状态和摘要 |
| Over-planning | 长时间规划但不执行 | 设定下一步可验证动作 |
| Under-verification | 输出看起来对但没有证据 | 增加测试、日志和审阅 |
| Unsafe action | 执行高风险外部操作 | 权限分层、确认、回滚方案 |