企业级Agent落地四道工程坎：工具调用、权限、上下文与并发

1. 项目概述：为什么企业级 Agent 落地总在 Demo 和上线之间“断崖式失重”

“Demo 惊艳、上线拉胯”——这八个字，几乎成了过去两年我参与过的所有企业级 Agent 项目复盘会上的高频开场白。不是模型不行，不是想法不新，更不是业务方不买账；而是当一个在 Jupyter Notebook 里流畅调用天气 API、自动写周报、还能用 LangGraph 编排三步决策流的智能体，被塞进生产环境的 CI/CD 流水线、接入真实 ERP 权限体系、扛住每秒 37 个并发请求、并在审计日志里留下可追溯的每一步动作时，它突然就“不会走路”了。这不是技术幻觉，是工程现实。

核心关键词Agent、工程解法、工具调用、权限与安全、上下文与成本，每一个都不是孤立概念，而是彼此咬合的齿轮。比如你用 LangGraph 实现了完美的工具编排逻辑（工具调用），但一旦生产环境要求所有外部 API 调用必须走统一网关并携带 RBAC Token（权限与安全），那原先硬编码的 requests.get 就立刻失效；再比如你给 Agent 设了 8K 上下文窗口（上下文与成本），但在高并发场景下，每个请求都加载完整历史会迅速耗尽 GPU 显存，导致响应延迟从 800ms 暴涨到 4.2s（成本失控）；而所谓“工程解法”，从来不是加个 Docker 容器或上个 Kubernetes 就完事——它是在工具链、权限层、内存管理、调度策略四个维度上，用可验证、可审计、可回滚的方式，把“能跑通”变成“敢上线”。

这篇文章不讲 LLM 原理，不复述 LangChain 文档，也不堆砌框架对比表。它是我作为一线工程师，在金融、制造、政务三个行业落地 7 个 Agent 项目后，亲手踩过、修过、压测过、审计过的真实记录。适合两类人：一是刚用 LangGraph 写出第一个多跳工具调用 demo、正兴奋地准备推进生产的开发者；二是技术负责人，手握预算却反复被问“为什么测试环境 99 分，上线后 SLA 掉到 62%”。全文没有一句空话，所有方案均已在至少两个不同规模客户现场稳定运行超 180 天。接下来，我们直面那四道真正卡住企业 Agent 落地的坎。

2. 四道坎的底层逻辑：为什么“能动”不等于“可用”

2.1 第一道坎：工具调用的“沙盒幻觉”与生产穿透力缺失

几乎所有新手 Demo 都始于一个干净的 Python 环境：pip install openai langgraph，写个 @tool 装饰器，调用 requests.get("https://api.weather.com/v3/weather/forecast/daily")，返回 JSON 解析后生成自然语言摘要。丝滑，惊艳。但这个流程在生产中根本不存在。

真实企业的工具生态是碎片化的：CRM 系统只提供 SOAP 接口且强制 WSDL 验证；ERP 的物料查询接口要求先调用 /auth/login 获取 session_id，再用该 session_id 作为 Cookie 发起 POST 请求；而新接入的 IoT 平台则采用 MQTT 协议，需维持长连接并处理 QoS2 确认机制。更关键的是，这些系统不接受未经签名的请求，不开放跨域，不提供 OpenAPI Spec，甚至文档里写的字段名和实际返回值不一致。

LangGraph 的ToolNode或 LlamaIndex 的FunctionCallingAgent在设计时默认假设工具是“无状态、幂等、HTTP-RESTful、带 Swagger”的理想对象。但现实是：

• 工具调用链中存在状态依赖（如登录态、事务 ID）；
• 工具响应格式高度非标准化（XML/JSON/二进制混合）；
• 工具调用本身可能触发副作用（如调用一次库存扣减接口，真实库存就少了）；
• 工具失败后不可简单重试（支付接口重复调用会引发双扣款）。

因此，“工具调用”在工程层面不是函数调用问题，而是服务治理问题。它需要：

