AUTOGPT避坑指南：手写实现核心循环，避开90%新手入坑陷阱

官方文档里那些架构图看多了，脑子容易浆糊。AUTOGPT 最核心的逻辑其实就在那几十行代码里，但很多新手一上来就啃官方源码，结果在依赖地狱里打滚，连个简单的循环都跑不通。我当年踩过的坑，现在整理出来，直接教你怎么手写实现一个精简版的执行引擎。不追求功能全，只追求逻辑通。只要你理解了这套“感知-思考-行动-观察”的闭环，再去改官方代码，你会发现那些看似复杂的配置项，不过是把核心逻辑封装后的参数而已。

坑的现象：为什么你的 Agent 会死循环

很多人第一次跑 AUTOGPT，最大的感受不是“聪明”，而是“卡死”。控制台里疯狂打印 Thinking...，然后就是无限期的等待，或者反复执行同一个任务，比如反复搜索同一个关键词，或者反复创建同一个文件。

这种现象在技术社区里被称为“无限循环陷阱”。表面上看，是模型太笨，其实是因为上下文管理失控。AUTOGPT 的设计初衷是自主代理，它没有人工干预机制，全靠 LLM 根据历史消息判断下一步。如果你给的初始提示词（System Prompt）不够精确，或者历史消息的截断策略不对，LLM 就会陷入“局部最优解”的泥潭。

举个真实案例：我测试过一个自动写周报的场景。我让 Agent 读取上周的 Git Commit 记录，生成周报。结果它第一步读取了日志，第二步思考“我需要更详细的信息”，第三步又去读取日志，第四步再思考……就这样循环了二十多次，直到 Token 耗尽报错。

根本原因在于：LLM 缺乏对“当前状态”的明确感知。它不知道“我已经读取过了”，因为它看到的历史消息里，并没有显式的“已执行动作”标记。它只看到了输入和输出，没有看到状态机。

原理简述：核心闭环与状态机

要解决这个问题，必须理解 AUTOGPT 的核心执行循环。抛开官方那些复杂的配置，核心逻辑其实就是四个步骤的递归调用：

Thinking (思考)：LLM 根据当前目标和历史消息，决定下一步行动。
Action (行动)：执行具体的工具调用，如搜索、写文件、运行代码。
Observation (观察)：获取行动的结果，并将其格式化为文本。
Feedback (反馈)：将观察结果追加到历史消息中，回到步骤 1。

这里的关键在于状态管理。官方实现中，状态是隐式的，隐藏在消息列表里。而我们在手写实现时，最好显式地维护一个 State 对象，记录当前步骤、已执行的任务 ID、失败次数等。

为什么官方文档不直接讲这个？因为官方追求的是通用性，它把状态管理交给了 LLM 的上下文窗口。但对于生产环境，这种“黑盒”状态管理是不可控的。你需要像写传统代码一样，写出明确的判断逻辑。

权威参考：在构建这类自主代理时，我们可以参考 RFC 9110 (HTTP Semantics) 中关于幂等性（Idempotency）的设计思想。虽然那是针对 HTTP 协议的，但核心逻辑相通：任何操作都应该是幂等的，或者具有明确的副作用标记。如果你的 Agent 重复执行同一个“非幂等”操作（比如发邮件、扣款），后果是灾难性的。

正确写法对比：手写核心循环

下面对比两种实现方式。左边是常见的错误写法（伪代码，模拟新手逻辑），右边是稳健的手写实现核心。

错误写法：依赖 LLM 自我判断

# 错误示范：缺乏状态控制，容易死循环
def run_agent_error(goal, history):while True:# 每次都把整个历史发给 LLM，让 LLM 决定下一步prompt = f"Goal: {goal}\nHistory: {history}\nWhat to do next?"response = llm.generate(prompt)# 解析响应，假设返回 JSONaction = parse_json(response)# 执行动作result = execute_tool(action['tool'], action['args'])# 简单追加结果，没有终止条件history.append(f"Action: {action['tool']}, Result: {result}")# 这里没有任何判断，全靠 LLM 良心发现说"Done"if "Done" in response:break

问题点：

无终止保护：如果 LLM 没输出 "Done"，或者输出了错误格式，程序就挂了或死循环。
历史无限膨胀：history 列表会越来越大，导致 Token 成本飙升，且 LLM 注意力分散。
无重试机制：如果 execute_tool 失败，程序直接崩溃或忽略错误。

正确写法：显式状态机 + 截断策略

