agent">从原理到落地：150 行代码构建 AI Agent

一、范式迁移：从“怎么实现”到“定义目标”

软件开发的重心正在发生一次静默但深刻的转移。过去几十年，工程师的主要精力花在“怎么实现”上——选择数据结构、设计接口、编写控制流。而在以大语言模型（LLM）为基础设施的新阶段，越来越多的工作前移到“定义目标”：把意图描述清楚，把可用能力声明清楚，剩下的执行路径交给模型去规划。

AI Agent 正是这一转移过程中第一个具备完整工程形态的实体。可以用一个类比来建立直觉：LLM 是一位知识渊博但足不出户的专家，它能推理、能生成、能解释，却无法主动触碰外部世界；Agent 则是给这位专家配上了手脚与记事本，让它能跑腿、能查资料、能动手验证，并在任务结束后留下记录。

理解这个类比的关键，是看清被动式对话模型的边界：你问，它答；对话结束，上下文即失；它不会主动读取文件、不会执行代码、不会操作外部系统。Agent 要做的，就是补齐这三块短板。

二、核心公式：四要素缺一不可

业界对 Agent 的架构已形成较为一致的抽象，可以写成一条公式：

AI Agent = LLM（大脑） + Planning（规划） + Memory（记忆） + Tools（手脚）

四个要素各自承担明确职责：

• LLM（大脑）：负责语义理解、推理决策与自然语言生成，是整个系统的调度中枢。
• Planning（规划）：把模糊的用户目标拆解为可执行的步骤序列，并在执行受阻时重新规划。简单实现可以是“单步决策 + 循环”，复杂实现则引入任务分解、反思与重试策略。
• Memory（记忆）：分为短期记忆（当前会话的消息与中间结果）与长期记忆（跨会话沉淀的知识、偏好、历史结论）。没有记忆的 Agent 每次都是从零开始，无法完成多轮递进的任务。
• Tools（手脚）：外部能力的统一抽象，让模型可以读写文件、执行代码、检索信息、调用业务接口。

这四者不是玄学概念，而是可以逐层落到代码上的工程结构。其中，连接“大脑”与“手脚”的关键机制，就是 Function Calling。

三、Function Calling：让模型学会“调用”

Function Calling 的工作流程可以概括为三步：

1. 开发者向 LLM 提供一组工具的“说明书”，通常是以 Schema 形式描述的工具名称、用途、参数结构；
2. LLM 根据当前对话上下文，判断是否需要调用工具、调用哪一个、传什么参数，并以结构化输出返回决策；
3. 宿主程序解析该决策，真正执行对应函数，把执行结果回填给 LLM，进入下一轮推理。

值得注意的是，模型本身并不执行任何函数，它只输出“意图与参数”。真正的执行权始终在开发者手中，这也正是安全边界与权限控制的落点。

一个最小可用的工具清单大致如下（示意性结构）：

TOOLS = [
    {"name": "read_file",        "description": "读取指定路径的文件内容"},
    {"name": "write_file",       "description": "向指定路径写入内容"},
    {"name": "list_directory",   "description": "列出目录下的文件与子目录结构"},
    {"name": "execute_python",   "description": "在沙箱中执行一段 Python 代码片段，而非文件路径，超时 10 秒"},
    {"name": "search_code",      "description": "在代码库中递归搜索关键词并返回匹配位置"},
]

围绕这组工具，Agent 的主循环可以用百余行代码完成：维护消息历史、调用模型、解析工具调用请求、执行工具、把结果追加回上下文、判断是否继续。代码量本身不是重点，重点在于循环中的每一环都对应前面公式里的一个要素。

四、一个反直觉的发现：工具描述比工具逻辑更重要

实践中有一个容易被低估的现象：工具描述的质量，往往比工具本身的实现更能决定 Agent 的可靠性。

以代码执行工具为例。如果描述只写“执行代码”，模型在某些上下文中会把文件路径当作参数传进来，期待工具自己去读取文件；而工具的语义其实是“执行一段代码片段”。加上限定语“执行代码片段，而非文件路径”之后，调用错误率会明显下降。

这类问题的根源在于：模型对工具的理解完全来自描述文本，描述模糊，决策必然漂移。给 LLM 写工具描述，本质上是在给一位新同事写操作手册——需要说明它做什么、不做什么、参数是什么格式、边界在哪里、失败时返回什么。越具体，误用越少。

几条可复用的撰写原则：

• 明确输入形态：参数是路径、是代码文本、是关键词，必须在描述中点明；
• 声明边界：写清楚工具不负责什么，避免模型越界使用；
• 描述返回结构：让模型知道执行结果长什么样，便于它决定下一步；
• 控制粒度：工具过粗则模型难以组合，过细则调用轮次膨胀，需要在两者间取平衡。

五、工程落地的几个关键约束

把 Agent 从示例推进到可用，还需要正视若干工程约束。

权限与沙箱。工具是 Agent 接触真实世界的通道，必须默认最小权限。代码执行应运行在隔离环境中并设置超时；文件写操作应限制在指定工作目录内；涉及外部系统的调用应经过鉴权与审计。

上下文管理。多轮工具调用会迅速膨胀消息历史，需要截断、摘要或外置存储策略，否则既影响成本也影响决策质量。这正是 Memory 要素从概念走向实现的场景。

可观测性。每一次模型决策、每一次工具调用及其返回，都应被完整记录。Agent 的失败往往不是单点错误，而是决策链条中的逐步偏移，缺少轨迹就无从调试。

失败处理。工具可能超时、可能返回异常、可能给出空结果。Agent 需要具备识别失败并重试或改道的能力，而不是把错误原样抛给用户。

六、结语

AI Agent 并不神秘，它是一条清晰的工程公式：一个负责决策的模型，一套负责执行的工具，一层负责延续的记忆，以及一个负责拆解目标的规划循环。把这条公式落到代码上，百余行即可跑通；把它落到生产上，则需要在描述质量、权限边界、上下文与可观测性上持续投入。理解了这四要素与它们之间的连接方式，就掌握了从被动对话走向主动执行的那把钥匙。