1. 统一的工具注册中心（支持元数据标注：是否幂等、是否需鉴权、最大重试次数、失败降级策略）；
2. 工具适配层（Adapter Layer），将原始异构接口封装为标准Callable[[dict], dict]接口，并内嵌重试、熔断、缓存逻辑；
3. 工具调用审计日志（记录输入参数、原始响应、耗时、是否成功、是否触发降级）；
4. 工具沙盒隔离（每个工具在独立进程或容器中运行，防止一个工具崩溃拖垮整个 Agent 运行时）。

提示：我们曾用一个“工具适配器生成器”解决 80% 的对接问题。它接收 WSDL URL 或 Postman Collection JSON，自动生成 Python Adapter 类，包含基础鉴权、错误码映射、字段清洗逻辑。生成的代码可直接提交 Git，由 QA 手动校验后上线。比人工写 Adapter 快 5 倍，且错误率下降 92%。

2.2 第二道坎：权限与安全的“信任错配”——从开发者视角到企业合规视角

Demo 环境里，Agent 的权限模型极其朴素：if user_role == "admin": allow_all_tools()。但企业生产环境的权限体系是立体的、动态的、多维的。它至少包含三层：

• 身份层（Identity）：用户通过 SSO 登录，其身份属性（部门、职级、项目组）由 LDAP/AD 同步，而非前端传参伪造；
• 资源层（Resource）：每个工具背后对应真实业务系统中的资源（如“销售合同”、“采购订单”），资源本身有 Owner、Visibility Scope（如仅本部门可见）；
• 操作层（Operation）：对同一资源，不同角色可执行的操作不同（销售经理可审批合同，但不能修改合同金额；财务专员可查看合同金额，但不能审批）。

LangChain 的Tool或 LangGraph 的State本身不承载权限语义。当你在 State 中存入{"user_id": "U123", "role": "sales_manager"}，这只是一个字符串，无法自动约束其对update_contract_status工具的调用权限。真正的权限控制必须发生在工具执行前一刻，且需与企业现有 IAM 系统（如 Okta、Azure AD、或自研 RBAC 引擎）实时联动。

我们踩过的典型坑包括：

• Agent 用管理员 Token 调用所有工具，绕过用户级权限检查（严重越权）；
• 工具返回数据未按用户权限过滤，导致敏感字段（如客户身份证号、成本价）泄露；
• 权限变更（如员工转岗）后，Agent 缓存的权限信息未及时刷新，造成权限滞留。

工程解法不是写个@require_permission装饰器就完事。它必须是：

• 零信任网关（Zero-Trust Gateway）：所有工具调用请求必须经由统一网关，网关根据请求头中的X-User-ID和X-Auth-Token，实时向 IAM 系统查询can_user_do_action(user_id, action="update_contract", resource_id="CON-789")；
• 数据脱敏中间件（Data Sanitization Middleware）：工具返回原始数据后，网关根据用户权限策略，动态移除或掩码字段（如"id_card": "110101**********1234"）；
• 权限缓存与刷新机制：使用 Redis 存储权限缓存（TTL=5min），同时监听 IAM 系统的权限变更事件（如 Kafka Topiciam.permission.updated），收到事件后立即清除对应用户缓存。

注意：Windows 安全选项卡权限设置（如 ACL）在此场景中完全不适用。Agent 的权限控制是应用层逻辑，与操作系统文件权限无关。强行套用 Windows ACL 会导致权限粒度粗（只能控到文件/目录）、无法关联业务资源、且无法实现细粒度操作控制（如“可读不可写”、“可查不可删”）。这是新手最容易混淆的点。

2.3 第三道坎：上下文与成本的“甜蜜陷阱”——大窗口不等于好记忆

“让 Agent 记得更多”是初学者最直觉的优化方向。于是把 context_window 从 4K 拉到 32K，把 history_length 从 10 轮设为 100 轮，甚至引入 VectorDB 存储全部对话历史。结果呢？推理延迟翻倍，GPU 显存占用飙升，Token 成本暴涨，而业务效果提升微乎其微——因为 Agent 并不需要“记得全部”，它需要的是“在正确时刻想起正确信息”。

