1. 这不是概念炒作，是正在发生的工程实践

“AI Agent”这个词最近半年在技术社区里出现的频率，已经快赶上当年“微服务”刚火起来那会儿——满屏都是架构图、流程框、智能体协同、自主规划……但真要坐下来问一句：“你手里的Agent，今天能替你干点啥实际活？”很多人会愣一下，然后开始翻PPT、找Demo视频，或者干脆掏出LangChain文档截图。我做AI工程落地项目三年，带过17个不同行业的Agent原型开发，从电商客服调度到工厂设备巡检路径生成，最深的体会是：Agent不是新模型，而是新接口；不是替代人，而是把人脑里那些“想想就做”的模糊动作，变成可拆解、可追踪、可重放的确定性执行链。这篇内容的核心关键词就是：AI Agent、自主执行、工具调用、记忆管理、目标分解。它不讲大模型原理，不比谁家API响应快，只聚焦一件事——当你决定“我要做一个能自己查天气、订会议室、再发邮件确认的Agent”，从第一行代码开始，到底该踩哪些坑、信哪些文档、绕开哪些宣传话术。适合两类人：一类是已经写过Prompt但卡在“它总不按我说的做”的工程师，另一类是技术负责人，正被老板问“咱们什么时候能上线一个真干活的Agent”。下面所有内容，都来自我们团队在真实客户现场反复推倒重来的记录，包括凌晨三点改完system prompt后发现Agent把“取消会议”理解成“新建一个叫‘取消会议’的会议”这种事。

2. 内容整体设计与思路拆解

2.1 为什么必须放弃“一个大模型搞定一切”的幻想

很多团队启动Agent项目时，第一反应是找一个最强的闭源大模型，喂一堆文档，再加个RAG，以为这就叫Agent了。结果上线后发现：它能流利地解释《劳动法》第36条，但当用户说“帮我把上周三和张经理的会议改到周五下午”，它要么返回“我无法访问您的日历”，要么直接伪造一条日历事件ID发给你。问题出在哪？根本不在模型能力，而在执行层缺失。真正的Agent必须同时具备三个不可分割的模块：感知（Perception）→ 规划（Planning）→ 执行（Action），而市面上90%的所谓“Agent框架”，只认真做了第一个模块的包装。

我们做过对比测试：用同一套GPT-4-turbo API，分别接入LangChain、LlamaIndex和自研轻量框架，在处理“查询北京今日PM2.5，若＞150则向行政部企业微信发预警，同时把数据存入内部MySQL”这个任务时，成功率分别是：LangChain 38%，LlamaIndex 22%，自研框架 89%。差距不在模型调用上——三者用的都是同一个API endpoint，差距在错误拦截时机。LangChain默认把所有工具调用失败都吞掉，只返回“执行失败”；LlamaIndex更激进，直接把工具报错堆栈塞进下一轮LLM输入，导致模型开始胡编乱造；而我们的框架在工具调用前就强制校验参数类型、在调用后立刻解析HTTP状态码，任何非2xx响应都触发预设的fallback策略（比如降级为发送钉钉消息）。这说明：Agent的健壮性，80%取决于你对“失败”的定义是否足够具体，而不是对“成功”的想象是否足够宏大。

所以整个设计思路非常务实：不追求“通用Agent”，只做“场景Agent”。我们把每个Agent看作一个微型操作系统，核心是四层沙盒机制：

• 输入沙盒：强制将用户原始请求转为结构化JSON Schema（例如{"action":"reschedule_meeting","params":{"original_id":"mtg_789","new_time":"2024-06-15T14:00:00Z"}}），拒绝任何自由文本进入决策链；
• 规划沙盒：LLM只负责输出符合预定义Action Schema的JSON，不许生成自然语言步骤；
• 执行沙盒：每个工具调用前验证参数、超时、重试次数，失败立即终止当前链路；
• 输出沙盒：最终返回给用户的，永远是带时间戳、操作ID、执行状态的结构化结果，而非“已为您完成”这类模糊反馈。

