AI Agent 开发实战：从核心概念到落地代码

真正的 ReAct 循环更灵活一些，它不提前制定完整计划，而是每步动态决策。下面是 ReAct Agent 的核心逻辑：

class ReActAgent:
    def run(self, task):
        context = f"任务：{task}\n"
        for i in range(self.max_iterations):
            thought = self._think(context)
            if "任务完成" in thought or "Final Answer:" in thought:
                return self._extract_answer(thought)
            action, action_input = self._decide_action(thought)
            observation = self._observe(action, action_input)
            context += f"\n思考：{thought}\n行动：{action}({action_input})\n观察：{observation}"

_think 询问模型下一步该做什么，_decide_action 让模型选出工具和参数，_observe 实际执行工具并返回结果。如果模型认为任务完成，它会在思考里包含「任务完成」字样，循环结束。

我把完整的代码放后面供参考，现在先看看架构。

架构分层：抽象也不是白给的

做 Agent 时，我会画一张分层图来理清依赖。大致是这样：

┌─────────────────────────────────────────┐
│ 应用层 (Application)                      │
├─────────────────────────────────────────┤
│ Agent 层 (智能体)                        │
├─────────────────────────────────────────┤
│ 工具层 (Tools)                           │
├─────────────────────────────────────────┤
│ 模型层 (LLM)                             │
├─────────────────────────────────────────┤
│ 基础设施层 (Infrastructure)               │
└─────────────────────────────────────────┘

• 应用层：负责接收用户指令、展示结果、处理异常 UI。最早做原型时我最爱忽略这层，结果连错误都看不见。
• Agent 层：核心调度者。它理解意图、规划步骤、协调工具。大多数逻辑都在这。
• 工具层：具体执行能力。每个工具要定义清楚自己能处理什么（can_handle），免得 Agent 乱调。
• 模型层：LLM 本身。选模型时，推理能力强比速度快更重要——除非你只做简单分类。
• 基础设施：向量数据库、API 网关、监控等。小项目可以暂时不管，但上线前必须补上。

实施：从小场景开始，别急着自动化一切

找对第一个场景
最容易踩的坑是想一步到位。我看到太多项目试图用 Agent 搞定整个客服流程，结果连边界都没划清楚。好的做法是挑一个明确、高重复、低风险的任务：比如自动整理电子发票、生成周报、或提取合同关键字段。

提示词是 Agent 的灵魂
都说 prompt engineering 重要，但放到 Agent 里，它定义了整个 Agent 的行为边界。角色定义、能力描述、输出格式、何时停止——每一点都会影响执行效果。我的习惯是先在 playground 里反复调试，再把最终版写进代码。

建立评估体系
别等到上线再看效果。我一般会准备几十条测试用例，每次改完 prompt 或工具就跑一遍。重点关注三个指标：

• 成功率：任务是否按预期完成？
• 步数 / 耗时：是不是绕了太多弯路？
• 输出质量：结果可以直接用吗？还是需要人工二次处理？

一个简单的评估脚本可以这样：

def evaluate_agent(agent, test_cases):
    metrics = {'success_rate': 0, 'avg_time': 0, 'avg_steps': 0}
    for case in test_cases:
        start = time.time()
        result = agent.execute(case['task'])
        elapsed = time.time() - start
        steps = len(agent.memory)
        success = (result == case['expected'])
        # 记录计算...
    return metrics

成本控制
很多人担心 LLM 调用成本。确实，ReAct 循环会让 token 消耗飙升。我的经验：先用便宜的小模型跑通流程（比如 GPT-3.5 或 Qwen），再根据效果决定是否升级。优化提示词、加缓存、合并相似步骤也能省不少。

两个案例：一次成功，一次翻车

文档处理 Agent（成功案例）
某团队每天需要把数百份技术文档分类、摘要、归档。他们开发了一个 DocumentAgent，流程是：读取文件 → 分类 → 摘要 → 索引。每个文档调四次 LLM，但有明确的步骤和工具。上线后，处理时间从 4 小时降到 30 分钟，准确率从 70% 提到 95%。关键成功因素：场景边界清晰，每步可验证，有专门的失败重试逻辑。

「自动一切」项目（失败教训）
另一家公司想用 Agent 完全替代人工审核流程，结果需求模糊、Agent 权限过大、没有兜底机制。用户期望太高，一旦出错就失去信任。最后项目叫停。教训很明显：别为了 AI 而 AI；Agent 不是万能工，一定要有明确的能力边界和人工干预入口。

常见问题

怎么选模型？
简单任务（分类、格式转换）用小模型，省钱又快。复杂推理（多步规划、代码生成）用 GPT-4 或 Claude。如果数据敏感，本地部署 LLaMA 或 Qwen 也是现实选择。

Agent 效果怎么衡量？
多人多维评估：自动化指标（成功率、耗时）加上人工抽检。长远看，用户满意度最重要，但前置指标可以帮你快速迭代。

安全怎么保障？
最小权限原则：Agent 能调用的工具越少越好。输入输出要过滤，防注入。敏感操作（删文件、发邮件）必须二次确认。所有动作记录日志，方便回溯。

趋势与个人判断