上下文膨胀的本质是信息噪声污染。一段 50 轮的对话历史中，90% 的内容与当前任务无关。LLM 的注意力机制会平均分配权重，导致关键指令（如“请用人民币报价”）被淹没在无关闲聊（如“今天天气不错”）中。我们实测过：在金融客服场景，将 history_length 从 50 轮压缩到 5 轮（仅保留最近 2 轮任务相关交互 + 当前指令），准确率反而提升 11%，首字响应时间从 2.3s 降至 0.8s。

更深层的成本陷阱在于长期记忆的工程代价。所谓 “Agent 记忆”，在工程上就是Working Memory的存储与检索。主流方案有三类：

• 短期记忆（Short-term）：存于进程内存或 Redis，生命周期 = 单次会话，成本低、速度快；
• 长期记忆（Long-term）：存于向量数据库（如 Chroma、Qdrant），需 embedding、索引、相似度检索，每次调用增加 200~500ms 延迟；
• 结构化记忆（Structured）：存于关系型数据库（如 PostgreSQL），按业务实体建模（如user_profile,order_history），查询精准但需预定义 schema。

问题在于，很多团队把所有记忆都塞进向量库，美其名曰“通用记忆”。但向量检索本质是模糊匹配，无法保证精确性。例如，用户问“我的上一份合同编号是多少？”，向量检索可能返回三份相似合同，Agent 需二次解析才能确认。而结构化查询SELECT contract_no FROM contracts WHERE user_id = 'U123' ORDER BY created_at DESC LIMIT 1，毫秒级返回唯一结果。

因此，“上下文与成本”的工程解法，核心是分层记忆架构（Tiered Memory Architecture）：

• L0 层（指令层）：当前 Prompt 中的 system_message + user_input，强制置顶，确保 LLM 优先关注；
• L1 层（会话层）：Redis 中缓存最近 3~5 轮关键 state（如{"current_order_id": "ORD-456", "selected_product": "iPhone15"}），用哈希键session:{session_id}:state存储；
• L2 层（实体层）：PostgreSQL 中按业务实体建模，Agent 通过 SQL 工具查询，而非向量检索；
• L3 层（知识层）：Chroma 中仅存高频、静态、非结构化知识（如产品说明书 PDF 的 chunk embeddings），且设置严格 relevance_threshold > 0.75。

这种分层，让 80% 的记忆访问落在 L0/L1 层（亚毫秒级），仅 20% 的复杂查询才触达 L2/L3 层，整体 P95 延迟稳定在 1.2s 以内。

2.4 第四道坎：并发与弹性的“单点幻觉”——从单机 Demo 到集群生产

Demo 总是单机、单进程、单用户。但企业级 Agent 必须支撑：

• 瞬时并发（Burst Concurrency）：如月底财务集中报销，30 秒内涌入 200+ 请求；
• 长时负载（Sustained Load）：客服系统 7×24 小时在线，平均 QPS 保持在 15~25；
• 弹性伸缩（Elastic Scaling）：凌晨低峰期自动缩容至 2 个实例，避免资源浪费。

LangGraph 的CompiledGraph默认是单进程同步执行。当 10 个请求同时抵达，它们会排队等待同一个 Python GIL 锁，CPU 利用率不足 30%，而队列积压越来越长。我们曾在一个政务项目中观察到：QPS 从 5 升到 8，平均延迟就从 1.1s 暴涨到 6.4s，P99 延迟突破 15s，用户投诉激增。

根本原因在于：Agent 的执行单元（Execution Unit）与部署单元（Deployment Unit）未解耦。Demo 中，一个 Python 进程既是 LLM 推理服务，又是工具调用协调器，还是状态管理器。生产中，这三者必须分离：