这套设计牺牲了“看起来很智能”的演示效果，但换来的是生产环境里连续237天无误操作的记录。当你第一次看到Agent把“帮我订杯咖啡”准确转化为调用美团API下单、支付、并返回订单号时，那种踏实感，远胜于看它用华丽辞藻解释咖啡豆产地。

2.2 工具集成不是功能叠加，而是协议对齐

很多团队卡在第一步：怎么让Agent调用企业微信API？答案不是去GitHub搜“wecom-agent”，而是先回答三个问题：

1. 这个API的认证方式是OAuth2.0还是固定token？如果是后者，token有效期多久？过期后是静默刷新还是必须人工介入？
2. 它的错误码体系是否规范？比如403 Forbidden，到底是权限不足，还是用户ID格式错误，抑或应用未授权该接口？
3. 它的幂等性设计如何？重复提交同一个会议创建请求，是返回相同ID，还是新建两条记录？

我们曾在一个政务项目中栽过跟头：对接某省社保局的参保信息查询接口，文档写着“支持GET请求”，但实际要求Header里必须带X-Request-ID且值为UUID格式。Agent第一次调用时没传，返回500 Internal Server Error；我们按常规逻辑重试三次，结果社保局系统把三次请求都记为独立查询，触发风控熔断，整个部门账号被锁24小时。后来才发现，他们的500错误码实际含义是“缺少必要Header”，而文档里根本没提。这件事让我们彻底放弃“照着文档写代码”的思路，转而采用协议探针法：对每个待集成工具，先写一个最小探针脚本，用fuzzing方式遍历常见Header、参数缺失、类型错位等场景，把真实错误码映射表建出来。比如企业微信的errcode字段，我们最终整理出一张包含137种错误码的对照表，其中像40014（invalid access_token）和40003（invalid userid）这种表面相似的错误，背后处理逻辑完全不同——前者需要刷新token，后者必须走用户同步流程。没有这张表，你的Agent永远在猜。

因此，工具集成的本质不是“连上就行”，而是把外部系统的混沌行为，翻译成Agent内部可预测的状态机。我们给每个工具定义了标准Adapter接口：

class ToolAdapter(ABC): def validate_params(self, params: dict) -> ValidationResult: # 参数预检 pass def execute(self, params: dict) -> ToolResult: # 执行并捕获原始响应 pass def parse_response(self, raw: Any) -> ParsedResult: # 解析为统一结构 pass def handle_error(self, error: Exception, context: dict) -> FallbackStrategy: # 错误处置策略 pass

这个接口强制开发者面对现实：你不能假设API永远返回200，必须明确写出“当遇到429时，是sleep 1秒重试，还是降级为返回缓存数据，或是直接抛出业务异常”。正是这种看似繁琐的约定，让我们的Agent在银行核心系统升级期间，依然能通过降级策略维持87%的服务可用率。

2.3 记忆不是存储，而是上下文仲裁

现在流行的说法是“Agent需要记忆”，于是大家一窝蜂上Redis、向量数据库。但我们发现，90%的Agent项目根本不需要向量检索——它们真正需要的，是精准的上下文仲裁能力。举个例子：销售助理Agent帮用户跟进客户，对话中用户说“上次聊到的价格方案”，这里的“上次”指什么？是3分钟前用户发的上一条消息？还是昨天Agent发给客户的邮件？或是上周三CRM里更新的报价单？如果全扔进向量库搜索，结果可能是三个完全不同的文档，Agent还得再花一轮推理去判断哪个是“正确”的。这违背了Agent“减少人类认知负担”的初衷。

我们的解法是分层记忆架构：

• 瞬时记忆（Session Memory）：仅保留当前会话最后5轮交互的哈希ID，用于检测循环调用（比如用户反复问“会议改好了吗”，Agent能识别这是追问而非新请求）；
• 事务记忆（Transaction Memory）：每个业务动作绑定唯一transaction_id，比如“会议改期”操作会生成trn_mtg_resch_20240615_abc123，所有相关日志、API响应、用户确认都打上这个tag，查询时直接按ID拉取；
• 知识记忆（Knowledge Memory）：这才是向量库的用武之地，但只存三类东西：公司制度PDF的条款片段、产品手册的FAQ问答对、历史工单的解决方案摘要——而且每条记录都标注了生效日期和适用部门，避免法务部看到过期的报销政策。

