Agent-Reach：构建智能体统一触达层，解决大模型调用外部系统的最后一公里

1. Agent-Reach 到底在解决什么问题：大模型时代的“最后一公里”困局

做 Agent 应用做了快两年，我越来越清楚地意识到一件事：现在的智能体，聪明是真的聪明，但“够不着”也是真的够不着。

什么意思？就是说模型本身的推理能力、规划能力、指令遵循能力，在 GPT-4 这个级别之后已经相当能打了。你让它写一封邮件、写一段代码、整理一份会议纪要，它都能干得有模有样。但一旦你希望它真正去干点“实事”——比如登录内部系统查一个订单、调一个第三方API发消息、把一份报表从数据库里取出来推到钉钉群——绝大多数 Agent 就卡住了。

卡住的原因不是模型不够聪明，而是 Agent 和外部世界之间缺了一层东西。这层东西，我给它起了个名字叫Agent-Reach，直译过来就是“智能体的触达能力”。简单说，就是 Agent 能不能真正碰到它想操作的那个系统、那个数据、那个工具。

你说这不就是工具调用（Function Calling）嘛？大模型平台不是都支持了吗？

对，也不对。Function Calling 解决的是“模型知道你有哪些函数、并且能输出一个规范的调用意图”，但它没有解决后面一连串更麻烦的问题：这个函数背后是 HTTP 接口还是 RPC？需要什么鉴权方式？超时失败怎么办？要不要限流？调用的操作涉及敏感数据，审批流怎么走？一个长任务里要连续调几十个工具，上下文塞不下怎么处理？这些才是真实业务场景里真正要命的事。

Agent-Reach 的项目定位，就是专门做这一层：Agent 与外部世界的统一触达层。它不是又一个大模型框架，不关心你用的是 LangChain、AutoGen 还是自己撸的 Pipeline，它只解决一件事——让 Agent 以统一、安全、可靠的方式，真正调用到它需要的任何内部或外部能力。

这玩意儿适合谁看？如果你是做 AI 应用开发的工程师、算法工程师想往工程方向多走一步，或者你自己在做 Agent 类产品但发现模型“只会说不会做”，那这篇博文应该能帮你在架构认知上补上关键的一环。我会从设计思路、核心技术拆解、实际部署流程到踩坑实录，完整讲一遍。

2. 整体设计思路：为什么 Agent 离“什么都能干”总差一步

先说一个我在多个项目里反复看到的共性现象：团队花了大精力把底座模型调好了、Prompt 也优化得不错，Agent 在 Demo 环境里表现惊艳，但一进到真正的业务系统里就“破功”。要接 ERP，人家是 SOAP 老接口；要查数仓，得走跳板机；要发消息，得对接五六个不同的 IM 平台。每个系统都有自己的协议、自己的认证方式、自己的数据格式。Agent 再聪明，面对这种巴别塔式的碎片化，也会一脸懵。

Agent-Reach 的出发点就是把这些乱七八糟的外部依赖抽象成一层，让 Agent 只需要面对一种统一的“能力描述”，而把所有协议适配、参数转换、鉴权、容错、审计的脏活累活，全部收编到触达层内部来处理。

2.1 方案选型：三层抽象而不是一把梭

我最早也想过简单方案：给 Agent 暴露一堆 Python 函数，让模型直接调。做出来之后发现只适合 Demo，完全扛不住生产环境的复杂性。第一，函数多了之后，模型光记住这些函数签名就消耗大量上下文token；第二，函数的入参出参都是强类型约束，模型的输出稍微飘一下就报错；第三，安全完全没保障，任何 Agent 都能调任何函数，出事了都不知道找谁。

后来我彻底重构成三层抽象，这是 Agent-Reach 的核心骨架：

能力层（Capability Layer）：定义“这个 Agent 能做什么”。每个能力是一个统一格式的描述单元，包含能力名称、能力说明、输入输出 Schema、权限要求、调用方式。Agent 只跟这一层打交道，不需要知道下面的事。