• 推理服务（Inference Service）：独立部署的 vLLM 或 Text Generation Inference（TGI）服务，提供高吞吐、低延迟的/generate接口；
• 编排服务（Orchestration Service）：轻量级 Python 服务（如 FastAPI），负责接收请求、维护 State、调用工具、组装 Prompt、调用推理服务；
• 工具服务（Tool Service）：每个工具封装为独立微服务（如weather-service,erp-adapter），通过 gRPC 或 HTTP 通信，支持独立扩缩容。

三者通过消息队列（如 RabbitMQ）或事件总线（如 Kafka）松耦合。当并发激增时：

• 编排服务实例可水平扩展（K8s HPA 基于 CPU 或 custom metric）；
• 推理服务实例可基于 GPU 显存利用率自动扩缩；
• 工具服务可根据各工具的 SLA 独立调整副本数（如 ERP 接口慢，就多扩几个 ERP Adapter 实例）。

我们最终落地的方案是：编排服务用 FastAPI + Celery（异步任务队列），推理服务用 vLLM（支持 PagedAttention），工具服务用 Go 编写（高并发、低内存占用），三者间通过 Kafka 传递TaskEvent（含 session_id, tool_name, input_params, timeout_ms）。实测在 AWS c5.4xlarge（16vCPU/32GB）节点上，单编排服务实例可稳定支撑 45 QPS，P99 延迟 < 1.8s；整套集群在 3 个节点上，轻松应对 120 QPS 瞬时峰值。

3. 四道坎的工程解法落地：从设计到部署的完整链条

3.1 工具调用工程化：构建企业级工具适配中心

工具适配中心（Tool Adapter Hub）不是代码库，而是一套可落地的工程规范与基础设施。它包含四个核心组件：

1. 工具元数据注册表（Tool Metadata Registry）
以 YAML 文件形式定义每个工具的契约，存于 Git 仓库（如tools/weather.yaml）：

name: weather_forecast_daily description: 获取指定城市未来7天天气预报 endpoint: https://api.weather.com/v3/weather/forecast/daily method: GET auth_type: api_key required_headers: - X-API-Key: ${WEATHER_API_KEY} input_schema: type: object properties: city: {type: string, description: "城市拼音，如 beijing"} language: {type: string, default: "zh-CN"} output_schema: type: object properties: forecast: {type: array, items: {type: object}} is_idempotent: true max_retries: 2 fallback_strategy: "return_cached"

该文件由业务方与开发共同维护，QA 根据此 Schema 编写自动化测试用例。

2. 自动化适配器生成器（Auto-Adapter Generator）
我们开发了一个 CLI 工具toolgen，输入上述 YAML，输出标准 Python Adapter 类：

toolgen generate --spec tools/weather.yaml --output adapters/weather.py

生成的adapters/weather.py包含：

• 基于requests.Session的连接池复用；
• 自动注入X-API-Key头；
• 对429 Too Many Requests的指数退避重试；
• 对5xx错误的 fallback 逻辑（返回缓存数据）；
• 结构化输出（自动将 JSON 转为 Pydantic Model）。

3. 工具运行时沙盒（Runtime Sandbox）
每个 Adapter 在独立子进程中运行，通过multiprocessing通信：

# orchestrator.py def execute_tool(tool_name: str, input_data: dict) -> dict: # 启动沙盒进程 proc = Process(target=sandbox_runner, args=(tool_name, input_data)) proc.start() proc.join(timeout=10) # 10秒超时 if proc.is_alive(): proc.terminate() raise ToolTimeoutError(f"Tool {tool_name} timeout") # 读取结果 result = read_result_from_pipe() return result

沙盒进程启动时，自动加载最小化依赖（仅requests,pydantic），杜绝工具间依赖冲突。

4. 工具调用审计网关（Audit Gateway）
所有工具调用请求必须经由tool-gateway服务，它记录：

• request_id,session_id,tool_name,input_hash,start_time,end_time,status_code,response_size,is_fallback；
• 日志推送到 ELK，支持按tool_name、status_code、p95_latency聚合分析；
• 当status_code == 500且p95_latency > 5s时，自动触发告警并生成根因分析报告（如“ERP Adapter 连接池耗尽”）。

