AI Agent 架构设计与多 Agent 协作系统搭建：上下文与工具的职责边界

范围说明：本文用设计场景和代码片段说明取舍；其中的服务名、故障、比例、延迟、并发数及图表数据均为演练输入或待测参数，不代表线上实测。采用前应在目标版本、硬件、流量与安全边界下复核并记录结果。

在多 Agent 协作系统或者复杂单 Agent 系统运行一段时间后，系统经常面临一个典型的性能与稳定性瓶颈：随着会话轮次的拉长，或者接入 API 数量的增加，Agent 的工具调用准确率大幅下降。例如，模型可能尝试直接在 Prompt 内计算复杂的数据逻辑导致显著偏差，或者将上百 KB 的环境状态日志全部塞入 Context，导致上下文窗口溢出或触发模型推理能力衰减。

这种工程痛点的根源在于设计初期未能划分 Context（上下文）与 Tool（工具）的职责边界，缺少严格的接口契约与显式错误语义设计。将 Context 作为通用的数据暂存区，同时将 Tool 视为无状态的脚本触发器，最终导致系统在面对高并发和长链路请求时鲁棒性不足。

1. 上下文膨胀下的 Attention Drift 现象与问题分析

在大型系统或复杂工作流场景中，当多 Agent 协作系统用于自动化运维排障时，分析 Agent 负责汇总日志，诊断 Agent 负责生成修复脚本并调用 K8s 工具执行。在面对冗长日志的排查任务时，如果分析 Agent 将诊断过程中的原生 SQL 输出、HTTP Response 原封不动地追加到上下文 Memory 中，会导致 Context 累积超过数万 Token。

在上下文显著膨胀后，模型容易降低对初始工具约束契约的注意力，出现 K8s API 请求参数组装错位的情况，或者在文本响应中以自然语言模拟“ Pod 已重启成功 ”的假象。

通过系统监控与链路日志分析发现，这种现象并非模型基座出现故障，而是庞大嘈杂的 Context 严重干扰了模型的注意力分布（Attention Drift）。

在工程架构中，上下文（Context）是 Agent 的临时记忆与状态机快照，而工具（Tool）是 Agent 延伸到物理现实的确定性副作用执行器。如果由上下文承担不属于它的原始数据存储，或者工具丢失了强类型的接口契约，整个系统的鲁鲁棒性就会降低。

2. 状态机与工具接口契约：区分短期内存与无状态执行器

解决该问题的关键在于架构上的模块解耦与职责划分。

上下文管理不能简单地通过追加消息列表（如messages.append(new_message)）来实现。应当将 Context 拆分为两个层级：

1. 全局不可变状态与短期决策视图：仅保留最近 N 轮的关键决策节点、用户目标以及经过 Summarize 压缩后的实体状态。
2. 外部游离数据载荷（Payload Offloading）：所有工具执行返回的大文本（如超过 2KB 的日志、JSON 响应、数据库查询结果），一律存入外置存储（如 Redis 或 S3），Context 内仅保留其 Hash 引用与摘要索引。

对于工具侧，不应直接向 LLM 传递泛型字典参数（如kwargs: dict）。必须构建强类型的工具接口契约（Interface Contract）。每一次工具调用，都必须在 Python 侧经过 Pydantic 或 Protocol 的二次校验，防止非法类型侵入系统。

上下文 (Context) 职责： - 维持 Agent 当前的 Goal 与 Sub-goals - 记录有限轮次的 Action-Observation 状态转移 - 存储轻量级句柄 (Pointers)，拒明确原始大文本直接持有 工具 (Tool) 职责： - 声明严格的 JSON Schema 输入输出契约 - 负责幂等控制、超时熔断与底层系统重试 - 将工程底层的 RPC/HTTP 错误收敛为标准 Agent 语义

3. 错误语义设计：区分 LLM 幻觉异常与系统工程异常

在多 Agent 系统中，错误处理机制至关重要。当工具执行失败时，需要明确是直接抛出 Exception 终止流程，还是将错误回传给 LLM 触发重试。

混淆这两者可能导致系统陷入无休止的重试循环。因此，需要从错误语义层建立严格的三分类设计：

第一类是Schema 契约错误（Contract Error）。例如 LLM 生成的 JSON 参数缺少必填字段或类型传错。这种错误属于 LLM 的局部生成偏差，应当捕获后作为提示词补充输入（Reflective Prompting），让 LLM 立即纠错重试，重试上限设为 2 次。

第二类是业务工程异常（Engineering Failure）。比如调用的上游 API 返回了 404，或者数据库连接超时。这种错误是确定性的物理故障，不能让 LLM 盲目重试工具，必须由工具层直接返回预设的结构化错误 Payload，引导 Agent 走降级分支或切换备用工具。

第三类是致命防线熔断（Fatal Breaker）。例如 Token 消耗超出本次 Task 的预算，或者工具触发了高危权限拦截（如试图执行rm -rf）。这种异常必须在 Python 框架层直接 raise 强中断信号，剥夺 Agent 的控制权，触发人工介入或全局降级。

4. 生产级 Agent 调度核心代码实现

下面是在生产环境落地的 Agent 上下文与工具隔离调度器实现。代码基于 Python 3.11 的异步能力与 Pydantic 强类型校验，在工程层为 LLM 的非确定性行为建立隔离机制：