适配层（Adapter Layer）：负责把统一的能力调用请求翻译成具体系统能理解的协议调用。比如有一个能力叫“查询订单”，适配层会根据目标系统的不同，分别翻译成 HTTP GET 请求、SQL 查询，或者老系统的 XML-RPC 调用。这一层就是“翻译官”。

通道层（Channel Layer）：管理实际的数据通路和基础设施。连接池、超时控制、重试策略、限流熔断、日志审计，都在这一层完成。

这三层配合起来的效果是：Agent 侧只需要理解一套规范的能力清单，而新增一个业务系统，也不需要动 Agent 的逻辑，只要写一个适配器挂进来就行。两边的耦合度降到最低，这也是这个方案能持续演进的关键。

2.2 为什么叫“触达”而不是“调用”：连通只是第一步

我在设计这个概念时下意识用的是“Reach”而不是“Call”，其实是经过思考的。Call 只代表一次性的请求-响应，而 Reach 强调的是一种持续可用的连通关系。

打个比方，Call 像是你打一次电话问路，挂了就完了；Reach 是你在一个城市里修好了路网，之后去哪都通。Agent-Reach 想建立的正是后者。它不满足于“这次把工具调通了”，而是追求“Agent 和外部系统之间形成一套稳定的、可管控的、可观测的连通机制”。

在这种思路下，Agent-Reach 除了基础的函数调用，还包含几个延伸能力：

• 能力发现：Agent 启动时动态加载可用的能力清单，而不是把工具死编码在代码里。新增一个工具，不用重新发布 Agent 服务。
• 多模态触达：一个能力可能同时有 API 方式、数据库方式、文件传输方式等多个通道可达，触达层会根据当前环境自动选择最优通道。
• 主动性触达：Agent 不仅响应请求，还能根据配置的规则或定时任务，主动地去触碰外部系统获取数据。比如每小时自动去拉一次最新库存。

“触达”这个词背后代表的，是整个 Agent 从“被动应答”到“主动作业”的范式转变。这是我做 Agent-Reach 这几个月最核心的认知升级。

2.3 核心目录结构：一个可以照着搭的工程骨架

项目我用的 Python 3.11 + FastAPI 做的底座，实际生产环境里 Python 做 AI 生态集成最省事，FastAPI 在异步处理和高并发上表现不错。核心目录结构长这样：

agent-reach/ ├── core/ # 核心层：能力定义与调用引擎 │ ├── capability.py # 能力描述的数据模型 │ ├── registry.py # 能力注册中心，维护可用能力清单 │ ├── dispatcher.py # 调用分发器，路由到对应适配器 │ └── context.py # 调用上下文管理，链路追踪 ├── adapters/ # 适配层：每个子目录一种协议 │ ├── http_adapter/ # HTTP/HTTPS 适配 │ ├── sql_adapter/ # 数据库查询适配 │ ├── mq_adapter/ # 消息队列适配（Kafka / RabbitMQ） │ └── browser_adapter/ # 浏览器自动化适配（Playwright 封装） ├── channels/ # 通道层：底层连接与通信 │ ├── connection.py # 连接池管理 │ ├── retry.py # 重试与熔断策略 │ └── audit.py # 审计日志 ├── security/ # 安全模块 │ ├── auth.py # 统一鉴权入口 │ ├── permission.py # 细粒度权限控制 │ └── validator.py # 输入输出安全校验 └── server/ # 服务入口 ├── api.py # 对外 HTTP API └── config.py # 全局配置加载

这套结构的核心调度逻辑在dispatcher.py里：Agent 发来一个统一格式的调用请求，分发器先查注册中心找到对应的能力定义，再根据定义中的适配器类型路由到具体的 adapter，adapter 执行完毕后把结果标准化返回，整个过程全程走审计日志。后面我会展开讲这几个关键模块的实现细节。

3. 核心细节与实操：能力描述协议和适配器开发是关键

整个 Agent-Reach 最核心的部分，不是代码量最大的部分，而是那个容易被低估的能力描述协议（Capability Description Protocol, CDP）。它决定了 Agent 能不能准确理解你暴露给它的每一个操作，也决定了调用成功率的上限。