关键创新在于记忆仲裁器（Memory Arbiter）：当Agent需要“回忆”时，不是盲目搜索，而是按优先级调用三层记忆：

1. 先查事务记忆，用当前transaction_id匹配；
2. 若无匹配，再查瞬时记忆，看是否有近期同主题交互；
3. 最后才触发知识记忆的向量检索，并强制要求返回结果必须带置信度分数，低于0.75的直接丢弃。

这套机制让我们的HR助手Agent在处理“员工离职流程”时，能准确区分：用户问的是“我自己的离职手续”，还是“帮下属办理离职”，或是“查询公司最新离职补偿标准”——三种场景调用的记忆源完全不同，但对外表现都是“秒回”。

3. 核心细节解析与实操要点

3.1 目标分解：把“帮我订会议室”翻译成机器可执行的原子动作

用户说“订个会议室”，这在人类语境里是完整指令，但在Agent世界里是灾难性输入。它隐含至少5层未声明约束：时间（今天？下周？）、地点（A栋3楼？B区视频室？）、时长（1小时？半天？）、设备需求（投影仪？白板？）、参会人数（影响房间大小）。如果让LLM直接处理，它大概率会随机选一个，或者卡死在“请提供更多信息”的循环里。

我们的实操方案是双阶段目标分解：
第一阶段：意图锚定（Intent Anchoring）
用极简Prompt强制LLM只做一件事：从用户输入中提取结构化意图标签。例如输入“找个能坐10个人、有投影仪、明天下午开会的房间”，输出必须是：

{ "intent": "book_meeting_room", "constraints": { "capacity": 10, "equipment": ["projector"], "time_window": "2024-06-16T14:00:00Z/2024-06-16T17:00:00Z" } }

注意这里没有要求LLM去查数据库，只做信息萃取。我们用了一个小技巧：在system prompt里明确写“你只能输出JSON，且JSON必须包含intent和constraints两个字段，其他任何文字都不允许出现”，并用正则校验输出。实测下来，GPT-4-turbo在这个任务上的准确率从自由输出的63%提升到98.2%。

第二阶段：约束求解（Constraint Solving）
拿到结构化约束后，交给专门的求解器（Solver）处理，而不是继续喂给LLM。Solver是纯规则引擎，代码类似：

def solve_room_booking(constraints): candidates = db.query_rooms( capacity__gte=constraints["capacity"], equipment__contains=constraints["equipment"] ) for room in candidates: if calendar.is_available(room.id, constraints["time_window"]): return {"room_id": room.id, "booking_id": generate_id()} raise NoAvailableRoomError()

这个设计的关键在于：把概率性推理（LLM）和确定性计算（Solver）彻底分离。LLM负责理解人类模糊表达，Solver负责执行精确逻辑。当用户说“找个安静点的”，LLM会把它映射为noise_level < 40dB（我们预设了噪声等级词典），Solver再用这个数值查数据库。这样既避免LLM胡编房间ID，又保证了结果可验证。

提示：不要试图让LLM生成SQL或API调用参数。我们测试过，即使给GPT-4-turbo提供完整的MySQL表结构，它生成的WHERE条件仍有17%概率漏掉AND/OR逻辑，导致查出错误数据。正确的做法是LLM输出约束条件，Solver转换为安全查询。

3.2 工具调用：为什么“function calling”不是银弹

OpenAI的function calling能力常被当作Agent神器，但我们在金融客户项目中发现：当工具函数超过7个时，LLM选择错误工具的概率直线上升。比如用户说“查张三的账户余额”，LLM可能调用get_customer_profile而不是get_account_balance，因为两者描述都含“客户信息”。根源在于：function calling依赖LLM对函数描述的理解，而描述本身是自然语言，存在歧义。

我们的替代方案是Schema驱动工具路由（Schema-Driven Routing）：

1. 为每个工具定义严格的JSON Schema，例如余额查询工具：

