agent/docs/01-agent-principles.md

Agent Principles

Working Definition

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

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

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	执行高风险外部操作	权限分层、确认、回滚方案