Agent-Reach：多智能体触达与调度层架构实践-二趣网

1. 项目概述与设计初衷

1.1 Agent-Reach 是什么

做 AI Agent 应用的同学，大概率都遇到过同一个尴尬：Agent 单个跑得很聪明，一旦要让多个 Agent 协作、按流程把任务分出去，就立刻变成“各干各的、谁也找不到谁”。Agent-Reach 就是为这个问题做的开源基础设施，定位是给多智能体系统提供一套统一的触达与调度层——说人话就是，让任意一个 Agent 能按名字或能力找到另一个 Agent，把任务发过去、拿到结果，并且整个过程可监控、可恢复、可排查。

我最早做多 Agent 系统时，最头疼的不是 Prompt 怎么设计，而是通信。微服务之间至少有 HTTP、RPC、消息队列这些成熟方案，Agent 之间却几乎没有标准化消息格式。你写一个 Agent 往另一个 Agent 发 JSON，另一边解析不了就整个崩溃。更麻烦的是，Agent 实例是动态拉起、随时销毁的，你根本不知道现在哪几个 Agent 还活着。Agent-Reach 恰好把这层“人肉协调”自动化了。

1.2 它要解决的核心问题

Agent 协作系统里排前三的痛点，Agent-Reach 都有对应的设计目标：

寻址难：微服务靠服务名 + 注册中心定位，Agent 却缺乏类似的命名和发现机制。Agent-Reach 内置元数据注册中心，每个 Agent 启动时上报自己的名字、能力标签、通信地址，调用方只凭语义名称就能触达目标。
生命周期不可控：Agent 可能因为 LLM 调用超时、上下文溢出、进程被杀等各种原因失联。Agent-Reach 引入心跳检测和状态外部化，失联 Agent 会自动标记不可用，避免请求发到“尸体”上。
任务粘滞：传统回调式协作在 Agent 长任务场景下容易断链。Agent-Reach 把所有任务流转和回执都走消息信封包装，配合可追踪的任务 ID，挂掉的任务可以从断点恢复。

另外它还有一层更实际的设计目标：不要侵入业务代码。Agent 原有的工具调用逻辑、上下文管理逻辑都不用改，只要在外部套一层 SDK，把 send 和 receive 的语义接上就行。这也是我在项目里最满意的一点。

1.3 适合谁读

如果你正在做以下事情，这篇文章应该能帮上忙：

用 LangChain、AutoGen、CrewAI 这类框架搭多 Agent 应用，但发现它们只解决了编排，没解决运行时触达与治理；
在自研 Agent 平台，需要把散落的 Agent 服务统一管起来；
做 RPA 或工作流系统，想把每一步的“执行单元”抽象成可远程调度的 Agent——原理同样适用。

下面我会从架构设计、核心实现、生产踩坑和调优建议四个方向拆解 Agent-Reach，带着实操代码和真实的故障复盘，尽量让看完的人能上手复现一套最小可用版本。

2. 整体架构与关键设计

2.1 命名与寻址：给每个 Agent 一本“通讯录”

Agent-Reach 的寻址模型借鉴了域名系统，又不完全是域名系统。注册中心里保存的不是 IP + 端口，而是一组结构化的元数据：

字段	作用	示例
agent_name	全局唯一名称，用户可读	finance_analyzer_v3
capability_tags	能力标签数组，支持语义查找	["财报解析", "PDF", "rsi"]
transport_addr	可被路由的通信地址	grpc://10.20.1.8:9001
ttl	心跳租约有效期，单位秒	30
status	当前健康状态	healthy / suspect / offline
metadata	自定义键值，扩展字段	{"timeout": 120}

这样设计的好处是：调用方可以做能力路由。比如调度器收到任务“把这份季报的流动性指标提取出来”，先拿“流动性指标”去注册中心查有哪些 Agent 挂了这个标签，再按权重或负载选一台。数据库索引只对 capability_tags 做了 GIN 数组索引，查询效率还不错，几千个 Agent 实例下响应耗时在 2ms 以内。