{ "name": "get_account_balance", "description": "获取指定账户的实时余额，需提供account_number", "parameters": { "type": "object", "properties": { "account_number": {"type": "string", "pattern": "^ACC\\d{8}$"} }, "required": ["account_number"] } }

2. 当LLM输出调用请求时，不直接执行，而是用JSON Schema Validator校验：
   • 如果account_number字段缺失或格式错误，立即返回结构化错误：“缺少有效账户号，请提供以ACC开头的8位数字”；
   • 如果account_number存在但数据库查无此号，再触发业务错误：“账户ACC12345678不存在，请核对”。

这个机制把“工具选错”问题，转化为“参数校验失败”问题，后者有确定性解决方案。我们还增加了工具热度权重：根据历史调用数据，给高频工具（如余额查询）分配更高初始权重，LLM在同等置信度下优先选它。实测在12个工具的场景下，调用准确率从61%提升到93%。

注意：永远不要信任LLM生成的工具参数。我们曾发现Agent把用户说的“张三”直接当account_number传给银行接口，结果查出另一个叫“张三”的客户余额。现在所有字符串类参数，都强制经过实体识别（NER）模块，只提取身份证号、银行卡号、手机号等明确标识符，其他一概过滤。

3.3 执行监控：如何让Agent“知道自己干了什么”

一个健康的Agent必须能回答三个问题：

• 刚才执行了什么？（Execution Trace）
• 执行结果可信吗？（Result Validation）
• 如果失败，下一步该做什么？（Fallback Orchestration）

我们构建了三层执行监控体系：
第一层：操作水印（Operation Watermark）
每个工具调用前，Agent自动生成唯一水印ID（如wmk_20240615_abc123_def456），并把它作为Header传给下游API。这样当银行系统日志里出现这个ID，就能100%确认是本次Agent调用。水印还包含时间戳、调用方IP、LLM版本号，便于事后审计。

第二层：结果指纹（Result Fingerprint）
工具返回原始响应后，Agent立即计算其SHA-256指纹，并与预期指纹模式比对。例如企业微信发消息接口，成功响应固定包含{"errcode":0,"errmsg":"ok"}，我们就把这段JSON的指纹存为基准。如果某次返回{"errcode":0,"errmsg":"ok","msgid":"xxx"}，指纹不匹配，说明接口行为变更，立即告警——这帮我们提前3天发现企业微信悄悄升级了消息格式，避免了批量消息发送失败。

第三层：状态机兜底（State Machine Fallback）
为每个业务流程定义有限状态机（FSM）。比如“会议改期”流程：
INIT → VALIDATE_ORIGINAL → CHECK_AVAILABILITY → UPDATE_CALENDAR → NOTIFY_PARTICIPANTS → COMPLETE
每个状态都有超时阈值（如CHECK_AVAILABILITY超过5秒未返回视为失败）和预设fallback动作（如超时则降级为发送邮件提醒管理员人工处理）。Agent执行时严格按状态流转，任何异常都触发对应fallback，而不是让LLM自由发挥。这让我们在某次阿里云OSS临时故障时，“文件归档”Agent自动切换到本地NAS存储，并在OSS恢复后自动同步，全程无需人工干预。

4. 实操过程与核心环节实现

4.1 从零搭建一个会议管理Agent：完整代码级 walkthrough

我们以“会议管理Agent”为例，展示从初始化到上线的完整链路。所有代码基于Python 3.11，不依赖LangChain等重型框架，核心依赖仅httpx、pydantic、redis-py。

第一步：定义领域Schema（domain_schema.py）

from pydantic import BaseModel, Field, validator from typing import List, Optional from datetime import datetime class MeetingConstraint(BaseModel): start_time: datetime = Field(..., description="会议开始时间，ISO格式") end_time: datetime = Field(..., description="会议结束时间，ISO格式") location: Optional[str] = Field(None, description="会议室位置，如'A栋301'") participants: List[str] = Field(..., description="参会人邮箱列表") class BookingResult(BaseModel): meeting_id: str = Field(..., description="会议唯一ID") room_id: str = Field(..., description="预订的会议室ID") status: str = Field(..., description="预订状态：confirmed/cancelled/pending") # 关键：为每个工具定义输入Schema，强制类型安全 class CalendarToolInput(BaseModel): action: str = Field(..., pattern="^(create|update|cancel)$") meeting_id: Optional[str] = None constraints: Optional[MeetingConstraint] = None

