现在构建一个 AI Agent，可以简单的使用一些 Code Agent SDK，比如Anthropic Claude Code，但想着作为一个技术人，还是要钻进去理解一些原理和概念，所以开始梳理一下完整的 AI Agent 构建体系。
理解 AI Agent
AI智能体是使用AI来实现目标并代表用户完成任务的软件系统。其表现出了推理、规划和记忆能力，并且具有一定的自主性，能够自主学习、适应和做出决定。
学习基础理论方面，先理解现阶段一个完整闭环的 AI Agent 的行为设计i模式：
ReAct模式
Plan-and-Execute模式
Reflection模式
CodeAct模式
再理解一个完整闭环的 AI Agent 工程视角：
Agent = LLM Call + Tools Call + Context Engineering
解析下三个组成部分：
组成部分 | 本质 | 工程实现 |
|---|---|---|
LLM Call | 推理引擎 | API调用，LiteLLM统一封装 |
Tools Call | 行动能力 | Function Call / MCP / 代码执行 |
Context Engineering | 智能核心 | 提示词设计、记忆管理、上下文组织 |
设计模式
ReAct模式
ReAct 是很多 Agent 设计的起点。它最重要的一点，是把一件事说清楚了：模型不应该只负责给答案，它还应该决定自己下一步做什么。
所以任务不再是一次性生成，而是一个循环：
思考当前状态
决定下一步动作
执行动作
观察结果
再进入下一轮思考
核心思想：将推理(Reasoning)和行动(Acting)结合，弥补CoT缺少外部反馈的缺陷。
工作流程：
┌─────────────────────────────────────┐│ ReAct Loop ││ ││ Thought → Action → Observation ││ ↓ ↓ ↓ ││ 推理 执行工具 观察结果 ││ ││ [循环迭代直到任务完成] │└─────────────────────────────────────┘每次迭代的三步骤：
Reasoning：LLM分析当前状态，生成内部推理链，决定下一步行动
Acting：根据推理结果执行具体操作（调用工具、执行代码等）
Observation：观察执行结果，反馈用于下一轮思考
Plan-and-Execute模式
有些任务太复杂，不适合每一步都临时决策。
这时候就需要先做一个更高层的规划，再把执行拆开。
这个模式适合：
长链路的软件交付任务
需要多步协调的操作流程
任务结构相对稳定、可预判的场景
核心思想：先制定完整计划，再按步骤执行
工作流程：
Planning → Task1 → Task2 → Task3 → Summary结构化工作流，适合任务关系明确的长期任务对比ReAct：
特性 | ReAct | Plan-and-Execute |
|---|---|---|
决策方式 | 边做边想 | 先规划后执行 |
灵活性 | 高 | 低 |
适用场景 | 动态任务 | 结构化任务 |
动态调整 | 支持 | 较弱 |
Reflection模式
让 Agent 能自我修正，如果说 ReAct 解决的是“怎么动”，Plan-and-Execute 解决的是“怎么规划”，那 Reflection 解决的就是“怎么纠错”。
流程：
初始输出 → 自我评估 → 生成反馈 → 修正输出 → [迭代]CodeAct模式
CodeAct 是 ReAct 模式的进化。
核心思想：通过生成可执行Python代码统一行动空间
优势：
代码是解决问题的普适方法
Agent可以按需生成解决方案，不局限于预定义工具
2025年演进：Anthropic提出将MCP服务器作为代码API，Agent编写代码与MCP交互。
Agent 设计与实现原理
核心机制：思考-行动循环
Agent的本质是一个持续运转的认知循环。理解这个循环，就理解了Agent的全部。
用一个类比来解释：
想象你在组装一台复杂的机器，但手边只有一本说明书和一堆零件。你会怎么做？
看说明书，理解当前要做什么
找到需要的零件，动手组装
观察组装结果，发现问题就调整
继续下一步，直到完成
Agent的运转方式完全类似——只不过"说明书"变成了提示词和上下文信息，"零件"变成了工具和代码执行能力，"观察结果"变成了工具返回的输出。
循环的四个关键阶段
┌──────────────────────────────────────────────────────────┐│ ││ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││ │ 理解 │ ──→ │ 决策 │ ──→ │ 执行 │ ││ │ 上下文 │ │ 下一步 │ │ 工具 │ ││ └──────────┘ └──────────┘ └──────────┘ ││ ↑ │ ││ │ ↓ ││ │ ┌──────────┐ ││ │ │ 整合 │ ││ └──────────────────────────── │ 结果 │ ││ └──────────┘ ││ │└──────────────────────────────────────────────────────────┘阶段一：理解上下文
LLM接收所有已有信息：系统提示词、用户请求、历史对话、工具执行结果。这些信息构成了Agent的"记忆"——它当前知道的一切。
阶段二：决策下一步
基于理解，LLM判断当前状态，决定接下来要做什么：
如果任务已完成，直接返回结果
如果需要更多信息，调用查询工具
如果需要处理数据，执行代码
如果遇到问题，调整策略
阶段三：执行工具
根据决策，调用相应的工具：读文件、写文件、执行命令、运行代码。工具执行后返回结果。
阶段四：整合结果
将工具结果写入上下文，成为下一次"理解"的新信息。循环继续。
上下文的生命周期
上下文是循环中唯一持续存在、不断更新的元素：
初始状态││ [系统提示词] + [用户请求]│▼┌─────────────────────────────────────┐│ 上下文容器 ││ ││ 第1轮：加入工具执行结果 #1 ││ 第2轮：加入工具执行结果 #2 ││ 第3轮：加入工具执行结果 #3 ││ ... │ ││ 最终：完整对话历史 + 所有工具结果 │└─────────────────────────────────────┘上下文持续累积，让Agent"记住"之前的每一步。这也是为什么长任务需要控制迭代次数——上下文会越来越大，消耗更多资源。
终止条件：什么时候停止循环？
循环不会永远运行，有三种终止方式：
任务完成：LLM判断问题已解决，不再调用工具，直接返回文本答案
达到上限：设置最大迭代次数（如20轮），防止无限循环
错误中断：工具执行失败或API调用异常
实践写一个极简Agent
理解的 Agent 实现主要有5个模块：
1. 实现一个Agent Loop 循环驱动核心
2. Tools实现，定义四个基础工具函数
3. Tools注册，工具Schema定义
4. System Prompt，完成初始化提示词
5. 还需要一个入口（CLI入口），作为用户交互界面
第一部分：Agent Loop
MAX_TURNS = 20def agent_loop(user_message: str, messages: list, client: OpenAI) -> str:"""Agent Loop：while循环驱动LLM推理与工具调用"""messages.append({"role": "user", "content": user_message})tool_schemas = [t["schema"] for t in TOOLS.values()]for turn in range(1, MAX_TURNS + 1):--- LLM推理 ---response = client.chat.completions.create(model="deepseek-chat",messages=messages,tools=tool_schemas,)assistant_msg = response.choices[0].messagemessages.append(assistant_msg.model_dump())--- 判断是否完成 ---if not assistant_msg.tool_calls:return assistant_msg.content or ""--- 执行工具调用 ---for tool_call in assistant_msg.tool_calls:name = tool_call.function.nameargs = json.loads(tool_call.function.arguments)tool_entry = TOOLS.get(name)result = tool_entry["function"](**args) if tool_entry else f"[error] unknown tool: {name}"messages.append({"role": "tool","tool_call_id": tool_call.id,"content": result,})return "[agent] reached maximum turns, stopping."要点：
messages 列表是上下文容器，持续累积所有对话和工具结果
MAX_TURNS 防止无限循环，安全上限
tool_calls 为空表示任务完成，退出循环
第二部分：Tools实现
def shell_exec(command: str) -> str:"""执行shell命令"""result = subprocess.run(command, shell=True, capture_output=True, text=True, timeout=30)output = result.stdout + (f"\\\\n[stderr]\\\\n{result.stderr}" if result.stderr else "")return output.strip() or "(no output)"def file_read(path: str) -> str:"""读取文件内容"""with open(path, "r", encoding="utf-8") as f:return f.read()def file_write(path: str, content: str) -> str:"""写入文件"""os.makedirs(os.path.dirname(path) or ".", exist_ok=True)with open(path, "w", encoding="utf-8") as f:f.write(content)return f"OK — wrote {len(content)} chars to {path}"def python_exec(code: str) -> str:"""执行Python代码"""with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as tmp:tmp.write(code)tmp_path = tmp.nameresult = subprocess.run([sys.executable, tmp_path], capture_output=True, text=True, timeout=30)os.unlink(tmp_path)return result.stdout.strip() or "(no output)"这四个工具覆盖了Agent与外部世界交互的核心能力：
工具 | 能力边界 |
|---|---|
shell_exec | 操作系统层面：文件管理、进程控制、网络请求 |
file_read | 信息获取：读取代码、配置、日志 |
file_write | 信息输出：保存结果、创建文件 |
python_exec | 数据处理：计算、分析、转换 |
有了这四个工具，Agent就能完成绝大多数编程任务——因为它可以读取现有代码、编写新代码、执行代码验证结果。
第三部分：Tools注册
TOOLS = {"shell_exec": {"function": shell_exec,"schema": {"type": "function","function": {"name": "shell_exec","description": "Execute a shell command and return output.","parameters": {"type": "object", "properties": {"command": {"type": "string"}},"required": ["command"]},},},},"file_read": {"function": file_read,"schema": {"type": "function","function": {"name": "file_read","description": "Read file contents.","parameters": {"type": "object", "properties": {"path": {"type": "string"}},"required": ["path"]},},},},"file_write": {"function": file_write,"schema": {"type": "function","function": {"name": "file_write","description": "Write content to file.","parameters": {"type": "object","properties": {"path": {"type": "string"}, "content": {"type": "string"}},"required": ["path", "content"]},},},},"python_exec": {"function": python_exec,"schema": {"type": "function","function": {"name": "python_exec","description": "Execute Python code.","parameters": {"type": "object", "properties": {"code": {"type": "string"}},"required": ["code"]},},},},}Schema的作用：
Schema告诉LLM每个工具的"使用说明书"——工具名称、功能描述、参数要求。LLM根据这些信息决定何时调用、如何传参。
Schema遵循OpenAI Function Calling标准格式，所有主流LLM都支持这一格式。
第四部分：System Prompt
SYSTEM_PROMPT = """You are a helpful AI assistant with access to the following tools:1. shell_exec — run shell commands2. file_read — read file contents3. file_write — write content to a file4. python_exec — execute Python codeThink step by step. Use tools when needed. When complete, respond directly."""System Prompt的作用：
这是Agent的第一条"指令"，告诉它：
身份定位（AI助手）
可用能力（四个工具）
行动准则（按步骤思考，完成任务后直接回答）
System Prompt在每次LLM调用时都会携带，是上下文的固定组成部分。
第五部分：CLI REPL入口
def main():client = OpenAI(api_key=os.environ["DEEPSEEK_API_KEY"], base_url="")messages = [{"role": "system", "content": SYSTEM_PROMPT}]print("Agent ready. Type 'exit' to quit, 'clear' to reset.\\\\n")while True:user_input = input("You> ").strip()if user_input.lower() == "exit": breakif user_input.lower() == "clear":messages = [{"role": "system", "content": SYSTEM_PROMPT}]continuereply = agent_loop(user_input, messages, client)print(f"\\\\nAgent> {reply}\\\\n")用户交互设计：
exit 退出会话
clear 清空上下文，重新开始
支持多轮对话，上下文持续累积
运行方式：
export DEEPSEEK_API_KEY="sk-xxxxx"python agent.py好，至此就是一个简单的 Agent 框架闭环。
总结
Agent框架设计核心公式：
Agent框架设计 = Agent Loop + Context Engineering
Agent Loop本质是思考-行动循环：理解→决策→执行→整合，持续迭代直到任务完成。
上下文工程决定Agent智能程度——精心组织上下文信息，让LLM每次决策有足够好的"原材料"。
从极简版本入手，理解核心逻辑，再逐步叠加功能，后面再深入学习下去。
- END -
觉得有启发，帮忙分享、“在看”、关注，谢谢。