这套方案在制造业客户上线后，工具对接周期从平均 5.2 人日缩短至 0.8 人日，工具故障平均定位时间从 47 分钟降至 3 分钟。

3.2 权限与安全工程化：零信任网关的实战配置

零信任网关（ZTG）是我们落地最重的一环，它不是防火墙，而是 Agent 的“权限守门人”。其核心是三个模块：

1. 权限决策引擎（PDP - Policy Decision Point）
我们选用 Open Policy Agent（OPA）作为 PDP。它接收 JSON 请求，返回allow: true/false及reason：

# policies/tool_access.rego package tool_access import data.users import data.resources default allow = false allow { # 用户存在且激活 users[user_id].status == "active" # 用户有该工具所需角色 user_role := users[user_id].role tool_roles[tool_name][user_role] # 资源可见性检查（如合同仅本部门可见） resource_dept := resources[resource_id].department user_dept := users[user_id].department resource_dept == user_dept } tool_roles["update_contract_status"] := {"sales_manager": true, "legal_officer": true} tool_roles["view_customer_data"] := {"sales_rep": true, "customer_service": true}

OPA 的优势在于策略即代码（Policy-as-Code），可版本化、可测试、可灰度发布。

2. 权限上下文注入器（Context Injector）
网关在转发请求前，从 OPA 获取决策结果，并注入必要上下文：

# gateway.py def inject_context(request: Request) -> dict: # 从 request.headers 提取 X-User-ID user_id = request.headers.get("X-User-ID") # 构造 OPA 输入 opa_input = { "user_id": user_id, "tool_name": request.tool_name, "resource_id": request.resource_id } # 调用 OPA API resp = requests.post("http://opa:8181/v1/data/tool_access/allow", json={"input": opa_input}) decision = resp.json()["result"] if not decision["allow"]: raise PermissionDenied(decision["reason"]) # 注入权限上下文到下游 return { "user_id": user_id, "allowed_actions": decision["allowed_actions"], # 如 ["read", "update"] "masked_fields": decision.get("masked_fields", []) # 如 ["id_card", "bank_account"] }

3. 数据脱敏中间件（Sanitization Middleware）
工具服务返回原始数据后，网关执行脱敏：

def sanitize_response(data: dict, masked_fields: list) -> dict: for field in masked_fields: keys = field.split(".") # 支持嵌套字段如 "customer.id_card" target = data for k in keys[:-1]: if isinstance(target, dict) and k in target: target = target[k] else: break else: if isinstance(target, dict) and keys[-1] in target: # 掩码逻辑：身份证号保留前4后4，中间* if keys[-1] == "id_card": val = str(target[keys[-1]]) target[keys[-1]] = f"{val[:4]}{'*' * (len(val)-8)}{val[-4:]}" elif keys[-1] == "bank_account": target[keys[-1]] = "***" + str(target[keys[-1]])[-4:] return data

该中间件已集成到所有工具服务的 SDK 中，开发者只需调用sanitize_response(data, context['masked_fields'])即可。

在政务项目中，ZTG 上线后，权限相关安全审计问题从每月 3.7 个降至 0，且所有权限变更（如新增角色）均可在 5 分钟内全网生效，无需重启任何服务。

3.3 上下文与成本工程化：分层记忆架构的代码实现

分层记忆架构（TMA）的落地，关键在于让每一层的记忆都有明确的生命周期、访问路径和成本边界。以下是核心代码片段：

1. L0 指令层：Prompt 工程化模板
我们摒弃了硬编码 Prompt，改用 Jinja2 模板 + 预处理器：

<!-- prompts/contract_assistant.j2 --> {{ system_prompt }} {% if session_state.current_order_id %} 上下文：用户正在处理订单 {{ session_state.current_order_id }}。 {% endif %} {% if session_state.selected_product %} 用户已选择产品：{{ session_state.selected_product }}。 {% endif %} 用户最新提问：{{ user_input }}

预处理器prompt_builder.py动态注入session_state，确保 L0 层永远只包含强相关上下文，长度严格控制在 512 tokens 内。