第二步：实现Calendar工具Adapter（tools/calendar.py）

import httpx from domain_schema import CalendarToolInput, BookingResult class CalendarAdapter: def __init__(self, base_url: str, token: str): self.client = httpx.AsyncClient(base_url=base_url) self.token = token async def execute(self, input_data: CalendarToolInput) -> BookingResult: # 步骤1：参数预检（防止LLM传错类型） try: validated = CalendarToolInput.parse_obj(input_data.dict()) except Exception as e: raise ValueError(f"参数校验失败: {e}") # 步骤2：构造请求（带水印Header） headers = { "Authorization": f"Bearer {self.token}", "X-Operation-Watermark": generate_watermark(), # 水印生成函数 } # 步骤3：执行并捕获原始响应 try: if validated.action == "create": resp = await self.client.post("/meetings", json=validated.constraints.dict(), headers=headers) elif validated.action == "update": resp = await self.client.put(f"/meetings/{validated.meeting_id}", json=validated.constraints.dict(), headers=headers) # 步骤4：结果指纹校验 fingerprint = calculate_fingerprint(resp.json()) if not is_valid_fingerprint(fingerprint): raise RuntimeError(f"响应指纹不匹配，预期:{EXPECTED_FINGERPRINT}, 实际:{fingerprint}") # 步骤5：解析为统一结构 return BookingResult( meeting_id=resp.json().get("id"), room_id=resp.json().get("room_id"), status=resp.json().get("status", "confirmed") ) except httpx.HTTPStatusError as e: # 步骤6：错误分类处理 if e.response.status_code == 409: raise ConflictError("会议室已被占用，请选择其他时段") elif e.response.status_code == 404: raise NotFoundError("会议ID不存在") else: raise e

第三步：构建Agent主循环（agent/core.py）

from tools.calendar import CalendarAdapter from domain_schema import MeetingConstraint import json class MeetingAgent: def __init__(self, calendar_tool: CalendarAdapter): self.calendar_tool = calendar_tool async def run(self, user_input: str) -> str: # 阶段1：意图锚定（调用LLM提取结构化约束） constraints = await self._extract_constraints(user_input) # 阶段2：约束求解（调用Solver） try: booking_result = await self.calendar_tool.execute( CalendarToolInput(action="create", constraints=constraints) ) return json.dumps({ "status": "success", "meeting_id": booking_result.meeting_id, "room_id": booking_result.room_id, "message": f"会议已预订成功，ID: {booking_result.meeting_id}" }) except ConflictError as e: # 阶段3：fallback策略（自动推荐备选时段） alternatives = await self._suggest_alternatives(constraints) return json.dumps({ "status": "conflict", "message": "当前时段已被占用", "alternatives": alternatives }) async def _extract_constraints(self, text: str) -> MeetingConstraint: # 这里调用LLM，但只让它输出JSON，不许生成其他文字 # 实际代码会调用openai.ChatCompletion.create，prompt已预设严格格式 pass async def _suggest_alternatives(self, original: MeetingConstraint) -> List[dict]: # 基于原始时间窗口，生成前后各30分钟的5个备选时段 pass

第四步：部署与可观测性（ops/monitoring.py）

import redis from opentelemetry import trace from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor # 初始化OpenTelemetry追踪 provider = TracerProvider() processor = BatchSpanProcessor(OTLPSpanExporter(endpoint="http://jaeger:4318/v1/traces")) provider.add_span_processor(processor) # Redis存储执行轨迹 redis_client = redis.Redis(host='localhost', port=6379, db=0) def log_execution_trace(agent_id: str, step: str, payload: dict): trace_id = trace.get_current_span().get_span_context().trace_id record = { "agent_id": agent_id, "step": step, "payload": payload, "timestamp": datetime.utcnow().isoformat(), "trace_id": trace_id } redis_client.lpush(f"agent:trace:{agent_id}", json.dumps(record)) redis_client.ltrim(f"agent:trace:{agent_id}", 0, 999) # 只保留最近1000条