# 正确示范：显式状态控制，防止死循环
import json
import time
from dataclasses import dataclass, field@dataclass
class AgentState:goal: strhistory: list = field(default_factory=list)step_count: int = 0max_steps: int = 10  # 硬限制，防止无限循环last_action_hash: str = None  # 防止重复动作def run_agent_robust(goal):state = AgentState(goal=goal)while state.step_count < state.max_steps:state.step_count += 1# 1. 构建提示词，限制历史长度（只保留最近 N 轮）recent_history = state.history[-5:]  # 滑动窗口prompt = build_prompt(goal, recent_history, state)# 2. 获取 LLM 响应response = llm.generate(prompt, temperature=0.7)# 3. 解析与容错try:action = parse_json_safe(response)except Exception as e:# 解析失败，记录错误并尝试修正，而不是崩溃state.history.append("Error: Invalid JSON from LLM")continue# 4. 幂等性检查：防止重复执行相同动作action_hash = hash(str(action))if action_hash == state.last_action_hash:state.history.append("Warning: Repeating same action, skipping.")continuestate.last_action_hash = action_hash# 5. 执行动作try:result = execute_tool(action['tool'], action['args'])state.history.append(f"Step {state.step_count}: {action['tool']} -> {result}")except Exception as e:state.history.append(f"Step {state.step_count}: {action['tool']} -> FAILED: {str(e)}")# 6. 终止条件判断if action.get('status') == 'DONE':print("Agent Finished Successfully.")breakif state.step_count >= state.max_steps:print("Max steps reached. Stopping.")def build_prompt(goal, history, state):# 这里可以加入更复杂的提示工程技巧return f"""Goal: {goal}Current Step: {state.step_count}History:{chr(10).join(history)}Output strict JSON: {{"tool": "...", "args": {{}}, "status": "PENDING|DONE"}}"""

核心改进点：

max_steps 硬限制：无论 LLM 怎么想，最多跑 10 步。这是生产环境的底线。
滑动窗口：只取最近 5 条历史，避免上下文爆炸，同时强制 LLM 关注近期任务。
幂等性检查：通过哈希值检测重复动作。如果 LLM 又想去搜索同一个词，直接跳过。
容错解析：LLM 经常输出非标准 JSON，必须用 parse_json_safe 处理，而不是直接 json.loads。

复现与修复代码：从报错到稳定

假设我们运行上面的“错误写法”，遇到了死循环。如何快速定位并修复？

场景复现：运行 run_agent_error("Summarize this text", [])。控制台输出：

Thinking...
Action: search
Observation: Found 10 results...
Thinking...
Action: search
Observation: Found 10 results...
... (重复 100 次)

调试步骤：

打印历史长度：在循环内加 print(len(history))。你会发现它一直在增长。
打印 LLM 原始输出：把 response 打印出来。你会发现 LLM 一直在说“我需要更多信息”，但信息其实已经给它了。
检查提示词：看看 prompt 里是否明确告诉了 LLM“你已经搜索过了”。

修复方案：在提示词中加入状态摘要。

def build_prompt_with_state(goal, history, state):# 生成一个简短的状态摘要status_summary = f"Steps executed: {state.step_count}. Last tool: {state.last_action_hash}."return f"""Goal: {goal}{status_summary}Recent History:{chr(10).join(history[-5:])}IMPORTANT: If the task is complete, output status 'DONE'. Do not repeat the same action if the result is already in history."""

这个小小的改动，能解决 80% 的死循环问题。因为 LLM 有了“我已经做过什么”的明确记忆。

进阶技巧与避坑建议

工具输出的标准化 不要让 LLM 直接读取原始数据（比如一个 10KB 的 JSON）。在 execute_tool 里做预处理，把结果压缩成人类可读的摘要。错误：result = requests.get(url).json() -> 直接扔给 LLM。正确：result = summarize_json(requests.get(url).json(), max_length=500)。
温度参数（Temperature）的动态调整 在“思考”阶段，温度可以高一点（0.7-0.9），鼓励创造性。在“执行”阶段，如果涉及代码生成或文件写入，温度要低（0.2-0.4），确保稳定性。很多新手全程用 0.7，导致生成的代码语法错误频发。
异步与并发 AUTOGPT 的瓶颈往往不在 LLM，而在工具执行（比如网络请求、数据库查询）。使用 asyncio 改造 execute_tool，可以让 Agent 在等待网络响应时，依然能处理其他逻辑。注意：LLM 调用通常是串行的（因为依赖上一步结果），但工具执行可以并行。
日志与追踪 生产环境必须接入 LangSmith 或类似的追踪工具。不要只看控制台输出，要看每一步的 Token 消耗、耗时、LLM 的置信度。你会发现，有时候 Agent 卡住，是因为它在某一步思考了 30 秒，而你根本不知道它在干什么。
避免“万能提示词” 不要试图用一个 System Prompt 搞定所有场景。写周报的 Prompt，和写代码的 Prompt，逻辑重点完全不同。 写代码：强调语法正确、单元测试。 写周报：强调结构清晰、语气专业。分场景配置提示词，效果远好于一个“大而全”的提示词。