3.1 能力描述协议：Agent 与世界的“通用语言”

你可以把 CDP 理解成一份给 Agent 看的“接口说明书”。跟人类开发时的 API 文档不同，Agent 不会自己去翻长文档再理解上下文，它需要的是结构化、无歧义、能直接作为模型输入的能力描述。

我用的 CDP 格式是 JSON Schema 的超集，每个能力包含五个核心字段：

{ "name": "create_work_order", "description": "创建一条新的维修工单，支持指派给指定工程师，创建后自动通知相关人员", "tags": ["work-order", "maintenance"], "input_schema": { "type": "object", "properties": { "title": {"type": "string", "description": "工单标题，一句话概括问题"}, "priority": {"type": "string", "enum": ["high", "medium", "low"], "description": "工单优先级"}, "assignee_id": {"type": "string", "description": "处理人ID，可选，留空则进入待分配池"}, "description": {"type": "string", "description": "详细问题描述"} }, "required": ["title"] }, "output_schema": { "type": "object", "properties": { "work_order_id": {"type": "string"}, "status": {"type": "string"}, "created_at": {"type": "string"} } }, "permission_required": "work_order:create", "adapter": "http", "endpoint_config": {"service": "erp", "path": "/api/v1/work-orders", "method": "POST"} }

这里有几个实操中的经验教训，值得单独说。

description 字段是成败关键。大模型的工具选择能力高度依赖描述文本的质量。你写“创建工单”四个字，它在面对相似工具时会犹豫不决；但你写清楚“创建一条新的维修工单，支持指派、通知”，它就能准确判断什么时候该用这个工具。描述要包含触发场景（什么情况下用）、参数含义（每个字段代表什么）、操作后果（会有副作用）。我实测下来，描述多写 50 个字，工具选择准确率能提升 10 到 15 个百分点。

input_schema 必须做全字段描述和约束。别偷懒不写 properties 里每个字段的 description，也别省略 enum 约束。大模型对没有约束的参数会自由发挥，比如 priority 不写 enum，它就有可能给一个 “urgent” 这种不存在的值。写了 enum 基本能保证输出值在合法区间内。

output_schema 别忽略。一方面它能让 Agent 知道调用后会拿到什么结构的数据，方便后续规划；另一方面，触达层可以对输出做强校验，不符合预期的直接判失败，防止脏数据污染下游逻辑。

3.2 适配器开发规范：新系统接入 30 分钟内完成

CDP 定了之后，接下来的问题就是：给一个新系统写适配器，怎么写最快、最稳？

我在项目里总结出一套五步法，新同事照着走基本 30 分钟就能完成一个简单适配器：

1. 梳理系统的触达方式：先搞清楚目标系统提供什么接口。有 HTTP API 就走 HTTP 适配器，只有数据库就给只读账号走 SQL 适配器，什么接口都没有但有人机界面，就走浏览器适配器。
2. 定义能力清单：把业务操作逐个映射成 CDP 格式的能力描述，每个操作一个 JSON 文件。这里要跟业务方确认清楚操作边界和副作用。
3. 实现适配器类：继承基类 BaseAdapter，实现execute(params)方法。

# agent_reach/adapters/http_adapter.py import httpx from agent_reach.core.capability import BaseAdapter class HttpAdapter(BaseAdapter): """通用HTTP适配器，按endpoint_config配置发请求""" async def execute(self, capability, params, context): config = capability.endpoint_config url = f"{config['service_url']}{config['path']}" headers = context.get_headers(config['service']) timeout = context.timeout async with httpx.AsyncClient() as client: if config['method'] == 'GET': resp = await client.get(url, params=params, headers=headers, timeout=timeout) else: resp = await client.post(url, json=params, headers=headers, timeout=timeout) resp.raise_for_status() return resp.json()

4. 配置权限策略：在权限配置里声明该适配器下所有能力的权限标签，并分配默认角色。
5. 联调验证：写一组测试用例，覆盖正常流程、参数缺失、超时、鉴权失败四类情况，跑通后注册进能力中心。