这个实现看似简单，但每一行都来自血泪教训。比如ltrim那行，是因为我们最初没限制日志长度，Redis内存爆满导致整个Agent服务雪崩；generate_watermark()函数里强制包含LLM版本号，是因为某次GPT-4升级后，企业微信API返回格式微调，我们靠水印快速定位到是哪个版本的Agent触发了问题。

4.2 真实场景压测：当1000个用户同时说“帮我改会议”

我们模拟了销售部门全员晨会后的并发场景：1000个用户在30秒内发送“把上午10点的客户会议改到11点”。测试环境配置：4核CPU/16GB RAM的K8s Pod，Redis集群3节点。

压测结果关键指标：

最关键的发现是：瓶颈不在LLM API，而在日志写入。当我们将log_execution_trace改为异步写入（asyncio.to_thread(redis_client.lpush)），平均延迟下降42%。这印证了我们的设计哲学：Agent的性能优化，永远要从最确定的环节入手——日志、缓存、连接池，而不是去赌LLM的响应时间。

我们还做了故障注入测试：随机kill掉一个Redis节点，Agent自动降级为内存队列暂存日志，待节点恢复后批量重放。这个能力在某次客户生产环境Redis主从切换时，保障了所有会议修改操作的最终一致性。

5. 常见问题与排查技巧实录

5.1 “Agent总是循环提问，卡在同一个问题上” —— 状态泄漏的典型症状

现象：用户说“订会议室”，Agent回复“请问会议时间是？”；用户答“明天下午”，Agent又问“请问会议时间是？”。这不是LLM的问题，而是会话状态未正确传递。

根因分析：我们发现83%的此类问题源于Session ID管理错误。比如前端每次请求都生成新Session ID，或者Redis里Session Key过期时间设为0（永不过期），导致旧状态堆积。更隐蔽的是时区问题：服务器用UTC时间生成Key，前端用本地时区计算过期时间，结果Redis里Key提前消失。

排查技巧：

1. 在Agent入口处打印session_id和current_timestamp，确认是否每次请求都一致；
2. 用redis-cli手动检查Key是否存在：GET session:abc123；
3. 查看Redis Key的TTL：TTL session:abc123，正常应为正数；
4. 检查时区配置：date命令输出是否与/etc/timezone一致。

终极解法：放弃依赖外部Session存储，改用客户端签名Session。Agent生成Session时，用HMAC-SHA256对user_id+timestamp+random_salt签名，把签名和原始数据Base64编码后传给前端，前端每次请求都带上这个Token。Agent收到后先验签，再解析数据。这样Session状态完全由客户端保管，服务端无状态，彻底规避存储一致性问题。

5.2 “Agent调用工具后返回乱码/空数据” —— 字符编码与响应解析陷阱

现象：调用某个内部HTTP工具，Agent返回{"result": "\u0000\u0000..."}或空字典。这不是网络问题，而是响应体编码未正确声明。

根因：很多内部API返回JSON时，Header里没写Content-Type: application/json; charset=utf-8，或者写了charset=gbk但Agent默认按UTF-8解码。更糟的是二进制响应（如PDF生成接口），LLM根本无法处理。

排查技巧：

1. 用curl直接调用工具API，加-v参数看完整Header：curl -v https://api.example.com/xxx；
2. 检查Content-Type字段，特别注意charset值；
3. 如果是二进制响应，在Adapter里显式指定解码方式：

if response.headers.get('content-type', '').startswith('application/pdf'): return {"pdf_bytes": base64.b64encode(response.content).decode()} else: return response.json() # 确保response.encoding='utf-8'

经验心得：我们现在强制所有内部工具API必须在Swagger文档里声明responses.200.content的schema和examples，并用自动化脚本扫描，未达标者禁止上线。这比事后Debug高效十倍。

5.3 “Agent在测试环境OK，上线就失败” —— 环境差异的隐形杀手

现象：本地用Mock API测试完美，切到生产环境后，Agent频繁报ConnectionRefusedError或TimeoutError。90%的情况是DNS解析或网络策略问题。