2. L1 会话层：Redis 状态管理
使用 Redis Hash 存储会话状态，Key 为session:{session_id}:state：

# memory/l1_session.py class SessionMemory: def __init__(self, redis_client): self.redis = redis_client def get_state(self, session_id: str) -> dict: # 仅获取 hash 中的特定字段，避免全量加载 return self.redis.hgetall(f"session:{session_id}:state") def update_state(self, session_id: str, updates: dict): # 原子性更新 self.redis.hset(f"session:{session_id}:state", mapping=updates) def expire_after(self, session_id: str, seconds: int): self.redis.expire(f"session:{session_id}:state", seconds)

每个会话状态 TTL 设为 30 分钟，超时自动清理，无内存泄漏风险。

3. L2 实体层：SQL 工具封装
为避免 LLM 直接生成 SQL，我们提供预定义的 SQL 工具：

# tools/sql_tools.py @tool def get_user_contracts(user_id: str) -> List[Contract]: """获取用户所有合同（结构化查询）""" with db_session() as conn: rows = conn.execute( text("SELECT id, status, amount FROM contracts WHERE user_id = :uid ORDER BY created_at DESC LIMIT 5"), {"uid": user_id} ).fetchall() return [Contract(id=r[0], status=r[1], amount=r[2]) for r in rows] @tool def update_contract_status(contract_id: str, new_status: str): """更新合同状态（带权限校验）""" # 此处调用 ZTG 的权限检查 check_permission("update_contract_status", contract_id) # 执行更新 with db_session() as conn: conn.execute( text("UPDATE contracts SET status = :status WHERE id = :cid"), {"status": new_status, "cid": contract_id} )

所有 SQL 工具均经过 SQL 注入扫描（sqlmap），且只允许 SELECT/UPDATE，禁用 DROP/DELETE。

4. L3 知识层：Chroma 向量库精简配置
我们限制向量库仅用于非结构化知识检索，并设置严格阈值：

# memory/l3_knowledge.py class KnowledgeMemory: def __init__(self, chroma_client): self.client = chroma_client self.collection = self.client.get_or_create_collection( name="product_knowledge", metadata={"hnsw:space": "cosine"} # 使用余弦相似度 ) def query(self, query_text: str, top_k: int = 3) -> List[Document]: results = self.collection.query( query_texts=[query_text], n_results=top_k, include=["documents", "metadatas", "distances"] ) # 严格过滤：只返回 distance < 0.25 的结果（高置信度） filtered = [] for i, dist in enumerate(results["distances"][0]): if dist < 0.25: filtered.append(Document( content=results["documents"][0][i], metadata=results["metadatas"][0][i] )) return filtered

distance < 0.25是我们通过 A/B 测试确定的阈值，低于此值的检索结果准确率 > 94%，高于则噪音显著增加。

这套 TMA 在金融项目中，将单次请求的平均 Token 消耗从 12,400 降至 3,800，LLM 服务月成本下降 68%，而业务指标（如合同查询准确率）保持 99.2% 不变。

3.4 并发与弹性工程化：K8s + vLLM + Kafka 的生产部署栈

生产部署栈不是堆砌新技术，而是让每个组件承担其最擅长的角色。我们的最终架构如下：

部署流程（CI/CD Pipeline）：

1. 开发提交adapters/erp.py到 Git；
2. CI 触发toolgen test --spec tools/erp.yaml，运行自动化测试；
3. 测试通过后，构建erp-adapter:v1.2.0镜像，推送到 Harbor；
4. Argo CD 自动部署新镜像到 K8s，滚动更新；
5. 新实例启动后，向 Kafka 发送ServiceReadyEvent，编排服务订阅该事件，将其加入可用工具池。

弹性伸缩策略：

• 编排服务：HPA 基于celery_queue_lengthcustom metric（从 Prometheus 抓取），当队列长度 > 50，扩容至最多 12 个实例；
• vLLM 服务：HPA 基于gpu_memory_utilization，当显存使用率 > 85%，扩容至最多 6 个实例；
• ERP Adapter：HPA 基于http_request_duration_seconds_bucket{le="2.0"}，当 P90 延迟 > 1.5s，扩容至最多 8 个实例。

