AI Agent架构详解:Model、Tool、Skill、Rules、Hooks与Harness
作者:JC2026.11.16 11:45浏览量:0简介:本文从系统设计和工程落地角度,梳理 AI Agent 中 Model、Tool、Skill、Rules、Hooks、Harness 六类核心组成。文章将说明它们各自解决的问题、协作方式、实施步骤、配置要点、验证方法及常见故障排查思路,帮助开发者、运维人员和技术负责人建立完整的 Agent 架构认知,并设计出更稳定、可控、可维护的任务执行系统。
agent-">一、教程目标:先建立完整的 Agent 认知框架
很多资料把“能调用工具的大模型”直接称为 Agent,也有资料把任务编排系统、工作流引擎或自动化助手称为 Agent。术语使用不统一,容易导致设计阶段出现误判:模型能力被当成系统能力,工具被误认为技能,规则又被混在提示词中,最终造成系统难以调试和维护。
本文要完成的目标是:从工程实现角度拆解一个 AI Agent 的基本组成,并说明这些组件如何协同完成任务。
适合阅读本文的人员包括:
- 希望理解 Agent 基础架构的开发者;
- 负责智能应用落地的技术负责人;
- 需要设计任务自动化流程的运维人员;
- 希望评估模型、工具调用和安全边界的企业用户;
- 正在使用云端模型服务、知识库、数据库或业务系统构建智能应用的团队。
需要先明确:Agent 不是一个单独的模型,也不是一段提示词,而是一个以模型为决策核心、由运行时环境负责执行和控制的完整系统。
二、核心定义:Agent 是持续推进任务的系统
普通对话通常是“输入一次、输出一次”。用户提出问题,模型生成回答,本轮交互基本结束。
Agent 的工作方式则不同。用户给出一个目标后,系统通常需要经过以下循环:
- 理解任务;
- 分析当前状态;
- 制定下一步行动;
- 调用工具或生成结果;
- 接收工具返回的信息;
- 判断任务是否完成;
- 如果未完成,继续规划和执行;
- 输出最终结果或请求人工确认。
可以将其抽象为:
目标输入↓任务理解与规划↓选择行动↓调用工具↓接收结果↓更新状态↓判断是否完成├─ 否:继续执行└─ 是:生成最终结果
这里最关键的特征不是“用了大模型”,而是系统具备持续推进任务的能力。模型负责推理和决策,运行时环境负责调度、执行、记录和约束。
三、六个核心概念分别解决什么问题
1. Model:负责理解、推理与决策
Model,也就是模型,是 Agent 的认知核心,主要承担以下职责:
- 理解用户意图;
- 提取任务中的关键参数;
- 对复杂目标进行拆解;
- 判断是否需要调用工具;
- 选择合适的工具和调用参数;
- 阅读工具返回结果;
- 根据中间结果调整下一步计划;
- 生成自然语言回复或结构化输出。
但模型本身通常不直接访问数据库、文件系统、网络服务或业务接口。它只能基于上下文生成文本或结构化决策,因此必须依赖外部执行环境完成真实操作。
模型的输出可以设计成类似下面的结构:
{"action": "调用工具","tool": "查询数据","arguments": {"condition": "指定条件"},"reason": "需要获取实时信息"}
实际系统中不一定使用完全相同的字段,但应尽量让模型输出具备明确的意图、动作、参数和终止状态。这样便于程序校验,也便于记录和排查。
模型选择时,不应只关注参数规模或单次回答效果,还要重点评估:
- 工具调用格式是否稳定;
- 是否能够遵守输出结构;
- 长上下文处理能力是否满足任务要求;
- 复杂任务中的规划能力是否足够;
- 对失败结果和异常信息的理解能力;
- 响应速度、调用成本和并发能力是否符合要求。
2. Tool:让 Agent 能够影响外部世界
Tool 是 Agent 可以调用的外部能力。模型只能“提出行动建议”,Tool 才能真正执行动作。
常见工具类型包括:
一个合格的工具定义至少应包含:
- 工具名称;
- 工具用途说明;
- 输入参数;
- 参数类型和是否必填;
- 返回结果格式;
- 失败时的错误信息;
- 权限和风险说明。
例如,工具描述可以采用通用结构:
{"name": "查询任务状态","description": "根据任务编号查询任务当前状态","parameters": {"task_id": {"type": "string","required": true,"description": "任务唯一标识"}}}
工具设计中最容易忽视的是“边界”。工具不应把过多复杂逻辑全部交给模型,也不应提供过于宽泛的能力。例如,“执行任意系统命令”虽然灵活,但会带来严重安全风险。更合理的做法是将能力拆分为有限、明确、可审计的操作。
对于有副作用的工具,例如删除数据、发送通知、修改配置,应增加:
- 参数白名单;
- 权限校验;
- 二次确认;
- 幂等控制;
- 操作审计;
- 超时和重试限制。
3. Skill:把多个动作封装成可复用能力
Skill 可以理解为面向任务的能力封装。它通常不是单个底层工具,而是一组工具、步骤、判断逻辑和输出规范的组合。
例如,“生成运营分析报告”可能包含:
- 查询数据;
- 清洗和聚合数据;
- 计算关键指标;
- 生成图表或表格;
- 编写分析结论;
- 保存报告;
- 返回访问信息。
如果每次都让模型从零规划这些步骤,容易出现遗漏、顺序错误或结果格式不一致。将其封装为 Skill 后,模型只需要判断“是否使用该能力”,具体流程由 Skill 负责。
Skill 通常包含以下内容:
- 能力名称;
- 适用场景;
- 输入要求;
- 执行步骤;
- 依赖工具;
- 输出格式;
- 异常处理方式;
- 权限要求;
- 成功判定条件。
可以采用如下伪配置:
skill:name: 生成分析报告purpose: 根据指定数据生成结构化报告inputs:- name: 时间范围required: true- name: 分析主题required: truesteps:- 查询相关数据- 校验数据完整性- 执行统计分析- 生成报告内容- 保存结果success_condition:- 数据查询成功- 报告内容完整- 保存操作成功
Skill 的价值在于复用和标准化。对于高频、复杂、对结果一致性要求较高的任务,优先使用 Skill,而不是让模型完全自由发挥。
4. Rules:限制 Agent 如何行动
Rules 是系统规则,用于约束模型和工具的行为。它解决的是“什么可以做、什么不能做、必须遵守什么流程”的问题。
规则可以分为几类:
行为规则
规定回答风格、任务边界和处理原则,例如:
- 不确定时必须明确说明;
- 不得编造未查询到的数据;
- 涉及敏感操作时必须请求确认;
- 任务失败后最多重试指定次数。
工具规则
规定工具调用方式,例如:
- 调用查询工具前必须校验参数;
- 只能访问授权范围内的数据;
- 写入操作必须记录操作原因;
- 不允许连续调用高风险工具。
数据规则
规定数据的处理方式,例如:
- 敏感字段不得直接输出;
- 外部输入必须经过格式校验;
- 结果需要标注数据来源和时间;
- 超出数据有效期时必须重新查询。
流程规则
规定任务执行顺序,例如:
身份确认 → 参数校验 → 数据查询 → 结果检查 → 执行动作 → 记录审计
Rules 不应只写成模糊的自然语言要求,还应尽可能转化为程序可检查的条件。例如“不能访问敏感数据”可以进一步落实为权限判断、字段过滤和审计记录。
四、Hooks:在关键生命周期节点插入控制逻辑
Hooks 是生命周期钩子,用于在 Agent 执行过程中的特定节点自动运行一段逻辑。
常见节点包括:
- 请求进入前;
- 模型调用前;
- 模型输出后;
- 工具调用前;
- 工具返回后;
- 任务结束时;
- 任务异常时。
Hooks 适合处理横向能力,不应把业务主流程全部写入其中。常见用途包括:
- 记录调用日志;
- 检查敏感信息;
- 校验工具参数;
- 统计耗时和调用次数;
- 对输出进行脱敏;
- 统一处理异常;
- 增加链路追踪标识;
- 拦截不符合规则的操作。
示意流程如下:
用户请求↓请求前 Hook:身份校验、内容检查↓模型决策↓工具前 Hook:参数校验、权限检查↓工具执行↓工具后 Hook:结果清洗、日志记录↓模型继续判断↓结束 Hook:输出脱敏、任务归档
Hooks 的优点是集中治理,避免每个工具重复实现相同的安全和日志逻辑。但也要注意,Hook 过多会使执行链路变得隐蔽,排查问题时不容易定位。因此每个 Hook 都应具备清晰命名、明确职责和可观测日志。
五、Harness:负责把所有组件组织起来
Harness 可以理解为 Agent 的运行时承载环境或执行框架。它负责把 Model、Tool、Skill、Rules 和 Hooks 组合成一个真正可运行的系统。
Harness 通常承担以下工作:
- 接收用户请求;
- 创建任务上下文;
- 管理对话和执行状态;
- 调用模型;
- 解析模型输出;
- 调度工具和 Skill;
- 执行规则校验;
- 触发生命周期 Hooks;
- 控制循环次数和超时时间;
- 保存日志和中间结果;
- 返回最终结果。
可以将 Harness 看作 Agent 的“操作系统”。模型像决策中枢,工具像外部设备,Skill 像应用程序,Rules 像安全策略,Hooks 像系统拦截器,而 Harness 负责统一调度。
一个简化的执行伪代码如下:
def run_agent(request):context = create_context(request)run_hook("before_request", context)validate_request(context)for step in range(MAX_STEPS):run_hook("before_model", context)decision = call_model(messages=context.messages,tools=context.available_tools,rules=context.rules)run_hook("after_model", decision)if decision.type == "final":result = decision.contentbreakif decision.type == "tool_call":validate_tool_call(decision, context)run_hook("before_tool", decision)tool_result = execute_tool(name=decision.name,arguments=decision.arguments)run_hook("after_tool", tool_result)context.add_tool_result(tool_result)continueraise RuntimeError("无法识别的模型输出")else:result = "任务达到最大执行步数,未完成"run_hook("after_request", result)return result
这段代码只是说明职责分工,并不对应某个具体平台或专有接口。实际实现时,还需要补充状态持久化、并发控制、超时处理、权限校验和人工审批机制。
六、从零设计一个 Agent 的实施步骤
第一步:明确任务边界
不要一开始就追求“什么都能做”的通用 Agent。应先选择一个目标明确、输入输出相对稳定的任务。
需要明确:
- 用户输入是什么;
- 最终输出是什么;
- 哪些步骤必须自动完成;
- 哪些步骤需要人工确认;
- 哪些数据可以访问;
- 哪些操作禁止执行;
- 任务完成的判定标准是什么。
边界越清晰,后续的工具、规则和测试越容易设计。
第二步:选择和评估 Model
根据任务复杂度选择模型能力,并用真实样例进行评估。重点测试:
- 是否能正确理解目标;
- 是否会选择正确工具;
- 参数是否完整;
- 是否能处理工具失败;
- 是否能在达到完成条件后及时停止;
- 是否会产生不必要的循环。
不要只用成功案例测试,还应准备缺少参数、数据为空、工具超时、权限不足和结果冲突等异常样例。
第三步:设计最小 Tool 集合
先提供完成任务所必需的工具,不要一次暴露过多能力。工具数量过多会增加模型选择难度,也会扩大安全风险。
每个工具都应定义输入校验、错误返回、权限范围和超时策略。对于写操作,优先采用幂等设计,避免 Agent 重试时产生重复数据或重复通知。
第四步:将稳定流程封装为 Skill
当某个任务需要多个工具协同,并且执行顺序相对固定时,就应将其封装成 Skill。Skill 中要明确输入、步骤、输出和成功条件,减少模型自由规划带来的不确定性。
第五步:补充 Rules 与 Hooks
Rules 负责定义约束,Hooks 负责在运行过程中自动执行检查、记录和拦截。两者应配合使用:
- Rules 表达“应该遵守什么”;
- Hooks 实现“在什么时候检查”;
- Harness 决定“检查失败后如何处理”。
第六步:实现 Harness 执行循环
Harness 至少要具备:
- 状态管理;
- 模型调用;
- 工具调度;
- 结果回填;
- 最大步数限制;
- 超时控制;
- 异常处理;
- 日志记录;
- 最终输出。
生产环境还应考虑任务恢复。例如进程中断后,可以根据保存的上下文恢复执行,而不是从头开始。
七、如何验证 Agent 是否真正可用
验证不能只看最终回答是否通顺,还要检查整个执行过程。
功能验证
确认以下内容:
- 能否正确理解用户目标;
- 能否调用正确工具;
- 工具参数是否符合预期;
- 能否基于工具结果继续执行;
- 能否在任务完成后停止;
- 最终结果是否满足格式要求。
安全验证
重点测试:
- 越权访问;
- 恶意输入诱导;
- 敏感数据泄露;
- 高风险操作绕过确认;
- 工具参数注入;
- 超出权限范围的资源访问。
稳定性验证
需要模拟:
- 模型返回格式错误;
- 工具超时;
- 工具返回空结果;
- 网络短暂中断;
- 重复执行;
- 并发请求;
- 长时间任务。
可观测性验证
至少记录:
- 请求标识;
- 用户或调用方身份;
- 模型调用次数;
- 工具调用名称和参数摘要;
- 每一步耗时;
- 错误类型;
- 最终状态;
- 是否触发人工介入。
日志中应避免直接记录敏感内容,可采用脱敏、摘要或哈希方式保留排查所需的信息。
八、常见问题与排查方法
1. Agent 一直循环,无法结束
常见原因包括:
- 没有定义明确的完成条件;
- 工具结果无法说明任务是否完成;
- 模型反复选择同一个工具;
- 没有设置最大步数。
排查时先查看每轮模型决策和工具返回结果,再确认是否存在重复调用。解决方式包括增加终止条件、记录已执行动作、限制重复调用次数。
2. 工具调用参数经常错误
可能是工具描述不清晰、参数类型模糊,或者模型没有获得足够上下文。
改进方法:
- 明确参数类型;
- 区分必填和可选字段;
- 提供合法取值范围;
- 在工具执行前增加程序校验;
- 缺少关键参数时先向用户追问。
3. Agent 会编造结果
模型可能在工具失败、数据为空或上下文不足时自行补全答案。
应通过规则明确要求:没有可靠数据时不得把推测表达成事实。工具返回结构中还应区分成功、空结果和失败三种状态,避免模型把异常当成正常结果。
4. 执行成本和延迟过高
常见原因是调用轮次过多、上下文过长、工具链拆分过细或重复查询。
优化方式包括:
- 将稳定流程封装为 Skill;
- 合并不必要的工具调用;
- 缓存短时间内不会变化的数据;
- 对简单任务使用更轻量的模型;
- 设置合理的超时和最大步数;
- 对失败操作采用有限重试。
5. 出现难以定位的偶发错误
此类问题通常与状态丢失、并发冲突、Hook 顺序不一致或异常处理不完整有关。
建议为每个任务生成唯一追踪标识,记录完整状态变更,并在模型调用、工具调用和 Hook 执行前后分别记录事件。这样可以还原任务执行链路。
九、生产环境的优化建议
安全方面
- 所有工具调用都进行身份和权限校验;
- 高风险操作增加人工确认;
- 对外部输入进行严格过滤;
- 敏感数据实行最小权限访问;
- 建立完整审计记录;
- 禁止默认开放任意执行能力。
稳定性方面
- 设置模型、工具和整体任务的超时;
- 为可重试错误配置有限重试;
- 对写操作进行幂等设计;
- 保存中间状态;
- 支持任务取消和恢复;
- 为异常设置降级路径。
性能和成本方面
- 控制上下文长度;
- 减少无效工具调用;
- 对重复查询使用缓存;
- 将长任务拆分为可恢复的阶段;
- 对不同复杂度任务采用不同模型策略;
- 统计每个任务的调用次数和资源消耗。
可维护性方面
- 将模型提示、工具定义、规则和执行代码分离;
- 为每个 Skill 建立版本;
- 为工具定义自动化测试;
- 使用固定测试集评估模型行为;
- 记录规则变更和执行效果;
- 避免把关键业务逻辑全部隐藏在提示词中。
十、总结
一个可靠的 AI Agent,不是简单地给模型增加几个工具,而是建立一套职责清晰的执行系统:
- Model 负责理解、推理和决策;
- Tool 负责访问外部系统并执行具体动作;
- Skill 负责封装可复用的复杂能力;
- Rules 负责定义行为边界;
- Hooks 负责在关键节点执行检查、记录和拦截;
- Harness 负责统筹调度、状态管理和任务循环。
实际落地时,建议遵循“先明确任务边界,再设计最小工具集,随后封装稳定技能,最后完善规则、钩子和运行时”的顺序。完成开发后,还要通过功能、安全、稳定性和可观测性测试验证系统行为。
当这些概念被清晰区分后,Agent 就不再是一个模糊的营销词,而会变成一套可以设计、实现、测试、监控和持续优化的工程系统。

登录后可评论,请前往 登录 或 注册