logo

一文讲清AI Agent核心概念与最小系统搭建

作者:半吊子全栈工匠2026.11.18 11:21浏览量:1

简介:本教程面向开发者,讲清模型、工具与Agent的区别,拆解Scaffolding、Harness、Context Engineering与Policy的分工,并给出工具定义、循环控制和结果验证的完整步骤。读完后,你可以搭建一个带停止条件与权限约束的最小Agent,并掌握常见问题的排查方法与安全检查要点。

一、概念与术语边界

本文中的Scaffolding、Harness和Skill是为讲解而做的简化定义,并非所有框架通用的标准术语。读者在其他框架中会遇到类似概念,大致对应关系如下:Scaffolding相当于规划与提示词编排层,Harness相当于运行时与工具执行器,Skill相当于一组打包好的提示词与工具。这种对应只在概念层面成立,具体实现以所用框架的文档为准。

大语言模型每次调用彼此独立,不保存记忆,也不会主动循环执行。Agent由模型加外围系统组成。模型负责决策,工具负责执行动作,存储模块负责保存跨轮次状态,日志模块负责追踪过程。

一个可运行的Agent包含四个要素:目标、规划、工具和反馈。目标是闭环停止的依据。规划是模型对当前这一步的决定。工具是可被调用的外部能力,例如读文件、查数据库、执行代码。反馈是工具返回的结果,它会作为下一轮的输入。

二、四个模块的分工

Scaffolding负责”怎么想”。 它拆解任务,判断当前是否需要调用工具、调用哪个工具,并约定模型每轮的输出结构。输出结构通常包含动作类型、工具名称、参数和理由,便于程序解析。

Harness负责”怎么跑”。 它注册工具、校验参数、在隔离环境中执行、设置超时与有限重试,并统一返回格式。模型给出的参数不能直接信任,所有动作都必须先经过Harness校验。

Context Engineering负责”模型看到什么”。 每轮上下文通常包括系统指令、原始目标、最近几轮的动作与结果、历史摘要和工具返回的关键信息。上下文需要设定token预算。例如,可以把系统指令控制在800个token内,目标300个token,最近三轮2000个token,历史摘要1000个token,检索结果2000个token,并预留一部分空间给模型输出。超出预算时,先把旧轮次压缩为摘要,再丢弃优先级较低的检索结果。

Policy负责”允许做什么”。 它定义动作白名单、高风险操作的人工确认规则、重试次数和终止条件。Policy必须在Harness层强制执行。只写在提示词里的规则属于软约束,模型可能忽略。

Scaffolding与Harness之间建议用结构化字段交互,常用字段包括:action(动作类型)、tool(工具名)、args(参数)、reason(理由)、observation(执行结果)、status(成功或失败)和error_code(错误码)。

三、最小系统搭建步骤

下面以”读取指定目录下的日志文件,统计错误类型并生成摘要”为例,完整走一遍搭建流程。该流程可以迁移到其他任务。

步骤一:明确目标与边界

做什么: 用一句话写出目标,并列出输入、输出、完成条件和失败条件。例如:输入是logs/目录下的.log文件,输出是包含错误类型与出现次数的表格,完成条件是表格通过验证。

为什么做: Agent在闭环中运行,如果没有明确的完成条件,它可能反复尝试而无法停止。

注意什么: 同时列出禁止事项,例如不得修改原始日志、不得访问logs/之外的路径。这些约束之后要落实为Policy规则。

步骤二:设计工具清单

做什么: 为每个工具定义名称、用途说明、参数结构、返回格式和错误码。下面是read_file工具的定义示例:

  1. {
  2. "name": "read_file",
  3. "description": "读取允许目录内的一个文本文件并返回内容。只读,不修改文件。",
  4. "parameters": {
  5. "type": "object",
  6. "properties": {
  7. "path": {"type": "string", "description": "相对于工作目录的路径,例如 logs/app.log"},
  8. "max_bytes": {"type": "integer", "minimum": 1, "maximum": 262144, "default": 65536}
  9. },
  10. "required": ["path"],
  11. "additionalProperties": false
  12. },
  13. "returns": {
  14. "type": "object",
  15. "properties": {
  16. "content": {"type": "string"},
  17. "truncated": {"type": "boolean"}
  18. }
  19. },
  20. "errors": ["INVALID_ARGUMENT", "PATH_DENIED", "FILE_NOT_FOUND", "TIMEOUT"]
  21. }

为什么做: 模型只能输出调用意图,能否执行取决于工具定义。模型主要依靠description选择工具,描述模糊会导致误调用。additionalProperties设为false,可以拒绝模型编造的多余参数。

一次完整调用示例: 模型输出动作:

  1. {"action": "tool_call", "tool": "read_file", "args": {"path": "logs/app.log"}, "reason": "需要先获取日志内容"}