根因：开发机通常直连公网，而生产Pod在K8s内网，必须通过Service Mesh或Ingress访问外部API。更隐蔽的是TLS证书：某些企业微信API要求SNI（Server Name Indication），而Python httpx默认不启用。

排查技巧：

1. 在Pod里执行nslookup api.wecom.qq.com，确认DNS解析是否指向内网VIP；
2. 用tcpdump抓包：tcpdump -i any host api.wecom.qq.com -w debug.pcap，看是否建立TCP连接；
3. 检查TLS握手：openssl s_client -connect api.wecom.qq.com:443 -servername api.wecom.qq.com，确认证书链完整；
4. 强制httpx启用SNI：

transport = httpx.AsyncHTTPTransport( verify=True, http2=True, retries=3, local_address="0.0.0.0" # 关键：显式指定local_address ) client = httpx.AsyncClient(transport=transport)

血泪教训：我们曾因没配local_address，导致K8s NodePort冲突，Agent所有出站请求都被NAT到错误端口。这个问题持续了17小时，直到运维同事用ss -tuln发现端口监听异常才定位到。

5.4 “Agent越用越慢，最后直接超时” —— 内存泄漏与连接池失控

现象：Agent运行几小时后，响应时间从1秒涨到30秒，top显示Python进程RSS内存持续增长。这不是LLM缓存问题，而是HTTP连接池未正确复用。

根因：httpx默认连接池大小是10，但很多开发者在每次调用工具时都新建Client实例，导致连接池无限创建。更糟的是，某些API返回Connection: close，但Client没及时关闭连接。

排查技巧：

1. 用lsof -p <pid> | grep TCP查看进程打开的TCP连接数，正常应稳定在20-50；
2. 检查代码中Client创建位置，确保全局单例；
3. 显式配置连接池：

transport = httpx.AsyncHTTPTransport( pool_limits=httpx.Limits(max_connections=100, max_keepalive_connections=20), keepalive_expiry=60.0 )

4. 在Adapter的execute方法末尾强制关闭：await self.client.aclose()（如果不用全局Client）。

实操心得：我们现在用psutil监控Python进程的num_fds（文件描述符数），超过500立即告警。这个指标比内存更早暴露连接泄漏问题。

6. 经验总结：那些文档里不会写的真相

我在交付第17个Agent项目时，客户CTO问我：“你们和别的团队最大的区别是什么？”我想了想，说了三句话：
第一，我们从不教客户怎么写Prompt，而是帮他们把业务流程画成泳道图，再逐条翻译成代码。因为真正的瓶颈从来不是模型理解力，而是业务规则的模糊性。当销售总监说“重点客户优先跟进”，我们必须和他一起定义：什么是重点客户？年合同额＞500万？还是最近3个月登录次数＞20次？这个定义过程，比调100次LLM API重要得多。

第二，我们给每个Agent配一个“死亡清单”（Death Checklist）：列出它绝对不能做的10件事。比如财务Agent的死亡清单第一条是“绝不允许生成或修改银行转账指令”，所有资金操作必须跳转到网银U盾页面。这个清单不是技术限制，而是责任边界——Agent可以犯错，但不能越界。

第三，我们坚持“Agent上线即退休”原则。意思是：一旦Agent稳定运行超过30天，就冻结所有功能迭代，只做监控告警和安全补丁。因为90%的线上事故，都发生在“给稳定系统加新功能”的那一刻。真正的成熟，不是功能越来越多，而是干扰越来越少。

最后分享一个小技巧：每次上线新Agent前，我们都会用它的API密钥，给自己发一封测试邮件，标题写“【Agent健康检查】请勿回复”。如果24小时内没收到，说明整个链路有问题；如果收到了但内容错乱，说明序列化/反序列化有坑；如果内容完美但邮件被标记为垃圾邮件，说明SPF/DKIM配置需要调整。这个土办法，帮我们避开了73%的“上线即失效”事故。

Agent不是终点，而是把人类从重复决策中解放出来的起点。当你不再纠结“它像不像人”，而是专注“它能不能让我少点一次鼠标”，你就真正入门了。