1. 整体设计思路拆解Agent 为什么需要一套触达机制先说结论Agent-Reach 解决的是智能体在真实网络环境中找得到、进得去、读得懂的问题。很多人做 Agent 应用时把精力全放在模型选型和提示词调优上结果模型再聪明如果拿不到完整、及时、结构化的外部数据整个链路就跑不起来。我最早做信息聚合类 Agent 时第一版只接了两三个固定 API主流程看起来没问题一旦换一个数据源、换一批目标站点就发现模型虽然有工具调用能力但不知道该去哪些地方找、怎么安排访问顺序、怎么从乱七八糟的页面里抽出有效字段这就是典型的触达能力缺失。Agent-Reach 这个项目本质上就是给 Agent 加一层网络触达层。它把任务从帮我整理某领域的最新资料拆解成三个可执行的问题目标从哪来、用什么顺序访问、拿到之后怎么结构化。你可以把它理解成给 Agent 配了一副地图 交通系统 翻译官。地图负责生成目标清单交通系统负责高效、合规地把每个目标访问一遍翻译官负责把 HTML、JSON、PDF 这些不同格式的内容统一成 Agent 可以直接使用的结构化文本。这套思路适合什么场景首先是做行业情报聚合、竞品动态跟踪、舆情监测这类需要持续采集外部信息的应用其次是做垂直搜索、知识库构建、RAG 数据预处理再就是给企业内部知识管理工具做增量数据同步。不管是个人开发者还是小团队只要你的 Agent 需要主动去外部取数Agent-Reach 的这套设计都能直接拿来用。我在设计这套机制时给自己定了四个原则一是所有目标来源可配置不同业务换数据源时不用改主代码二是访问节奏必须可控不能因为 Agent 的并发调度把目标站点拖垮三是内容解析要有兜底格式变了不能直接崩四是整个触达过程可观测哪个目标失败、为什么失败一眼能定位。这四点贯穿了后续所有的模块划分和代码组织。2. 核心模块与关键技术点2.1 目标生成从人工维护清单到种子自动扩展Agent 触达的第一个环节是去哪里。最常见的做法是人工维护一份静态 URL 清单但实践下来这种清单有三个问题更新不及时、覆盖面窄、缺少上下文。比如你维护了一个行业新闻站的列表目标站改版换路径后你的清单就失效了而真正有价值的信源往往不是靠人工罗列出来的而是从已有关注内容里长出来的。Agent-Reach 在目标生成上做了两级设计。第一级是种子源配置也就是把人工整理的基础清单做成结构化配置每一项带名称、入口地址、抓取路径、更新频率、失效兜底页面第二级是自动扩展也就是让 Agent 从已抓取的内容里提取新线索。举例来说某篇资料里引用了另一个行业站点的链接或者某个讨论帖里提到了一个未收录的数据源这些线索会进入候选池经过打分确认后自动补充进目标列表。这个设计背后的逻辑是真实网络环境里的信息分布是稀疏但互联的人工清单覆盖的是你知道的节点而自动扩展覆盖的是节点之间的连接关系。我在初期版本里只做了种子源配置后来发现覆盖率总是差一截加上自动扩展后一个行业资讯类的 Agent 从 40 个种子源扩展到了 300 多个有效目标其中的新增来源绝大多数是靠内容间引用关系发现的。实际操作中目标生成模块会维护一张候选表字段包括来源地址、发现途径、关联种子、打分权重、状态。打分规则可以很简单被多个独立页面引用加分域名信誉库命中加分带明显低质特征的减分。不需要上特别复杂的算法线性加权就能跑出不错的效果关键是让这个打分过程可解释方便后续人工复核。2.2 访问调度并发、频率与优先级的三方博弈目标清单有了接下来就是怎么访问。这里最容易出问题的是只顾着并发高忘了频率限制和所有目标一视同仁没有优先级。真实环境里的目标站点对访问频率的容忍度差异极大有的是 API 接口明确给了 QPS 限制有的虽然没写但访问过快会直接拒绝服务更麻烦的是某些站点的限制逻辑并不透明需要靠实际反馈动态调整。Agent-Reach 的调度模块把访问控制拆成三层。第一层是全局令牌桶控制整体请求速率默认配置我会让每秒的请求上限根据目标站点数量估算宁可低一些也不触发风控第二层是单站点 QPS 策略每个站点独立配置比如某个数据 API 允许每秒 5 次那就给它单独建一个限速器不和其他站点抢额度第三层是动态退避一旦收到限流响应或者连接异常自动对该站点执行退避策略指数退避从 1 秒开始连续失败三次后暂停该目标十分钟。优先级这块Agent-Reach 采用业务优先级 时间敏感度双因子排序。业务优先级由任务上下文决定比如某个目标是用户显式提到的那就标记为高优先级时间敏感度则由内容本身决定比如最新公告今日快讯这类页面的过期速度远快于说明文档需要优先保证抓取及时性。调度队列实时按这两个因子算出综合权重高权重的目标先执行低权重的排队避免一出现新任务就把整个队列打乱。这里有一个我从实战里总结的细节不要把调度器做得太聪明。很多时候固执地加上各种动态负载均衡策略反而会在目标站点反馈异常时把问题复杂化。Agent-Reach 的做法是让策略保持简单每轮从队列里取固定数量的高权重目标每个目标按自己的频率限制去执行执行完回来更新状态仅此而已。简单策略的优点是容易排查也容易向非技术同事解释。2.3 内容解析干净文本、结构化字段与失败兜底访问完成之后内容解析的质量直接决定下游 Agent 的表现。我见过不少项目抓取回来的页面源码直接塞给模型结果模型被大量导航、广告、脚本代码干扰回答质量明显下降还增加了 Token 消耗。Agent-Reach 解析层的目标是把网页内容还原成一篇干净的主文本再按业务需要抽成结构化字段。解析流程分三步。第一步是主内容抽取用内容提取规则把正文区域从 HTML 中剥离出来这一步主要处理的是怎么去噪。第二步是字段映射按配置的结构化模板抽取标题、发布时间、作者、正文、标签等字段这里我建议先做规则抽取XPath 或 CSS 选择器规则没命中的再交给模型做兜底抽取而不是一上来就全部靠模型成本和延迟都吃不消。第三步是格式归一化把发布时间统一成 ISO 格式、数字单位统一、去掉多余空白字符保证下游存进数据库的数据是整齐的。失败兜底是解析层里最容易被忽视的部分。站点改版、字段换位置、动态渲染导致内容为空这些情况在实际运行中非常常见。我的做法是给每个解析任务配降级链首选规则 A失败后尝试规则 B再失败就整页转文本交给 LLM 做信息抽取仍然失败就把原始页面截图或源码存进失败队列等人工检查。这条降级链保证了即使站点临时变动Agent 主流程也不会中断只是个别目标的质量降级不至于全军覆没。3. 实操过程从零搭建一个 Agent-Reach 实例3.1 环境准备与依赖选择我建议把 Agent-Reach 做成一个独立的 Python 服务用 FastAPI 暴露控制接口用 PostgreSQL 存任务状态和内容结果用 Redis 做队列和限流计数。这套组合的好处是生态成熟、排查方便而且 Redis 的原子计数非常适合做频率限制。依赖方面核心就三个库# requests 改成 httpx异步并发方便 import httpx # 解析用 parsel基于 scrapy 的选择器简单够用 from parsel import Selector # 调度用 asyncio配合自带队列 import asyncio用 httpx 而不是 requests 的原因很简单Agent-Reach 的触达过程天然是并发密集型的异步 IO 能大幅压满吞吐。用 parsel 是因为它轻量如果你已经在用 Scrapy 生态那直接用 parsel 可以复用一套选择器语法而且它本身不依赖 Twisted不拖累纯 asyncio 服务。3.2 核心调度代码的骨架下面这段代码是我实际项目里的简化版核心思路是生产者把目标 URL 塞进队列多个 worker 并发消费每个 worker 内部遵循站点级限速import asyncio from collections import defaultdict from datetime import datetime, timedelta class ReachScheduler: def __init__(self, concurrency8): self.queue asyncio.Queue() self.semaphore asyncio.Semaphore(concurrency) self.domain_hits defaultdict(list) # 记录每个域名的访问时间点 self.max_hits_per_domain {} # 每个域名的 QPS 限制 def set_domain_limit(self, domain: str, qps: float): 为单个域名配置独立的访问频率限制 self.max_hits_per_domain[domain] qps def _check_domain_available(self, domain: str) - bool: limit self.max_hits_per_domain.get(domain, 5) now datetime.now() # 只保留最近 10 秒的访问记录 self.domain_hits[domain] [ t for t in self.domain_hits[domain] if now - t timedelta(seconds10) ] return len(self.domain_hits[domain]) limit * 10 async def fetch_one(self, url: str): domain url.split(/)[2] # 不满足频率限制时等待 0.5 秒后再检查 while not self._check_domain_available(domain): await asyncio.sleep(0.5) self.domain_hits[domain].append(datetime.now()) async with self.semaphore: async with httpx.AsyncClient(timeout15, follow_redirectsTrue) as client: resp await client.get(url, headers{User-Agent: self.ua}) return resp.text这里有几个细节值得展开。第一个是domain_hits这种时间点列表的写法不依赖额外的 Redis 数据结构单机部署时简单直接如果部署多个实例再把这段替换成 Redis 的滑动窗口计数。第二个是semaphore控制全局并发避免整个进程的并发数过高把内存打满。第三个是httpx.AsyncClient建议在每个 worker 里复用连接池不要每次请求都重新创建对目标站点和本机资源都更友好。3.3 运行监控与数据落库调度只是前半程数据落库和失败追踪才是保证系统可用的后半程。Agent-Reach 在每次抓取任务结束后会往 PostgreSQL 写入一条完整的任务记录字段大概是字段类型说明task_iduuid任务唯一 IDtarget_urltext目标地址statusenumsuccess / failed / skipped / manual_feedbackhttp_codeint请求响应码latency_msint总耗时fail_reasontext失败原因如 timeout、blocked、parse_errorwait_durationint因为频率限制等待的时间created_attimestamptz触发时间这张表是排查问题的第一入口。我每天第一件事就是看fail_reason分布如果某类失败突然增多往往不是代码问题而是某个目标站点改版了。配合一个简单的统计 SQL就能快速定位是哪些域名的失败率在上升SELECT split_part(target_url, /, 3) AS domain, status, count(*) AS cnt FROM reach_task_log WHERE created_at now() - interval 6 hours GROUP BY domain, status ORDER BY cnt DESC;落库之后内容数据还要做去重。同一页面在不同时间抓到的内容可能略有差异不能单纯靠 URL 唯一约束。我用的策略是存两份字段一份是content_hash对主内容做 SHA256一份是similar_hash对内容去掉空白字符后取前 500 个字符再做一次哈希。写入前先检查这两个哈希如果完全相同直接丢弃如果相似则更新已有记录的抓取时间只有差异足够大才新增一条版本记录。这样既避免了重复存储又能保留内容演变的轨迹。3.4 如何让 Agent 主流程与 Reach 层解耦Agent-Reach 的定位是触达层不是决策层所以它不应该依赖具体某个模型的调用逻辑。我在设计时让它们通过消息队列解耦Agent 需要外部信息时向 Reach 服务发一个任务请求Reach 完成后把结果写回结果表Agent 通过轮询或事件通知拿到结果继续自己的推理流程。举个例子。假设你有一个行业日报 Agent它每天的任务是整理指定领域的动态。主流程会先检查本地数据库中最近 12 小时的增量数据够不够不够就向 Reach 服务发起补充抓取请求然后进入等待状态。Reach 服务把目标清单跑完之后调用一个事件回调通知 AgentAgent 再进入汇总环节。这样做的最大好处是换模型、换业务逻辑都不会影响触达层反之触达层调整访问策略也不会影响 Agent 的业务判断。这个解耦思路虽然简单但在真实项目里往往容易被忽略。很多人直接把抓取逻辑写在 Agent 的 main 函数里一旦并发出问题整个 Agent 就卡死了。把触达能力剥离成独立服务后故障隔离、水平扩展、单独运维全都变得顺理成章。4. 常见问题与排查技巧实录4.1 高频故障速查表在实际运行 Agent-Reach 的几个月里我遇到过的典型问题基本可以归成几类。下面这张表是我整理的高频故障速查表每一条背后都有真实的踩坑经历。现象可能原因排查方法解决建议所有请求都超时全局并发过高本机连接数被打满看latency_ms和本机网络连接数降低concurrency给每个 worker 增加连接复用单个站点频繁限流没有按域名拆分限速看fail_reasonblocked的占比用set_domain_limit单独配置调低 QPS内容解析为空但页面正常打开目标站是动态渲染直接请求源码没有正文保存原始 HTML 检查是否含渲染后的字段接入无头浏览器兜底或改用该站提供的 API同一条内容反复入库只对 URL 做了去重没做正文指纹去重查content_hash是否有大量重复启用正文哈希和相似哈希双层去重任务积压、队列越来越长解析耗时占比过高worker 被 IO 阻塞看任务日志里解析步骤的耗时占比把前期规则解析和后续模型兜底分离异步化处理某些目标永远抓不到最新内容目标配置的更新轮询周期太长查种子源配置里的update_interval对高敏内容单独缩短间隔不要全局套同一个节奏4.2 三个最容易踩的坑第一个坑是把 UA 和请求头做成全局统一。实际跑一段时间你就会发现不同站点的风控策略差别很大有些站点对相同 UA 的频繁访问非常敏感有些则对无 Cookie 的请求直接拒绝。我的做法是把请求头做成分组配置比如搜索引擎抓取组API 客户端组浏览器模拟组不同目标走不同分组而不是全用一个。第二个坑是重试逻辑写得太激进。刚开始我把超时重试设为 3 次超时时间 10 秒结果某个目标站点临时抖动时整个队列被重试请求占满正常目标反而排不进去。后来改成只有明确是网络层错误连接重置、DNS 解析失败才重试收到 HTTP 4xx 不重试收到 429 或 503 走退避逻辑并且重试请求最多只占全局并发额度的 20%保证正常任务不被拖累。第三个坑是正文解析成功不代表字段质量过关。我见过解析结果里标题、正文都挺完整但发布时间解析出来是空值的情况原因是页面里用了相对时间3 hours ago而不是标准日期。这类问题用规则很难穷尽最好在解析层加一个字段完整性检查如果必填字段缺失率超过阈值就把该任务标记为manual_feedback进入人工审核队列而不是默默当作成功处理。4.3 从日志快速定位问题的技巧Agent-Reach 的日志设计遵循一个原则每个环节的时间都要可测量。我在日志里固定记录四个时间点入队时间、请求开始时间、请求结束时间、解析结束时间。四个时间点一算就知道耗时到底花在哪一层。排查问题时我最常用的分析方式是分组看耗时中位数。有一次任务整体变慢我按域名分组看请求时间和解析时间发现某个域名的解析耗时中位数是其他站点的 6 倍一查才发现它改版后正文区域变成了图片为主解析模块在反复尝试无文本节点。如果不是按域名拆分统计只在全局层面看平均耗时这个问题很容易被平均值掩盖。另一个比较实用的技巧是给每个任务打 trace_id。这个 id 从任务生成一直带到日志、结果表、回调事件。你不需要复杂的链路追踪系统只要在所有日志行里输出这个 id出问题时grep trace_idxxx就能把整个链路串起来。对于一个小型至中型的触达服务来说这比引入一堆 APM 工具更直接有效。5. 合规与稳定性建设不要等出问题再补救触达层跑在公网上合规和稳定性这两件事不能靠事后补救。先说合规Agent-Reach 的访问频率控制不只是为了技术上不触发限流更是为了不给目标站点造成不必要的压力。我在全局策略里默认加了两个约束一是严格遵守目标站点 robots 声明二是对同一站点设置访问间隔下限绝不在短时间内反复请求同一路径。这些都是合理使用网络资源的基本要求做触达类应用的第一原则是不打扰。稳定性方面我建议重点建设三个阶段的能力。事前阶段也就是配置阶段通过种子源的健康检查提前发现已经失效的域名避免把请求发到确定失败的地址上。事中阶段就是前文反复提到的限速、退避、降级链。事后阶段则是把失败任务做分类统计形成周报让问题趋势一目了然。三个阶段缺一不可只有事后统计没有事中保护等到发现问题时目标站点可能已经被打扰了好几次。还有一个很容易被忽略的点是存储容量规划。很多人觉得抓取内容存数据库就行了但实际跑起来每天的增量数据量很容易超出预期。文本内容本身不大但版本记录、日志表、失败快照加在一起膨胀速度非常快。我的做法是日志表按天分表超过 30 天的数据自动归档内容结果表保留最近 3 个版本更早的版本归档到冷存储。这样即使数据量翻倍主查询性能也不会明显退化。6. Agent 触达层的下一步演进Agent-Reach 目前的形态是一个半主动的触达服务它按配置好的目标和调度策略执行不具备自己规划任务的能力。我对它的下一步演进方向是让这一层具备有限的自主性——在给定约束条件下Agent 能够根据实时反馈调整抓取计划而不是死守着初始配置。一个比较务实的做法是引入目标质量反馈回路。当前任务的解析结果出来之后让下游 Agent 对内容质量做一个轻量打分比如信息密度如何、是否重复、是否命中业务需求。这些打分数据回流到目标管理模块用来调整种子源的权重持续打高分的源加权持续打低分的源降权达到一定阈值后自动暂停。这样就形成一个闭环Agent 触达得越多它就越清楚哪些源值得触达系统性覆盖率会随着运行时间不断提高。另外多模态内容的触达也需要逐步纳入。现在的 Agent-Reach 主要处理文本内容但很多有价值的信息以图片、表格、音视频形式存在。下一步的解析层计划加入 OCR 和语音识别前置处理把非文本内容先转成文本再进入原有的解析链路。这个方向的技术已经很成熟难点在于成本控制和异步编排但作为触达层的扩展价值是明确的。我在落地 Agent-Reach 这套设计时的体会是不要让智能成为借口先把数据触达这件基础工程做实。Agent 的能力上限很大程度上取决于它能稳定、合规、高效地触达多少有效信息。把这个底盘打牢上层做多少花活都不虚。