Harness依次检查工具是否存在、参数是否符合Schema、路径是否在白名单内(先做realpath解析,拒绝”..”和越界的符号链接),然后在10秒超时内执行。执行成功后返回:

  1. {"status": "ok", "observation": {"content": "2026-11-18 ERROR ...", "truncated": false}, "error_code": null}

如果模型请求的是”../../etc/passwd”,Harness返回PATH_DENIED。这个错误也要作为observation回传给模型,让它调整策略,而不是直接让整个任务崩溃。

步骤三:设计循环与停止条件

做什么: 写出主循环,并为每种退出情况设定明确条件。

  1. state = {"goal": GOAL, "history": [], "step": 0, "started_at": now()}
  2. while True:
  3. if state["step"] >= MAX_STEPS: # 建议10到20步
  4. return fail("STEP_LIMIT")
  5. if now() - state["started_at"] > MAX_SECONDS:
  6. return fail("TIMEOUT")
  7. decision = model.decide(build_context(state))
  8. if decision["action"] == "finish":
  9. return verify(state, decision) # 进入结果验证
  10. result = harness.execute(decision) # 校验、执行、截断
  11. state["history"].append({"decision": decision, "result": result})
  12. state["step"] += 1
  13. audit_log(state, decision, result)

停止条件包括:结果通过验证(成功);达到步数或时间上限;同一工具带相同参数连续调用三次以上;连续三次出现错误;高风险操作被人工拒绝。

为什么做: 循环没有上限,遇到模型误判时成本和风险会不断累积。上限和去重检查是最简单、最有效的保护。

步骤四:配置上下文与Policy

做什么: 把步骤一中的禁止事项转为可执行的规则,由Harness检查。

  • 白名单:只允许读取logs/目录。
  • 禁止删除与覆盖原始文件。
  • 写入report/目录的操作需要人工确认。
  • 每次写操作前,先把原文件复制到backup/目录,文件名带时间戳。
  • 写入失败时,用备份文件恢复,并记录回滚结果。
  • 审计日志保存时间、用户、工具名、参数摘要、写前与写后的校验和、执行结果。日志中的敏感字段需要脱敏。

为什么做: 写操作是最难逆转的环节。备份、确认和回滚能把误操作的影响限制在可恢复的范围内。沙箱提供的最小权限是另一层保护,两者配合使用。

步骤五:执行反馈与结果验证

做什么: 每个动作的结果都要进入history,供下一轮决策使用。任务结束后,按规则验证结果:

  1. 输出表格的格式是否符合约定。
  2. 错误类型的次数之和,是否与脚本对同一文件的独立统计结果一致。抽样对比即可,不必全量比对。
  3. 表格中是否出现日志里不存在的错误类型。

验证失败时,把失败原因作为observation交回模型,允许最多一次修正。仍然失败则终止,并输出失败原因。

为什么做: 模型说”完成了”并不等于完成了。独立验证才能证明结果可信。

四、常见问题排查与优化

问题 定位信号 优化动作
重复调用 同一工具与同一参数连续出现,history中重复记录 加入去重检查,把”已尝试”信息写入上下文,超过阈值后终止
参数校验失败 error_code为INVALID_ARGUMENT的次数增多 在description中给出参数示例与取值范围,错误信息中指出具体字段
超时与重试 TIMEOUT次数上升,任务耗时明显变长 限制max_bytes,拆分大文件,只对幂等操作重试,最多两次并采用指数退避
上下文溢出 模型忘记早期目标,token接近上限 把旧轮次压缩为摘要,每轮重新注入目标,检索结果按优先级截断
越权访问 PATH_DENIED频繁出现,或审计日志中出现白名单外的路径 检查realpath与符号链接,收紧白名单,对越权请求告警

排查时先看执行轨迹,再看提示词。每一步的动作、参数、observation和error_code都应可以回放。没有轨迹,就无法判断问题出在决策、工具还是权限。

优化时建议先用一小批样本评估,记录每次运行的步数、工具调用次数、token成本和成功率。只有数据表明瓶颈所在,才调整提示词或工具。

五、安全检查表

  • Agent运行在与生产环境隔离的沙箱中,没有生产凭证。
  • 密钥通过环境变量或密钥管理服务注入,不写入代码、提示词或日志。
  • 所有工具参数经过JSON Schema校验,拒绝多余字段。
  • 文件路径经过realpath解析并与白名单比对。
  • 设置了步数、时间和成本上限。
  • 写操作有写前备份、人工确认和失败回滚。
  • 审计日志记录每一步的动作、参数摘要和结果,并已脱敏。
  • 高风险动作在执行前需要人工确认。

完成这份检查表,最小Agent就具备了可控的运行边界。它的能力仍然有限,后续再根据实际任务逐步扩展工具和权限。

发表评论

活动