2.2 消息信封与路由策略

Agent-Reach 的所有通信走一个统一信封，我简化一下核心字段：

type Envelope struct { MsgID string // 全局唯一的消息ID，链路追踪用 Sender string // 发送方 agent_name Recipient string // 目标 agent_name / capability tag TaskType string // 任务类型，如 "inference" / "tool_call" Payload []byte // 实际负载 TimeoutMs int // 期待响应的超时时间 RetryCount int // 已重试次数 IdempotencyKey string // 幂等键，防止任务重复执行 TraceID string // 调用链追踪ID }

路由策略这里我踩过坑，初始版本只有“精确匹配 agent_name”，结果 Agent 实例滚动重启后名字带上了版本号，调用方全部 404。后来改成三段式匹配：能力标签 > 别名 > 实例名。优先按能力找，找不到就看全局别名，最后才落到具体实例。这样 Agent 升级、迁移时调用方完全无感知。

路由组件本身是个轻量网关，不承担业务计算，只做四件事：查注册表、选目标、发消息、收回执。它基于 gRPC 流式传输，头部带 Envelope 元数据，负载单独走 byte payload，避免把二进制内容塞进 JSON 导致的序列化膨胀。

2.3 调度执行模型：把“找人干活”变成可追踪的流水线

单个 Agent 之间互相发消息只是最初级用法，真正复杂的是任务编排状态。一个任务可能要经过“数据预处理 Agent → 分析 Agent → 报表生成 Agent”三个节点，每一步都要有状态、有超时、有回退。

Agent-Reach 的调度模型很简单，就三张抽象：

任务(Task)：外部请求进来的完整业务单元，持有 TaskID 和 DAG 定义；
步骤(Step)：DAG 里的一个节点，对应一次 Agent 触达；
执行记录(ExecutionRecord)：每个步骤的运行快照，写事务日志。

流水线的状态不放在内存里，而是落到 PostgreSQL 的一张 task_events 表里。Agent 每完成一步，就追加一条事件。这样哪怕调度器宕机，重启后按 TaskID 拉事件流就能恢复现场。我把这个设计叫“事件溯源式编排”，它让 Agent-Reach 在多 Agent 场景下的可靠性上了一个台阶。

2.4 为什么不用“中心化管道”方案

我在设计早期想过更简单的方案：做一个中心 Agent，把任务发进来再转出去，类似消息队列。但很快放弃了。中心化管道有三个硬伤：

单点故障会让整个 Agent 网络停摆；
中心节点会成为 Prompt 上下文瓶颈——所有任务描述都挤在一个上下文窗口里；
无法横向扩展语义能力，新增 Agent 得改中心逻辑。

Agent-Reach 最终选择“去中心调度 + 集中元数据”的折中方案：调度是分散在调用侧的，每个 Agent 都内嵌轻量 client，自己决定找谁、什么时候发；只有注册表和事件日志是集中存储。这种架构更像服务网格的数据面/控制面分离，Agent 网络能动态伸缩，也不会被某个中心拖死。

3. 核心实现与落地实操

3.1 最小可用版本的技术栈

先交代一下我在 Agent-Reach 里使用的技术栈，给想复现的同学一个参考：

组件	选型	理由
注册中心	etcd	自带租约和 watch，天然适合心跳保活
消息传输	gRPC（双向流）	低延迟、支持流式回传、带原生健康检查
事件日志	PostgreSQL	事务性写入可靠，便于业务方后续做分析
Agent SDK	Go + Python 双版本	团队以这两门语言为主，SDK 只做封装
观测系统	OpenTelemetry + Prometheus	标准协议，统一 trace 和 metrics

这里多说一句为什么选择 etcd 而不是 Redis：心跳注册需要“租约过期自动清理”的语义，etcd 的 Lease 机制天然能做，Redis 要自己维护过期键和回调，分布式临时节点这块不如 etcd 省心。etcd watch 还能实时推送注册表变更，省掉轮询的延迟和开销。

3.2 注册与发现的实现细节（附代码）

SDK 里最重要的函数是 Serve()，它做了三件事：启动健康监测、注册元数据、阻塞等待消息。我贴一段简化版 Go 实现，可以跑通最小的 Agent 触达流程：

func Serve(agentName string, handle func(Envelope) Envelope) { // 1. 建立etcd连接，带租约 cli, _ := clientv3.New(clientv3.Config{Endpoints: []string{"127.0.0.1:2379"}}) leaseTTL := 30 leaseResp, _ := cli.Grant(context.TODO(), int64(leaseTTL)) // 2. 注册元数据（采用key = /agents/{name}，value = JSON元数据） meta, _ := json.Marshal(Registration{AgentName: agentName, Status: "healthy"}) cli.Put(context.TODO(), "/agents/"+agentName, string(meta), clientv3.WithLease(leaseResp.ID)) // 3. 启动心跳续约（子goroutine里自动续租） keepAliveCh, _ := cli.KeepAlive(context.TODO(), leaseResp.ID) go func() { for range keepAliveCh { // 续约成功，说明租约有效 } }() // 4. 监听本Agent的专用消息通道（简化成回调） listenForMessages(agentName, handle) }

这个注册流程的关键点是：租约 TTL 一定要和心跳频率匹配。我当时设了 TTL 30 秒、心跳 5 秒一次，因为网络抖动导致一次心跳超时后 30 秒内还能补上，不会误杀。如果 TTL 太短，JVM GC 停顿几秒就会 Agent 被判定离线。

3.3 Agent 生命周期管理与健康检查

Agent-Reach 的健康检查分两个维度：

被动健康度：注册中心的租约是否在有效期内。租约过期就自动把状态置为 suspect，连续错过 2 个租约周期置为 offline。
主动健康度：SDK 每隔 10 秒向 Agent 发 ping 请求，检查是否还活着，以及依赖的模型服务是否可用。这层检查比租约更细，能提前发现“进程还在、但模型超时严重”的状态。

主动健康检查的结果写进元数据里的 status 字段。调用方在选目标时会优先过滤掉非 healthy 节点。

这里有个容易被忽略的问题：Agent 处理长任务时，消息回调可能阻塞很久，健康检查也会排在消息处理后面，导致假性离线。我的解法是给健康检查单独分配缓冲通道，把 ping 请求从业务消息队列中隔离出来，有效避免了长任务导致的误判。

3.4 可靠投递与重试策略

消息重投是 Agent-Reach 里最需要小心设计的部分，整套逻辑的讲究比想象中多。无脑重试会把下游 Agent 打爆，完全不做重试又会让上游任务白白失败。

我采用两阶段重试策略：

第一层：同步超时重试（针对瞬时失败）：调用方设置 TimeoutMs，默认 30 秒。超时后最多重试 2 次，重试可路由到同 Agent 的不同实例。每次重试间隔用指数退避：500ms → 2s。这一层解决进程重启、连接闪断等问题。
第二层：异步补偿重试（针对长时间不可用）：同步重试全失败后，把任务标记为 PENDING_RETRY 写入补偿表，由后台 Worker 接管。Worker 按 1min / 5min / 30min 三个递进时间段重试，每个时段只试一次。超过最大次数后任务进入 FAILED 状态，并回调通知调度器做人工兜底。

幂等靠 IdempotencyKey 实现。收方 Agent 在消息入口加一层去重表，以 IdempotencyKey + Recipient 为唯一索引，相同键的结果直接复用，防止任务被重复执行。这一步看似简单，实际上能救回大量因为重试产生的账目重复计算问题。

消息回执的设计我认为是最出效果的一块。Agent 执行完成后，回执消息里不只放结果负载，还放了一个 result_ref，指向事件日志里对应的 ExecutionRecord，让对方可以直接查看 Agent 执行了多久、调用了哪些工具。这在排查“为什么给的结果不对”时特别好用。

4. 生产环境踩坑实录与排查技巧

4.1 故障一：连接池被打满，所有触达事件排长队

现象很典型：Agent 数量从 50 涨到 300 之后，系统里突然出现大量 deadline exceeded 报错。查 gRPC 监控，发现连接池排队时间超过了 5 秒，活跃连接数卡在池子上限附近波动。

排查过程沿三条线展开：先看注册中心 etcd 的 watch 推送频率，发现 Agent 频繁启停导致全量广播；再看 agent client 的 channel 复用率，发现每次触达都新建了一个 gRPC connection；最后看路由网关的转发逻辑，发现必须等上一个响应返回才继续读队列消息。

根因是客户端 gRPC 连接复用没做好。SDK 在每次消息到达时都创建一个新连接，大流量场景下连接数飙升。修复策略分两步：一是把 client 改为长连接 + 连接池，复用同一连接处理所有消息；二是把路由网关的同步转发改成异步转发，内部加一个待响应票据池。

修复后每组压测的 p99 延迟从 2800ms 降到了 420ms，效果肉眼可见。大家在自建触达层时，连接复用问题要提前考虑，这是最容易忽视的瓶颈。

4.2 故障二：Agent 突发消息风暴，背压堵死事件日志

某个数据采集任务上线后，把下游 Agent 的 QPS 拉高了十几倍。事件日志的 PostgreSQL 写入很快出现锁等待，紧接着事务日志堆积，整个 Agent-Reach 的控制面都卡了。

我的处理顺序是：

先给事件写入加限流器，对单 Task 的写事件速率限制在 200 条/秒，超过直接丢弃并合并为聚合事件。
给每类消息加背压信号：Agent 回调处理不过来时，向发送方返回一个 Busy 状态，发送方收到 Busy 就进入退避等待，而不是不断重发。
事件表按时间分区，旧分区自动归档。

这里有一个关于背压的关键认知：它不只是“发慢点”这么简单，而是要形成“反馈回路”。如果只是单方面限流上游，下游还是会有积压。Agent-Reach 的做法是在协议里自带 Busy 响应码，相当于让接收方反向拖住发送方，让整条链路按真实消费能力自动适配流量。

事件表分区的设计也需要注意。把 task_events 按日期分区，配合定时调度清理数据，能避免写放大。我见过有的项目不分区，上线三个月后单表数据到了几十亿行，任何查询都变成了慢查询，就很被动。

4.3 故障三：注册中心 watch 暴涨，内存被打到接近 OOM

业务高峰期，etcd 集群内存异常上涨，watch 数量从几千涨到几十万。细查之后发现和 Agent 的发现机制有关：SDK 每次调用发现逻辑时都新建一个 watcher，且没有关闭，导致 watcher 泄漏。

修复方式有两个关键点：

所有 Agent 进程内共享一个全局 watcher，对外按能力标签做本地分发；
加一层 watcher 生命周期管理，监听范围是 /agents 前缀而不是每个 Agent 单独 watch。

修复后 etcd watch 数量从十几万降到几百，集群内存恢复正常。这个问题也是典型的“SDK 设计缺陷导致的基础设施稳定性问题”，实现触达层时一定要设计好 watcher 的复用。另外提醒一句：注册中心本身的 watch 数量、吞吐量要纳入容量规划，不能只看存储容量。

4.4 故障四：Agent 明明在线，任务却始终无法触达

一次排查中，两个 Agent 在同一台宿主机上，注册中心里都是 healthy，但 A 发给 B 的消息一直超时。最初怀疑是网络问题，抓包后发现 SYN 包到了 B 的端口没有任何响应——B 的 agent process 确实活着，但监听端口变了。

原因是 B 在发布新版本时，监听地址和注册中心里登记的地址不一致：B 进程绑定的是宿主机内网 IP，注册中心里登记的却是服务发现接口返回的 pod IP。结果调用方按注册地址连接，自然连不上。

这个问题的启发非常大。地址登记必须走 Agent 启动时的运行时自省，而不是从外部配置中心推断。SDK 启动时要检查当前节点所有可用网卡，挑选真正能被对端访问的地址注册上去。当时教训深刻，有个地址不一致问题导致两个环境之间完全无法通信，花了好几个小时才定位到是网卡/IP 选择策略的错。

5. 实测效果与调优建议

5.1 压测指标与结论

我在本地环境对 Agent-Reach 做了最简压测：一个调度器，十个模拟 Agent，每个 Agent 的处理延迟约 50ms。压测结果：

指标	结果
峰值触达 QPS	2350 消息/秒
单消息路由延迟 p99	6.5ms
注册中心查询延迟 p99	2.1ms
同步重试成功率（乱序丢包模拟）	覆盖 96% 失败场景
异步补偿成功率（进程崩溃模拟）	覆盖剩余 3% 场景

路由网关的延迟主要消耗在 gRPC 反序列化和注册表本地缓存查询上，和网络往返差不多，不会成为 Agent 协作瓶颈。重试成功率的覆盖情况说明，网络乱序丢包可以靠同步重试解决，进程级故障必须靠异步补偿，两者缺一不可。

5.2 值得留意的调优项

我根据自己的实践给几个核心配置项的推荐值，各组件版本不同可以结合实际做微调，但这些原则应该通用：

注册租约 TTL：不要用默认 5 秒，太短容易误杀；也不要太长，会掩盖真实故障。推荐值是健康检查周期的 4 到 6 倍，配合心跳频率设置在 10 到 30 秒之间比较合适。
路由表本地缓存：建在 Agent 进程内，订阅注册表变更做增量更新。避免每次路由都查 etcd，性能上差异巨大。缓存失效时间我选了 5 秒，这样即使 etcd 挂掉，路由层还能继续工作一段时间。
消息超时配置：不要把超时设成固定值。按照具体 Agent 的历史 p95 处理时间 + 1.5 倍缓冲动态生成。这样自然消息快的 Agent 超时短，任务重的 Agent 超时自动放长，不会误伤。

5.3 Client SDK 的使用经验

SDK 用起来是最直接的反馈来源，有几个细节值得分享：

SDK 里内置了本地路由缓存和全局 watcher 共享，这俩优化让业务代码完全不需要关心性能问题。引入 SDK 后压测显示调用损耗可以控制在 3% 以下，整体体感很轻。
Python 版 SDK 用的是 asyncio + grpc.aio，核心处理逻辑和 Go 版对齐，但遇到阻塞调用（比如 requests）要包成 executor 跑，否则事件循环被卡住，健康检查会误报。
日志输出做了结构化 JSON 格式，所有消息头字段都会带 TraceID，排查问题时按 TraceID 拉全链路日志非常方便。这一点在 Agent 协作场景的价值比预想大很多。

6. 最后再分享几句个人的体会

我在做 Agent-Reach 之前，以为多 Agent 系统最大的难点是“如何让 Agent 聪明地规划”，做完之后我觉得真正难的是“如何让 Agent 像微服务一样靠谱地协作”。规划能力可以靠调 Prompt 快速改善，触达和可靠性不行——它需要的是类似基础设施的耐心打磨。

Agent-Reach 的多智能体触达实践

Agent 协作系统里排前三的痛点，Agent-Reach 都有对应的设计目标：

寻址难：微服务靠服务名 + 注册中心定位，Agent 却缺乏类似的命名和发现机制。Agent-Reach 内置元数据注册中心，每个 Agent 启动时上报自己的名字、能力标签、通信地址，调用方只凭语义名称就能触达目标。
生命周期不可控：Agent 可能因为 LLM 调用超时、上下文溢出、进程被杀等各种原因失联。Agent-Reach 引入心跳检测和状态外部化，失联 Agent 会自动标记不可用，避免请求发到“尸体”上。
任务粘滞：传统回调式协作在 Agent 长任务场景下容易断链。Agent-Reach 把所有任务流转和回执都走消息信封包装，配合可追踪的任务 ID，挂掉的任务可以从断点恢复。

如果你正在做以下事情，这篇文章应该能帮上忙：

用 LangChain、AutoGen、CrewAI 这类框架搭多 Agent 应用，但发现它们只解决了编排，没解决运行时触达与治理；
在自研 Agent 平台，需要把散落的 Agent 服务统一管起来；
做 RPA 或工作流系统，想把每一步的“执行单元”抽象成可远程调度的 Agent——原理同样适用。

1. 整体架构与关键设计

1.1 命名与寻址：给每个 Agent 一本“通讯录”

Agent-Reach 的寻址模型借鉴了域名系统，又不完全是域名系统。注册中心里保存的不是 IP + 端口，而是一组结构化的元数据：

字段	作用	示例
agent_name	全局唯一名称，用户可读	finance_analyzer_v3
capability_tags	能力标签数组，支持语义查找	["财报解析", "PDF", "rsi"]
transport_addr	可被路由的通信地址	grpc://10.20.1.8:9001
ttl	心跳租约有效期，单位秒	30
status	当前健康状态	healthy / suspect / offline
metadata	自定义键值，扩展字段	{"timeout": 120}

1.2 消息信封与路由策略

Agent-Reach 的所有通信走一个统一信封，我简化一下核心字段：

type Envelope struct { MsgID string // 全局唯一的消息ID，链路追踪用 Sender string // 发送方 agent_name Recipient string // 目标 agent_name / capability tag TaskType string // 任务类型，如 "inference" / "tool_call" Payload []byte // 实际负载 TimeoutMs int // 期待响应的超时时间 RetryCount int // 已重试次数 IdempotencyKey string // 幂等键，防止任务重复执行 TraceID string // 调用链追踪ID }

1.3 调度执行模型：把“找人干活”变成可追踪的流水线

Agent-Reach 的调度模型很简单，就三张抽象：

任务(Task)：外部请求进来的完整业务单元，持有 TaskID 和 DAG 定义；
步骤(Step)：DAG 里的一个节点，对应一次 Agent 触达；
执行记录(ExecutionRecord)：每个步骤的运行快照，写事务日志。

1.4 为什么不用“中心化管道”方案

我在设计早期想过更简单的方案：做一个中心 Agent，把任务发进来再转出去，类似消息队列。但很快放弃了。中心化管道有三个硬伤：

单点故障会让整个 Agent 网络停摆；
中心节点会成为 Prompt 上下文瓶颈——所有任务描述都挤在一个上下文窗口里；
无法横向扩展语义能力，新增 Agent 得改中心逻辑。

2. 核心实现与落地实操

2.1 最小可用版本的技术栈

先交代一下我在 Agent-Reach 里使用的技术栈，给想复现的同学一个参考：

组件	选型	理由
注册中心	etcd	自带租约和 watch，天然适合心跳保活
消息传输	gRPC（双向流）	低延迟、支持流式回传、带原生健康检查
事件日志	PostgreSQL	事务性写入可靠，便于业务方后续做分析
Agent SDK	Go + Python 双版本	团队以这两门语言为主，SDK 只做封装
观测系统	OpenTelemetry + Prometheus	标准协议，统一 trace 和 metrics

2.2 注册与发现的实现细节（附代码）

SDK 里最重要的函数是 Serve()，它做了三件事：启动健康监测、注册元数据、阻塞等待消息。我贴一段简化版 Go 实现，可以跑通最小的 Agent 触达流程：

func Serve(agentName string, handle func(Envelope) Envelope) { // 1. 建立etcd连接，带租约 cli, _ := clientv3.New(clientv3.Config{Endpoints: []string{"127.0.0.1:2379"}}) leaseTTL := 30 leaseResp, _ := cli.Grant(context.TODO(), int64(leaseTTL)) // 2. 注册元数据（采用key = /agents/{name}，value = JSON元数据） meta, _ := json.Marshal(Registration{AgentName: agentName, Status: "healthy"}) cli.Put(context.TODO(), "/agents/"+agentName, string(meta), clientv3.WithLease(leaseResp.ID)) // 3. 启动心跳续约（子goroutine里自动续租） keepAliveCh, _ := cli.KeepAlive(context.TODO(), leaseResp.ID) go func() { for range keepAliveCh { // 续约成功，说明租约有效 } }() // 4. 监听本Agent的专用消息通道（简化成回调） listenForMessages(agentName, handle) }

2.3 Agent 生命周期管理与健康检查

Agent-Reach 的健康检查分两个维度：

被动健康度：注册中心的租约是否在有效期内。租约过期就自动把状态置为 suspect，连续错过 2 个租约周期置为 offline。
主动健康度：SDK 每隔 10 秒向 Agent 发 ping 请求，检查是否还活着，以及依赖的模型服务是否可用。这层检查比租约更细，能提前发现“进程还在、但模型超时严重”的状态。

主动健康检查的结果写进元数据里的 status 字段。调用方在选目标时会优先过滤掉非 healthy 节点。

2.4 可靠投递与重试策略

消息重投是 Agent-Reach 里最需要小心设计的部分，整套逻辑的讲究比想象中多。无脑重试会把下游 Agent 打爆，完全不做重试又会让上游任务白白失败。

我采用两阶段重试策略：

第一层：同步超时重试（针对瞬时失败）：调用方设置 TimeoutMs，默认 30 秒。超时后最多重试 2 次，重试可路由到同 Agent 的不同实例。每次重试间隔用指数退避：500ms → 2s。这一层解决进程重启、连接闪断等问题。
第二层：异步补偿重试（针对长时间不可用）：同步重试全失败后，把任务标记为 PENDING_RETRY 写入补偿表，由后台 Worker 接管。Worker 按 1min / 5min / 30min 三个递进时间段重试，每个时段只试一次。超过最大次数后任务进入 FAILED 状态，并回调通知调度器做人工兜底。

2.5 可观测性：每条触达都能追溯到执行现场

Agent-Reach 在注册和消息协议里塞了 TraceID，就是为了把可观测性做扎实。推荐的做法是这样的：

日志：SDK 统一输出结构化 JSON 日志，字段包含 trace_id、agent_name、event_type、duration_ms。采集走 Filebeat + ES。
指标：每个 Agent 暴露 Prometheus metrics，比如任务处理时长直方图、消息接收速率、重试次数计数、注册状态变化次数。
链路追踪：SDK 自动创建 OpenTelemetry span，跨 Agent 传消息时会把 TraceID 注入对端 span，整条任务链路在 Jaeger 里呈现为一条完整的调用链。

实际排查场景里，我基本不用再 SSH 上服务器看日志，通常是直接打开 Jaeger 搜 TraceID，几分钟定位到是哪个 Agent 卡在了哪一步。这也是 Agent-Reach 项目的稳定性底气来源。

3. 生产环境踩坑实录与排查技巧

3.1 故障一：连接池被打满，所有触达事件排长队

现象很典型：Agent 数量从 50 涨到 300 之后，系统里突然出现大量 deadline exceeded 报错。查 gRPC 监控，发现连接池排队时间超过了 5 秒，活跃连接数卡在池子上限附近徘徊。