这套流程最大的好处是标准化。写适配器的时候不需要关心 Agent 那边怎么调用，只管把“能力”翻译成“目标系统动作”就行。之后的调试和维护都变得非常清晰，因为每个环节的职责边界是明确的。

3.3 智能调度引擎：Agent 与外部系统的执行统筹

适配器解决了“怎么调”，还需要一个核心模块解决“什么时候调、怎么编排、调完怎么处理”。这就是调度引擎做的事。

调度引擎的核心功能有三个：

• 并发控制：当 Agent 规划出一个多步骤任务，比如“先查库存，再比对订单，最后生成采购单”，这些步骤有依赖关系，直接并发执行就乱套了。调度引擎内置 DAG 依赖解析，能自动识别步骤间的前后依赖，把无依赖的并行执行，有依赖的串行等待。
• 动态超时管理：不同的外部系统响应速度差异巨大。查缓存 50 毫秒返回，跑一个复杂报表可能要 20 秒。统一固定超时时间会让前者白白等待、后者频繁被中断。调度引擎会为每个能力配置独立的超时档位，并支持按历史调用耗时自动调整。
• 异常补偿编排：外部调用总有失败的时候。调度引擎支持定义失败后的补偿动作，比如调用 A 系统失败后，自动切换 B 通道重试，或者把任务放入重试队列并通知管理员。

我在一个实际项目里用到了全部三个能力：Agent 需要跨三个系统完成“客户投诉理赔全流程”，涉及客户系统查询、订单系统核验、财务系统打款。调度引擎先把三个子任务按依赖关系排好，订单核验和客户查询并行跑，财务打款等前面两个都成功后再执行。中间还设置了重试规则：财务系统偶发超时，重试一次成功率能从 70% 提到 95% 以上。这就是调度层的价值，它让 Agent 不再是“调一次工具等一次结果”，而是能真正统筹一个完整业务流程的执行。

4. 安全与权限设计：Agent 能触达一切之前先要解决“能不能碰”

说实话，做 Agent-Reach 这类的项目，最难的不是功能实现，而是安全和权限体系的设计。Agent 不像人，它不会“临场判断”某个操作是否越界，它只会按照规划去执行。这意味着，你的权限控制必须做到比给人工账号更细、更严。

4.1 最小够用原则在 Agent 场景下的落地方式

传统的 RBAC（基于角色的访问控制）模型在 Agent 场景下不够用。因为一个 Agent 可能服务于多种业务场景，在不同上下文中拥有不同的操作边界。比如同一个“客服助手” Agent，处理普通咨询时只能查订单，处理退款申请时才有退款权限。如果只给 Agent 配一个固定角色，权限非大即小，都不可行。

我采用的方案是动态权限上下文：每次调用不仅校验“这个 Agent 有没有权限做这个操作”，还校验“在当前对话上下文/任务上下文里，这个操作是否被允许”。

具体实现是两个叠加层：

• 静态权限表：定义 Agent 类型、能力、允许的操作三元组关系。这是白名单，Agent 只能触达白名单内的能力。
• 运行时策略：根据当前任务的目的、涉及的用户级别、数据敏感度实时计算一个“权限分数”，低于阈值的直接拒绝。

举个例子：一个常规咨询任务，Agent 查询订单详情，静态权限表允许，运行时策略判定该操作与任务意图匹配，放行。但如果 Agent 突然尝试调用“批量导出全量客户数据”能力，静态权限表可能都不需要配置，运行时策略会根据数据敏感度直接拦截，并给管理员推送告警。

4.2 敏感操作的双人复核机制

在权限设计中，有一类操作我坚持要做人工复核：涉及资金、隐私、数据删除等高风险能力的调用。

具体做法是，这类能力在 CDP 定义里打上"requires_approval": true的标记。调度引擎识别到标记后，不会直接执行，而是把调用请求挂起，生成一个审批任务推送到飞书/钉钉/企业微信的管理员工作台。管理员点了同意，调用才真正发出。