importasyncioimportjsonimportloggingfromtypingimportAny,Callable,Dict,List,OptionalfrompydanticimportBaseModel,Field,ValidationError logging.basicConfig(level=logging.INFO)logger=logging.getLogger("AgentFramework")classToolResult(BaseModel):"""工具调用的确定性输出契约"""success:booldata:Optional[Dict[str,Any]]=Noneerror_code:Optional[str]=Noneerror_message:Optional[str]=Noneis_recoverable:bool=FalseclassAgentContext(BaseModel):"""解耦后的 Agent 上下文管理"""session_id:strtoken_budget:int=Field(default=8000)tokens_used:int=0short_term_memory:List[Dict[str,str]]=Field(default_factory=list)payload_store:Dict[str,Any]=Field(default_factory=dict)defappend_action(self,role:str,content:str,payload:Optional[Any]=None)->None:"""追加轻量上下文，大文本载荷卸载至外部字典"""pointer_key=Noneifpayloadandlen(str(payload))>1024:pointer_key=f"ref_{len(self.payload_store)+1}"self.payload_store[pointer_key]=payload content+=f" [Payload Offloaded to{pointer_key}]"self.short_term_memory.append({"role":role,"content":content})# 模拟 Token 计算，实际生产使用 tiktokenself.tokens_used+=len(content)//4defis_budget_exceeded(self)->bool:returnself.tokens_used>=self.token_budgetclassBaseTool:"""所有 Agent 工具必须继承的抽象契约类"""name:strdescription:strargs_schema:type[BaseModel]asyncdefexecute(self,**kwargs)->ToolResult:try:validated_args=self.args_schema(**kwargs)returnawaitself._run(validated_args)exceptValidationErrorase:logger.warning(f"Tool{self.name}Schema Contract Error:{e}")returnToolResult(success=False,error_code="SCHEMA_INVALID",error_message=str(e),is_recoverable=True)exceptExceptionase:logger.error(f"Tool{self.name}Execution System Exception:{e}")returnToolResult(success=False,error_code="SYSTEM_FAULT",error_message=f"Internal tool failure:{str(e)}",is_recoverable=False)asyncdef_run(self,args:BaseModel)->ToolResult:raiseNotImplementedErrorclassQueryLogSchema(BaseModel):service_name:str=Field(...,description="目标微服务名称")lines:int=Field(default=50,ge=1,le=500,description="读取日志行数")classQueryLogTool(BaseTool):name="query_service_log"description="查询指定微服务最新的日志信息"args_schema=QueryLogSchemaasyncdef_run(self,args:QueryLogSchema)->ToolResult:# 模拟真实的底层运维 API 调用ifargs.service_name=="invalid_svc":returnToolResult(success=False,error_code="SERVICE_NOT_FOUND",error_message=f"Service{args.service_name}unregistered",is_recoverable=True)fake_log=f"2026-08-09 INFO [{args.service_name}] Processed request successfully."*args.linesreturnToolResult(success=True,data={"logs":fake_log})classAgentDispatcher:"""Agent 核心调度引擎：隔离 Context 与 Tool"""def__init__(self,context:AgentContext):self.context=context self.tools:Dict[str,BaseTool]={}defregister_tool(self,tool:BaseTool)->None:self.tools[tool.name]=toolasyncdefdispatch_tool_call(self,tool_name:str,raw_args:Dict[str,Any])->str:ifself.context.is_budget_exceeded():raiseRuntimeError("Fatal: Token budget exhausted, agent execution terminated.")tool=self.tools.get(tool_name)ifnottool:returnf"Error: Tool '{tool_name}' does not exist."result=awaittool.execute(**raw_args)ifresult.success:# 成功后写回上下文，自动触发 Payload 离线存储self.context.append_action("tool",f"Executed{tool_name}successfully.",payload=result.data)returnf"Tool Executed Successfully. Output reference:{result.data}"else:ifresult.is_recoverable:# 提示模型修正参数或更换输入returnf"Tool Error [{result.error_code}]:{result.error_message}. Please check args and retry."else:# 确定性工程故障，直接向 Context 注入降级通知self.context.append_action("system",f"Tool{tool_name}failed with system fault.")returnf"Tool System Error:{result.error_message}. Do not retry this tool."

5. 在 5000 次长链路测试下看分工边界的性能表现

在仿真环境下搭建包含 5 个 Agent 协作的告警排查链路，并进行 5000 次长轮次压力测试。

测试对比了两种方案：对比方案将所有工具调用的原始文本全部原样存入 Context，且工具参数解析采用无类型的字典检索；重构方案引入了上述的数据载荷卸载、Pydantic 契约约束以及三级错误语义响应。

指标对比项 对比方案 (上下文无边界) 重构方案 (契约与载荷隔离) 上下文 Token 平均占用 78,400 Tokens 6,200 Tokens (↓ 92.1%) LLM 工具调用语法错误率 14.8% 0.3% (↓ 97.9%) 长轮次死循环发生率 8.5% 0.无业务流量 (显著减少（需验证）) 平均任务处理耗时 12.4s 3.1s (↓ 75.无业务流量)

压力测试数据证明：不应依赖 LLM 自身的隐式调整去管理复杂状态和工具。

在多 Agent 协作系统的工程落地中，关键在于通过工程手段构建确定性防线。保持 Context 精简、可追溯，确保 Tool 具备强类型、容错机制与显式错误语义。将控制逻辑收敛至工程代码，才能保证 AI Agent 在复杂生产环境中的稳定运行。