我们曾对该栈进行混沌工程测试：随机 kill 1 个 vLLM 实例，系统在 12 秒内自动恢复，P99 延迟波动 < 0.3s；模拟 Kafka broker 故障，消息积压在 30 秒内被消费完毕，无消息丢失。整套系统在客户生产环境已稳定运行 217 天，SLA 达 99.95%。

4. 常见问题与排查技巧实录：来自生产环境的 12 个血泪教训

4.1 工具调用类问题

Q1：工具调用返回 401 Unauthorized，但 Postman 测试正常
根因：Postman 使用浏览器 Cookie，而 Agent 服务未携带会话 Cookie。
排查：抓包对比 Postman 与 Agent 请求的 headers，重点看Cookie和Authorization。
解法：在工具适配器中，显式管理requests.Session()，并在首次登录后持久化session.cookies。切勿用requests.get(url, cookies=...)临时传参。

Q2：ERP 接口调用偶尔超时，日志显示连接被拒绝
根因：ERP 系统设置了连接池上限（如 Tomcat maxConnections=200），而 Agent 并发数超过此值。
排查：在 ERP 服务器上执行netstat -an | grep :8080 | wc -l，确认 ESTABLISHED 连接数是否接近上限。
解法：在工具适配器中，配置requests.Session()的pool_connections=10和pool_maxsize=10，限制单实例最大连接数；同时在 K8s 中为 ERP Adapter 设置resources.limits.cpu=500m，防止单实例发起过多连接。

Q3：天气 API 返回数据中，温度字段有时是字符串 "25°C"，有时是数字 25
根因：API 提供商未遵守 OpenAPI Spec，返回类型不一致。
排查：开启工具适配器的log_raw_response=True，收集 100 次响应，统计字段类型分布。
解法：在适配器的parse_response()方法中，强制类型转换：temp = float(str(resp['temp']).replace('°C', '').strip())，并添加异常兜底except (ValueError, KeyError): temp = 0.0。

4.2 权限与安全类问题

Q4：ZTG 返回 allow=true，但工具服务仍报权限不足
根因：ZTG 与工具服务的权限上下文未同步。ZTG 检查的是user_id，而工具服务校验的是session_token。
排查：检查 ZTG 日志中的decision输出，与工具服务收到的X-User-IDheader 是否一致。
解法：统一使用X-User-ID作为权限上下文传递标准，禁止工具服务自行解析 Token。所有权限校验必须由 ZTG 完成，工具服务只做数据操作。

Q5：用户反馈能看到其他部门的合同，但 ZTG 日志显示权限检查通过
根因：ZTG 的resource_dept == user_dept检查逻辑有缺陷，未考虑“跨部门协作”场景（如法务部可查看所有合同）。
排查：检查 OPA 策略中tool_roles的定义，确认是否遗漏了跨部门角色。
解法：重构 OPA 策略，引入resource_visibility字段：resource_visibility: ["department", "company", "public"]，并修改检查逻辑为resource_visibility in ["department", "company"]。

Q6：脱敏中间件未生效，身份证号明文返回
根因：脱敏中间件位于 HTTP 响应链末端，而工具服务返回的是StreamingResponse（如 SSE），中间件无法拦截流式数据。
排查：检查工具服务的返回类型，确认是否为StreamingResponse或Response(content=...)。
解法：对流式响应，改用StreamingResponse的content参数包装，或在工具服务内部完成脱敏，而非依赖网关。

4.3 上下文与成本类问题

Q7：Agent 在长对话中开始“忘记”最初的任务目标
根因：L0 层 Prompt 中的 system_message 被过长的对话历史稀释，LLM 注意力偏移。
排查：打印每次请求的完整 Prompt，观察 system_message 是否被挤到 token 末尾。
解法：在 Prompt 模板中，强制将 system_message 置顶