最开始我只在“财务打款”这种操作上开了审批，后来一次误删数据的事故让我把所有delete_开头的操作也全部加了审批。代价是每个删除任务多等几分钟的人工响应，但换来的是“永远不会因为模型幻觉执行不可逆操作”的安全感。这个值得。

4.3 全程审计与追溯：出事之后能查、能对、能复盘

安全体系最后一块拼图是可观测性。Agent-Reach 里的每一次触达，不管成功失败，都会落一条审计日志，包含：时间戳、Agent ID、能力名称、触达的目标系统、入参摘要（敏感字段脱敏）、出参摘要、执行耗时、调用的模型推理 ID、审批人（如果有审批环节）。

为什么强调这些字段？因为 Agent 的行为链路是多跳的，一个最终动作可能是模型在第三次推理时才决定的，中间经历了什么得靠推理 ID 串起来。有了这条完整链路，出问题了能快速定位是 Agent 规划错误、能力描述歧义还是适配器代码 bug，而不是对着日志大海捞针。

我还会定期跑一个审计分析任务，统计哪些 Agent 调了哪些能力、频率如何、失败率多高、有没有异常调用模式。这些数据反过来能帮助优化能力描述、完善权限表，是一个不断迭代的正循环。

5. 从零部署一套 Agent-Reach：完整实操流程

理论说了一大堆，实际跑起来才是真的。这一节我按我自己的环境（Ubuntu 22.04，Docker 部署）记录一遍完整流程，从环境准备到第一个 Agent 成功触达外部服务。

5.1 环境准备与依赖安装

# 系统依赖 sudo apt update && sudo apt install -y python3.11 python3.11-venv redis-server # 创建虚拟环境 python3.11 -m venv venv source venv/bin/activate # 安装项目依赖 pip install fastapi uvicorn[standard] httpx pydantic redis apscheduler python-jose passlib # 如果要用浏览器适配器，还要装 Playwright pip install playwright playwright install chromium

这里有个经验之谈：Redis 一定要装，Agent-Reach 的能力注册缓存、调用队列、分布式锁都要用到它。走了不少弯路才意识到这件事。

5.2 快捷启动配置文件

在项目根目录创建config.yaml，这是整个服务的总装配文件：

server: host: "0.0.0.0" port: 8900 redis: url: "redis://localhost:6379/0" registry: scan_paths: - "./capabilities" # 能力定义文件目录 auto_reload: true # 配置文件变更自动热加载 security: jwt_secret: "please-change-me" token_expire_hours: 24 default_approval_timeout: 3600 # 审批超时秒数 channels: http: max_connections: 200 connect_timeout: 5 read_timeout: 30 sql: max_connections: 50 pool_recycle: 3600 audit: backend: "redis" log_level: "info"

配置里registry.scan_paths是最实用的一个参数，它指定了能力定义文件所在的目录，启动时会自动扫描加载。配合auto_reload: true，你在capabilities目录里新增一个 JSON 能力文件，服务会在几秒钟内自动感知，Agent 侧立即可用。这个特性对调试太方便了，不用为每个新工具重启服务。

5.3 编写并注册第一个自定义能力

我们来实现一个“获取纳斯达克指数实时行情”的能力。假设有一个外部行情 API 提供这个数据（这里用模拟接口演示）。

第一步，在capabilities目录创建stock_quote.json：

{ "name": "get_nasdaq_quote", "description": "获取纳斯达克指数当前点位和涨跌幅，适用于用户询问美股大盘情况、指数行情等场景", "tags": ["stock", "market"], "input_schema": { "type": "object", "properties": {}, "required": [] }, "output_schema": { "type": "object", "properties": { "index": {"type": "string"}, "value": {"type": "number"}, "change_percent": {"type": "number"}, "updated_at": {"type": "string"} }, "required": ["index", "value", "change_percent"] }, "permission_required": "market:read", "adapter": "http", "endpoint_config": { "service": "market-api", "path": "/v1/index/nasdaq", "method": "GET" } }

第二步，在服务配置里注册这个外部服务（services.yaml）：