未来一两年，多模态 Agent（图文一起处理）和端侧部署（手机、IoT）会逐渐成熟。再往后，完全自主的 Agent 可能需要三到五年。不过我更看重的是工具链成熟度——现在 LangChain、AutoGPT 等框架让开发门槛降低，但抽象泄漏也常常发生，理解底层原理仍然能救命。

我自己在用的学习路径：先花一周弄懂 ReAct 循环和工具调用，再拿一个真实小任务动手实现，最后读几篇经典论文（ReAct、Toolformer）。这样半年下来，基本能独立设计中等复杂的 Agent 了。

附录：完整示例代码

下面是前面提到的两个 Agent 类的完整实现，包括工具基类和 Mock LLM，方便你直接跑起来。

# 工具基类
class Tool:
    name = "base_tool"
    def execute(self, input_data):
        raise NotImplementedError
    def can_handle(self, task):
        return False

class FileTool(Tool):
    name = "file_tool"
    def execute(self, input_data):
        return f"文件操作完成：{input_data}"
    def can_handle(self, task):
        return "文件" in task or "file" in task.lower()

class WebTool(Tool):
    name = "web_tool"
    def execute(self, input_data):
        return f"网络请求完成：{input_data}"
    def can_handle(self, task):
        return "搜索" in task or "网页" in task or "web" in task.lower()

class DefaultTool(Tool):
    name = "default"
    def execute(self, input_data):
        return f"默认处理：{input_data}"

class MockLLM:
    def generate(self, prompt):
        if "思考" in prompt:
            return "我需要先搜索相关信息"
        elif "选择" in prompt:
            return "工具：web_tool\n参数：搜索 AI Agent"
        return "处理完成"

# 基础执行框架
class AIAgent:
    def __init__(self, llm, tools=None):
        self.llm = llm
        self.tools = tools or []
        self.memory = []

    def execute(self, task):
        understanding = self._understand(task)
        plan = self._plan(understanding)
        results = []
        for step in plan:
            result = self._execute_step(step)
            results.append(result)
            if not self._verify(result):
                plan = self._replan(step, result)
        return self._summarize(results)

    def _understand(self, task):
        prompt = f"分析以下任务的核心目标：{task}"
        return self.llm.generate(prompt)

    def _plan(self, understanding):
        prompt = f"为以下目标制定执行计划：{understanding}"
        plan_text = self.llm.generate(prompt)
        return self._parse_plan(plan_text)

    def _execute_step(self, step):
        tool = self._select_tool(step)
        result = tool.execute(step)
        self.memory.append({'step': step, 'tool': tool.name, 'result': result})
        return result

    def _verify(self, result):
        return result.get('success', False)

    def _replan(self, failed_step, result):
        prompt = f"步骤'{failed_step}'执行失败，结果：{result}，请调整计划"
        new_plan = self.llm.generate(prompt)
        return self._parse_plan(new_plan)

    def _summarize(self, results):
        prompt = f"总结以下执行结果：{results}"
        return self.llm.generate(prompt)

    def _parse_plan(self, plan_text):
        return [line.strip() for line in plan_text.split('\n') if line.strip()]

    def _select_tool(self, step):
        for tool in self.tools:
            if tool.can_handle(step):
                return tool
        return DefaultTool()

# ReAct Agent
class ReActAgent:
    def __init__(self, llm, tools):
        self.llm = llm
        self.tools = {tool.name: tool for tool in tools}
        self.max_iterations = 10

    def run(self, task):
        context = f"任务：{task}\n"
        for i in range(self.max_iterations):
            thought = self._think(context)
            if "任务完成" in thought or "Final Answer:" in thought:
                return self._extract_answer(thought)
            action, action_input = self._decide_action(thought)
            observation = self._observe(action, action_input)
            context += f"\n思考：{thought}\n行动：{action}({action_input})\n观察：{observation}"
        return "达到最大迭代次数，任务未完成"

    def _think(self, context):
        prompt = f""" {context} 请思考下一步应该做什么。如果任务已完成，请回答"任务完成：[结果]" """
        return self.llm.generate(prompt)

    def _decide_action(self, thought):
        prompt = f"根据思考'{thought}'，选择要执行的工具和参数"
        response = self.llm.generate(prompt)
        return self._parse_action(response)

    def _observe(self, action, action_input):
        if action in self.tools:
            return self.tools[action].execute(action_input)
        return f"未知工具：{action}"

    def _extract_answer(self, thought):
        return thought.split("任务完成：")[-1].strip()

    def _parse_action(self, response):
        lines = response.strip().split('\n')
        action = "default"
        action_input = ""
        for line in lines:
            if "工具：" in line or "tool:" in line.lower():
                action = line.split("：")[-1].strip()
            if "参数：" in line or "input:" in line.lower():
                action_input = line.split("：")[-1].strip()
        return action, action_input

可以直接运行，把 MockLLM 替换成真实 API，再挂上你自己的工具，就能开始试验了。

参考资料：

• ReAct: Synergizing Reasoning and Acting in Language Models (2023)
• Toolformer: Language Models Can Teach Themselves to Use Tools (2023)
• AutoGPT: https://github.com/Significant-Gravitas/AutoGPT
• LangChain 文档：https://python.langchain.com