services: market-api: base_url: "https://api.simulated-market.example.com" auth_type: "api_key" api_key_env: "MARKET_API_KEY" timeout: 10

第三步，在权限表里加一条白名单：

permissions: - agent_type: "finance_assistant" capabilities: ["get_nasdaq_quote"] allowed: true

完成这三步，重启服务，Agent 侧就能看到这个新能力并开始调用了。整个新增能力的过程，实际就是复制 JSON、填参数、配权限三步，没有写一行 Python 代码。这也是 Agent-Reach 设计上很在意的一点：业务能力的接入不该依赖专门的开发工作，配置化、声明式是它的正确形态。

5.4 通过 API 网关发起一个真实调用

Agent-Reach 本身提供 HTTP API，LLM 应用层可以直接调用：

curl -X POST http://localhost:8900/v1/call \ -H "Authorization: Bearer <你的Token>" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "finance_assistant", "capability": "get_nasdaq_quote", "params": {}, "trace_id": "test-001" }'

正常响应：

{ "success": true, "result": { "index": "NASDAQ", "value": 17862.31, "change_percent": 0.74, "updated_at": "2025-02-18T14:30:00Z" }, "trace_id": "test-001", "latency_ms": 213 }

实际接入 LangChain 或自研 Agent 框架时，只需要把 Agent-Reach 封装成 BaseTool 的一个实现，让模型把它看成是一个普通的工具函数即可。这里面额外的收益是，Agent 侧的消息量大幅减少——能力清单在 Agent-Reach 侧维护并注入系统提示词，而不是把所有参数枚举都堆进每次请求里，token 开销能省不少。

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

在 Agent-Reach 的开发迭代过程中，我踩过不少坑，下面这些是高频问题里最有代表性的，整理出来给后来人当“避雷针”。

6.1 模型总是选错工具？八成是描述文本的问题

现象：Agent 明明看到了能力清单，但在相似能力之间总是选错，或者该用工具的时候不用。

排查思路：先把问题分清楚，是“没看到”还是“看到了选不对”。前者检查能力清单是否成功注入系统提示词、有没有被 token 截断；后者几乎可以断定是描述文本质量的问题。

实战解法：我给团队定了一条规则，描述文案必须包含“触发场景 + 参数含义 + 操作副作用”三要素。

• 错误示例："获取天气数据"——触发场景不明确，跟其他天气类能力区分不开。
• 正确示例："根据城市名称获取未来7天天气预报，包含温度、湿度、降水概率，适用于用户询问出行天气、穿衣建议等场景"。

改完描述之后，同样的能力列表，模型选对的概率明显提高。此外还可以给频率高的能力在 tags 里加一些别名关键词，比如“明天会下雨吗”这种口语化表达能更容易关联到天气能力。

6.2 能力调用超时严重？检查一下是不是忽略了鉴权耗时

现象：某些服务调用间歇性超时，手机端看到经常是“服务繁忙”或者“请求超时”。

排查思路：第一反应是服务端负载问题，但查了半天发现很多超时来自鉴权环节。目标服务用的是 OAuth2.0，每次调用前都要先请求一次 Token，而 Token 服务在高峰期响应很慢。等 Token 拿到再发业务请求，时间已经过去了大半。

实战解法：在适配器里加 Token 缓存机制，提前申请，快过期时异步刷新，不要让每次业务调用都等一次鉴权往返。另外把“鉴权耗时”单独纳入超时预算管理，业务超时和鉴权超时分别计算，别让鉴权卡死整个调用链路。

# agent_reach/adapters/oauth_cache.py from cachetools import TTLCache class OAuthTokenCache: """OAuth Token缓存，提前几分钟刷新避免业务调用被鉴权阻塞""" def __init__(self, auth_client): self._cache = TTLCache(maxsize=16, ttl=3500) self._auth_client = auth_client async def get_token(self, service): token = self._cache.get(service) if token: return token token = await self._auth_client.fetch_token(service) self._cache[service] = token return token

TTL 设置在 3500 秒，是为了比多数 Token 的 3600 秒有效期提前一点刷新，避免临界竞争。

6.3 复杂任务中途失败，怎么快速定位故障点？

现象：Agent 执行一个跨系统多步骤任务，中途某一环失败，整个任务回滚。但从 Agent 的对话界面看，只知道“操作失败”，不知道具体是哪个系统、哪个环节出了问题。

排查思路：这就要回到前面讲的审计链路了。用 trace_id 去审计日志里查，按时间顺序能看到每一步调用的真实状态。如果是 HTTP 502，多半目标服务挂了；如果是权限拒绝，检查权限表配置；如果连请求都没发出去，多半是调度引擎卡在审批环节。

实战解法：我在调度引擎里给每个子任务加上状态标签：pending -> dispatching -> approved（如需审批）-> executing -> success / failed / retrying。每一步的切换都实时写入 Redis，并对外暴露一个查询接口。前端可以做一个简单的执行状态看板，Agent 执行到哪一步、卡在哪一步，一目了然。这比让用户对着聊天窗口猜要靠谱得多。

还有一个很实用的小技巧：给每个子任务加上一个短描述，失败时把错误信息拼到一起返回给 Agent，Agent 能根据错误信息自动调整策略。比如查订单服务失败时，如果错误信息是权限不足，Agent 就会换成“查询本地缓存版本”的备用方案，整个流程的兜底性会好很多。

6.4 高频能力调用性能瓶颈：从优化连接池到预热

压测跑下来发现“查订单”这个高频能力 TPS 上不去，服务端日志里看到大量 TIME_WAIT 状态的连接。问题出在底层连接池默认配置太保守。

后来我在通道层做了三件事：

• 增大 HTTP 连接池的max_connections，并开启 keep-alive 复用；
• 把 SQL 适配器的连接池pool_pre_ping打开，防止拿到失效连接；
• 在服务启动时对高频能力做一次预热调用，把连接、权限缓存、鉴权缓存全部预先填充好。

这套组合拳打完，压测 TPS 从 80 提到了 200 以上。对于 Agent 场景来说，单个 Agent 的调用频率其实不高，但多个 Agent 并发接入时，这个优化收益就很明显了。

7. 实测性能数据与容量参考

分享一组我在内部环境做压测的数据，供你在做容量规划时参考。环境：8C16G 虚拟机，Agent-Reach 单节点，后端依赖一个模拟外部 API（平均响应 35ms）。

单节点跑 20 个并发 Agent 完全没压力，瓶颈通常不在 Agent-Reach 本身，而在目标系统的响应能力。如果你的业务需要更高并发，建议把调度引擎和适配器分别横向扩容，中间用 Redis 做消息缓冲，这样能扛到几百个 Agent 同时在线调用。另外提醒一句，服务节点尽量与目标系统部署在同一内网，跨公网调用会显著放大延迟和失败概率。

8. 最后的一些思考

Agent-Reach 这个项目做下来，我最深的体感是：大模型时代真正稀缺的能力，不是“让模型更聪明”的调优技巧，而是“让聪明能落地”的工程化能力。模型再强，如果无法安全、可靠、高效地触达真实世界的数据和系统，那么它在业务场景里的价值就会大打折扣，只能停留在“演示惊艳、生产拉垮”的尴尬境地。

如果你也在做 Agent 类应用，我的建议是：在卷 Prompt、卷模型微调之外，留一些精力好好设计你的工具触达层。把能力的标准化描述做好，把权限边界设计得更严谨一点，把调用链路的可观测性建设起来。这些“看起来不酷”的工作，恰恰是决定你的 Agent 能否从 Demo 走向生产的关键。

关于这个项目，我目前还在持续迭代的方向有两个：一是把适配器生态做得更丰富一些，尤其是老系统常见的 XML-RPC 和文件传输类协议的适配；二是在触达层内置一个简单的 LLM 能力路由，让 Agent 在决策时能直接拿到每个可用能力的质量分和调用成本，从而做出更优的执行规划。这两个方向跑通之后，我会再写一篇续篇分享心得。