不用绕弯子直接聊正题。这个标题里藏着一件我琢磨了很久的事互联网从诞生那天起就是给“人”用的浏览器、按钮、表单、验证码全都是以人类的手指和眼睛为尺度设计的。但这两年AI Agent 开始大规模涌入线上它们不用鼠标不看界面靠的是 API 和结构化数据。结果就出现了一个很尴尬的断层Agent 想办的事人类的应用接不住人类用得顺手的应用Agent 用起来又隔了一层。我开源了一个叫 ANX 的协议全称是 Agent Network eXchange核心目标就一句话让应用原生地同时服务人类用户和 Agent 用户从架构上就把“人机共用”这件事做进基因里。这篇文章把我从需求拆解、协议设计、落地实现到踩坑排查的全过程都写出来适合正在做 Agent 基础设施、或者想让自己产品“被 Agent 用起来”的开发者参考。1. 为什么说 Agent 是下一代核心用户很多人对 Agent 的想象还停留在“聊天机器人”“智能助手”这类概念上但实际上Agent 正在从“对话界面”走向“自主行动”。它会自己去查资料、比价、订票、提交表单、调用工具甚至跟其他 Agent 协作完成一个复杂的任务链条。这时候 Agent 的身份已经变了它不再是一个帮你操作电脑的工具它本身就是互联网上的一名“用户”。1.1 互联网的用户结构正在发生根本变化我举个例子你马上就懂。过去十年网站的流量分析看的是 UV、PV、停留时长、跳出率这些指标背后都有一个隐含假设每一个访问者都是一个真实的人。但现在你再去看很多头部平台的日志你会发现非人类流量爬虫、脚本、AI Agent占比已经高到惊人。这些非人类流量里面有一部分是恶意的但越来越多的部分是“正经办事”的自动比价、自动监控库存、自动汇总信息、自动下单。我在自己的服务器日志里做过一次统计某段时间内一个普通的信息聚合类接口Agent 调用占比超过 60%。这不是未来这就是现在。而问题在于绝大多数应用根本没有为这种“新用户”做好准备。1.2 现有方案为什么撑不住现在让 Agent 使用互联网服务主流做法有三条路但每条路都有明显短板。第一条路是“爬虫路线”。Agent 模拟浏览器请求、解析 HTML、抽取信息。这条路的问题在于前端页面重构一次爬虫就得跟着改一次遇到登录态、验证码、行为风控Agent 直接废掉。而且爬虫对服务器资源的消耗极大动不动就被封 IP。第二条路是“开放 API 路线”。服务方单独维护一套面向机器的接口比如 JSON API、GraphQL、Webhook。这条路对 Agent 很友好但它有一个致命伤它把人类用户和机器用户彻底割裂了。维护两套入口意味着双倍的开发成本、双倍的安全风险和双倍的体验一致性难题。很多小团队根本没有这个精力。第三条路是“浏览器自动化路线”。让 Agent 真的打开一个浏览器像人一样点击、输入、滚动。这个方案看着很美实际上是最脆弱的前端一个按钮的位置变了自动化脚本就崩了加载慢一点时序就乱了弹个广告流程就断了。而且这种方案的效率极低一个简单操作要消耗大量的计算资源去渲染页面、识别元素。1.3 我们需要的是“原生共存”而非“模拟人类”这三条路的本质问题是一样的它们都在用某种方式“绕过”应用本来的设计而不是让应用从一开始就理解“我同时服务人类和 Agent”这件事。所以我在设计 ANX 协议时定了一个基调不做爬虫、不做二次封装、不做浏览器模拟而是从应用层协议入手让应用自己具备“向 Agent 开放”的能力。这就好比一个实体店铺过去只接待走进来的顾客现在门口多了一个服务窗口窗口后面有标准化的单据格式Agent 来了不用推门直接递单子就能办事。人类顾客还是走大门体验完全不受影响。这才是“人机共用”的正解不是让 Agent 去适应人类世界的混沌而是让应用的入口层具备双重接待能力。2. ANX 协议的整体设计思路协议设计这件事最怕一上来就写格式、定字段那样做出来的东西只能是自嗨。我先是把需求分了三层Agent 怎么找到应用、Agent 怎么调用应用、Agent 怎么安全地使用应用。每一层对应一组清晰的协议设计目标然后再逐层落实现。2.1 三个层级的设计拆解第一层是“发现层”。人找应用靠应用商店、搜索引擎、朋友推荐那 Agent 怎么知道一个应用提供什么能力ANX 方案是让应用暴露一份结构化能力清单我们叫 Capability Manifest相当于给 Agent 看的一份“服务菜单”。Agent 拿到这份菜单就知道这个应用能干什么、需要什么参数、返回什么格式不需要人肉去读文档。第二层是“调用层”。能力清单只是“菜谱”真正的“上菜”环节需要一个标准的请求-响应机制。ANX 采用消息信封格式所有请求都包裹在一个统一的信封里信封上有版本、会话标识、请求 ID、认证信息、超时策略等元数据而信封里的业务载荷则交给应用自己定义。这有点像 HTTP 协议状态行和头是协议的消息体随你的业务爱怎么填怎么填。第三层是“治理层”。Agent 不是人它没有道德感也常常缺乏边界意识。如果放任 Agent 随意调用你会遇到失控的循环调用、无限重试、资源耗尽、权限滥用等问题。所以 ANX 在协议层面内置了能力边界、频控策略、权限令牌和审计追踪。这些不是应用层自己实现的闭包而是协议层面定义的标准语义。2.2 协议设计的关键取舍设计过程中有几个关键的取舍我认为值得展开说说因为它们直接决定了协议的可用性。第一个取舍是“通用还是专精”。市面上已经有很多针对 Agent 的协议或框架但它们大多绑定到特定的 Agent 运行时或者特定的应用框架上。ANX 的定位是做一个不依赖任何 Agent 框架的“最小公约数”它只定义消息的封装、能力的描述和权限的流转具体怎么执行交给应用自己。这就保证了任何语言、任何框架写的应用只要实现了 ANX 协议层就能接入 Agent 生态。第二个取舍是“让 Agent 学新东西还是迁就 Agent 的现状”。当前各大 Agent 框架都支持通过 MCP、Function Calling 之类的机制调用外部工具。ANX 在设计上刻意保持和这类机制的良好兼容性Agent 端只需要把 ANX 视为另一个“工具仓库”按各自框架的规范包装调用即可不需要理解 ANX 内部的消息结构。这样既保住了协议的表达能力又不给 Agent 开发增加额外负担。第三个取舍是“安全前置还是事后补救”。很多系统是先让人用起来遇到安全问题再堵窟窿但 Agent 的调用速度和并发能力是人的成百上千倍一旦出问题就是灾难性的。所以 ANX 把安全语义直接烙进协议定义里比如所有 Agent 调用必须携带签名令牌、所有高权限操作必须二次确认、所有变更类操作必须存在幂等键。这些在协议层面就是强制的不是可选项。2.3 与其他方案的边界划分有人可能会问有了现成的 HTTP、GraphQL、gRPC为什么还要一个 ANX我的回答是HTTP 这些都是传输层和接口层的协议它们不关心“调用方是人还是 Agent”。ANX 站在更高的位置它定义的是“双用户模型”下的应用行为规范同一个请求进来系统如何识别调用方身份如何分配不同的速率策略如何呈现人类可读的界面或 Agent 可读的结构化响应。换句话说ANX 不是替代 HTTP而是跑在 HTTP 之上的一层语义规范。你可以把 ANX 想象成一套“国际货物运输公约”HTTP、WebSocket、gRPC 这些都是不同的运输工具ANX 规定的是货物如何打包、谁有权运输、到了之后怎么交接。运输工具还是那些但整个流程变得可预期、可追溯。3. 协议核心机制与实操要点框架聊完了落到具体实现。ANX 的核心机制可以拆成四块能力清单、消息信封、认证授权、频控与审计。每一块都不复杂但在细节上有很多坑我一个个说。3.1 Capability Manifest给 Agent 看的服务菜单Capability Manifest 是 ANX 协议最外层的组成部分说白了就是一份 JSON 文件描述应用对外开放的能力。我设计它的第一原则是“人可以轻松读懂机器可以精确解析”所以它不允许出现自由文本描述每个能力必须有明确的输入 schema 和输出 schema。一个简单的 Manifest 长这样{ anx: { version: 1.0, manifest_id: shop-001, service: { name: 虚拟商店订单服务, description: 提供商品查询与订单创建能力 }, capabilities: [ { name: query_product, description: 按商品ID查询在售商品信息, input_schema: { type: object, properties: { product_id: { type: string, pattern: ^P\\d{6}$ } }, required: [product_id] }, output_schema: { type: object, properties: { product: { type: object } }, required: [product] }, auth_required: true, rate_limits: { per_minute: 60 } } ] } }这份 Manifest 做到几件事告诉 Agent 这个服务叫什么、能干什么告诉 Agent 每个能力需要什么参数、参数格式是什么、返回什么告诉 Agent 这个能力需要什么等级的认证、调用频率上限是多少。实操中我强烈建议你给每个能力的输入输出都定义严格 schema不要偷懒写自由格式。原因是 Agent 的推理模型对自由格式的理解极不稳定你今天写一句“productId 是商品编号自己看文档”明天 Agent 就可能在参数里传一个商品名称过来。只有把类型、正则、枚举值、默认值都写死Agent 才能稳定地生成正确参数。3.2 消息信封统一的人机请求入口ANX 协议定义的请求消息使用统一的 JSON 信封结构。无论是人类用户在前端点按钮发起的请求还是 Agent 通过协议层发起的调用都必须走同一个入口。信封格式如下{ anx_version: 1.0, message_id: req_9f2a7c1d, session_id: sess_3b8e5d2f, caller: { type: agent, agent_id: agent-vehicle-v3, identity: { token: eyJhbGciOi... } }, capability: query_product, params: { product_id: P120938 }, idempotency_key: idem_20240121_093847, timeout_ms: 30000 }这个信封里的每个字段都不是摆设我逐个说我的设计动机。message_id 是这条消息的唯一标识用于分布式追踪以及在排查问题时把人类用户和 Agent 的请求关联到同一个追踪链路。session_id 表示会话上下文帮助服务端判断这是新会话还是已有会话的延续Agent 的会话生命周期和人类的 Session 生命周期在业务上往往差异很大这个字段为此提供了区分基础。caller 字段是 ANX 最核心的差异点它明确标识调用方是人还是 Agent。人类调用时 type 为 humanAgent 调用时 type 为 agent 并携带 agent_id。服务端拿到这个字段之后可以走完全不同的业务策略分支。idempotency_key 是为 Agent 场景专门加的Agent 在超时后重试是家常便饭如果没有幂等键一次订单就可能被重复创建。timeout_ms 让调用方明确声明自己愿意等多久防止双向死锁。3.3 认证授权让 Agent 拥有自己的身份这是整个协议里最容易被低估的部分。传统应用的认证体系默认的“用户”是人类密码、验证码、人脸识别没有一个适合 Agent。ANX 的认证设计思路是给 Agent 发独立的身份凭证而不是借用开发者的个人账号。我推荐的做法是双轨认证。人类用户走原有的账号密码或者第三方登录Agent 用户走 API Key 或 JWT 令牌。每个 Agent 令牌可以绑定一组能力权限比如“只能查商品、不能下单”“只读、不可写”甚至可以绑定每日预算上限。实现上令牌签发的逻辑要单独抽出来做成一个服务模块不要跟人类用户的认证逻辑混在一起。因为两者的生命周期完全不同人类账号可能十年不变Agent 令牌可能因为安全策略频繁轮换。权限控制还有个细节需要注意Agent 的权限要支持“数据集隔离”。同一套查询能力不同的 Agent 应该看到不同的数据范围。比如内部渠道 Agent 能看到含成本价格的商品数据而外部比价 Agent 只能看到不含利润信息的公开数据。这个隔离逻辑建议放在业务层之上用类似策略引擎的方式统一处理。3.4 访问控制与审计防止 Agent 失控的“安全带”Agent 失控有两种典型形态我都遇到过。一种是死循环重试Agent 调用超时后把同样的请求以每秒一次的频率重试半小时直接把数据库连接池打爆。另一种是权限漂移Agent 在对话过程中不断索要权限开发者手一抖给了个管理权限然后一路执行到深夜。ANX 的访问控制从两个方向堵住这些问题。第一个方向是协议层强制幂等和重试退避。每个调用必须携带 idempotency_key服务端缓存最近 N 个幂等键对应结果重试次数超过限制后服务端主动返回“429 请停止重试”而不是继续执行。第二个方向是权限逐级递进Agent 默认只有最小权限要想执行高权限操作必须进入“授权确认流程”而且这个确认可以由更高权限的管理 Agent 或人类完成。审计这件事更适合用一张表来看。我给自己项目定义的审计字段如下审计字段含义为什么必须记录message_id请求唯一标识排查问题需要关联上下文caller_typehuman/agent区分用户类型的核心维度agent_id调用方 Agent 标识定位失控 Agentcapability调用的能力名统计各能力使用频率params_digest参数摘要追溯业务数据变化result_code结果状态监控失败率与错误码cost_estimate预估消耗成本管控的基础数据这套审计不仅仅是事后查账用的在运行期我会跑一些简单的异常检测规则比如“同一个 agent_id 在 5 分钟内调用失败超过 50 次”命中后自动将对应令牌踢出活跃认证列表。4. 构建一个真正的人机共用 App协议设计得再好最终还是要落到一个能跑的 App 上。这一节我以一个“商品订单服务”为例完整走一遍搭建流程包含路由设计、Agent 接入层和前端共存方案。这个示例我已经在一套模拟项目 X 里完整跑通过这里给出的都是可直接参考的代码和配置。4.1 路由层一条路径双头接待人机共用的核心在于入口层不做分流而是做“识别 策略路由”。同一个 URL请求进来后先识别调用方类型再决定走哪套处理逻辑。from flask import Flask, request, jsonify from anx import ANXEnvelope, CapabilityRegistry, AgentAuth app Flask(__name__) registry CapabilityRegistry(./manifest.json) app.route(/anx/dispatch, methods[POST]) def dispatch(): envelope ANXEnvelope.from_request(request) # 识别调用方 if envelope.caller.type agent: auth AgentAuth.verify_agent_token(envelope.caller.identity.token) if not auth.is_valid(): return jsonify({error: invalid_agent_token}), 401 # Agent 走协议处理链路 return handle_agent_call(envelope, auth) # 人类用户走现有业务逻辑 if request.is_json: return handle_human_api(request) return handle_human_page(request)这段代码展示了关键的设计取舍入口不做分流只做识别。一旦完成识别人类和 Agent 走的处理链路由不同的 Handler 负责但底层的业务逻辑查库存、创建订单、更新状态是共享的。这样既避免了双维护的浪费又保证了两类用户的体验可以各自优化。4.2 Agent 接入层能力注册与参数校验Agent 接入层是 ANX 协议落地最重的部分。每个能力都需要注册一个处理函数并且在执行前做严格的参数校验。registry.register(query_product) def query_product(params: dict, ctx: dict): # 自动参数校验schema 校验由 registry 统一处理 product_id params[product_id] product db.query_one(SELECT * FROM products WHERE id %s, product_id) if not product: return {error: {code: NOT_FOUND, message: 商品不存在}} # 根据调用方权限做数据脱敏 caller ctx[caller] if caller.type agent and not caller.has_scope(internal:cost_price): product.pop(cost_price, None) return {product: product}注意这里我在函数签名里塞了一个 ctx 参数它由 ANX 运行时在分发时注入携带了调用方的完整上下文身份、权限、会话、幂等键。这比在每个函数里自行解析信封干净得多也是做数据隔离、权限控制、风控策略的基础。执行流里还有个容易踩的坑参数校验要放在业务逻辑之前且校验规则要跟 Manifest 里声明的 schema 保持绝对一致。我在最开始偷懒写了两套校验逻辑一套在 Manifest 声明、一套在代码里后来发现 Manifest 改了但代码没同步Agent 被错误信息误导了好几天。现在我的做法是让代码直接从 Manifest 加载校验规则。4.3 前端共存同一个界面既给人类用也给 Agent“读”之前我说了 Agent 不用浏览器但这里有个容易被忽略的点在很多场景下Agent 需要“理解”一个人类界面的内容才能做出决策。比如一个聚合比价 Agent它可能拿到的数据源既有 ANX 接口又有普通网页。所以我在前端实现上也做了“机器可读语义”的注入让人类的 UI 同时携带结构化数据。最实用的做法是在 HTML 里嵌入 JSON-LD 或 RDFa 标注。人类看到的是精美的商品卡片Agent 解析页面时却能直接拿到机器的结构化数据而不需要去猜某个价格字符串是什么含义。div classproduct-card h2 classproduct-title高性能机械键盘/h2 span classprice¥ 899/span script typeapplication/ldjson { context: https://schema.org, type: Product, name: 高性能机械键盘, sku: P120938, offers: { type: Offer, price: 899.00, priceCurrency: CNY, availability: https://schema.org/InStock } } /script /div这套做法的收益是让“人类界面”和“Agent 数据源”不冲突。Agent 可以直接基于结构化标注来提取信息不需要 OCR、不需要图像识别、不需要复杂的 DOM 解析。等于你的产品在不牺牲任何人类用户体验的前提下天然变成了 Agent 可以消费的数据源。4.4 会话共存让人类和 Agent 出现在同一个工作流里人机共用的进阶形态不只是“都能访问”还包括“互相协作”。我发现最有价值的场景是Agent 发起一个事务请求但关键节点需要人类确认。比如一个订货 Agent 发现了性价比不错的商品自动生成了采购单但最后一步的“确认付款”需要人类主管点击。ANX 支持这种行为思路是给每个事务分配一个状态机包含 pending_human_confirmation 这个状态。Agent 在该状态下提交事项系统通过 Webhook 通知人类用户人类用户点击确认后事务继续流转。这个流程里Agent 和人类各司其职各用各的客户端共享的是同一份事务数据。{ transaction_id: trx_7281aa, initiator: { type: agent, agent_id: agent-procurement-v2 }, current_state: pending_human_confirmation, required_actions: [ { action: approve_payment, assigned_to: human, timeout_hours: 24 } ] }这类“混合事务”在工作流引擎里实现起来并不复杂难点在设计上要有意识地把它建模出来而不是事后打补丁。我现在回头看我自己的第一个版本当时 Transaction 模型里只有“发起人”和“操作人”两个字段结果 Agent 发起的流程根本没法优雅地插入人类审批环节后来把模型重构升级成“发起方 状态机 操作队列 审批链”才彻底解决。5. 落地过程中的典型问题与排查实录再干净的设计落地时都会遇到一堆“设计时没想到”的问题。我把我在开发 ANX 参考实现和搭建示例应用过程中最有代表性的几个问题整理出来希望能帮你省一点排查时间。5.1 Agent 身份混淆导致的数据泄露第一次上线测试时我遇到一个非常吓人的问题某些 Agent 调用竟然返回了本不该看到的内部成本数据。排查了很久最后发现根因是会话中间件在解析 user 身份时默认取的是 HTTP Header 里的 User-Agent 字段结果把这个值当成了人类用户的标识。而 ANX 的信封里明明写着调用方是个外部 Agent中间件却不认识新的身份字段。这个问题的教训很直接一旦引入“双用户模型”你的中间件、过滤器、依赖注入框架里的“当前用户”概念必须进行重构升级不能再默认只有一个身份来源。我在 protocol 层面把 caller 类型作为最高优先级的身份来源任何中间件在解析身份时先看 ANX 信封再看传统会话彻底杜绝了身份取错的问题。5.2 幂等设计被“聪明”的 Agent 绕过的教训还有一个令人啼笑皆非的问题。我最初把幂等键设计成可选字段理由是“不要为难开发者”。结果某个 Agent 在重试时每次重新生成幂等键导致同一条采购指令被重复执行了多次。它“聪明”地以为这样能绕开幂等限制实际上是在给自己制造灾难性的重复订单。从这次之后我把幂等键改成了强制字段并在服务端维护了一个幂等键与响应结果映射的缓存。同样的行为要是发生了服务端会直接返回缓存中的首次结果而不是重新执行一遍业务逻辑。这个改动对于写操作类的 Agent 调用尤其重要我建议所有做的人机共用系统都直接照抄。5.3 频控策略引发的连环失败第三个印象深刻的问题是高并发场景下的“频控误伤”。我最初给每个 Agent 令牌设置每分钟 60 次的调用限制结果单个 Agent 内部有 10 个并发任务每个任务都在调同一个接口瞬间就把 60 次的额度打满了剩余任务全部收到 429。更糟的是Agent 收到 429 后开始指数退避重试造成用户体验上“事情没办完且看起来卡死了”。现在的方案是双桶频控第一层用令牌桶限制单个 Agent 账号的总速率第二层用滑动窗口限制单个会话内的调用节奏。同时我在限流响应里带上 Retry-After 字段让 Agent 知道该等多久而不是靠猜。这本质上是在协议层给 Agent 一个明确的“交通信号”让它能自我调节。5.4 常见问题速查表我把一些管线上的问题做成了一张排查速查表遇到问题时按图索骥就好。现象可能原因排查手段与解决方案Agent 拿到 401令牌过期或颁发时签名密钥变更检查令牌签发时间的失效时间戳确认密钥轮换策略是否把旧令牌拉黑Agent 拿到 403权限 scope 不足查看 Manifest 中该能力声明的 auth_required 等级检查 Agent 令牌绑定的 scopeAgent 重复创建订单幂等键缺失或重复生成确认请求信封中是否强制携带 idempotency_key服务端是否配置幂等结果缓存Agent 调用时好时坏频控策略太激进超并发触发检查是否使用双桶限流查看 429 响应中的 Retry-After前端页面加载慢日志记录里 Agent 请求过多给 Agent 请求单独路由不走前端静态资源服务配置独立的资源配额Agent 拿到过时数据缓存层级未区分用户类型为 Agent 调用设置独立缓存策略配置更短 TTL 或直接走实时查询6. 最后再分享一点个人实操经验整套方案从设计到落地我最有感触的一点是真正难的不是协议本身怎么写而是你想清楚“为什么要让 Agent 成为你的用户”。很多人一听说 Agent 流量占比上升了第一反应是做防御、做拦截、做风控把非人类流量一律按爬虫处理。但换个角度看这些 Agent 里相当大一部分是在认真地替你或替你的客户办事把它们赶到对立面去你只会损失更多价值。所以我给自己的原则是给 Agent 一个合法、高效、可控的“入口”让它们走正规军路线而不是去做游击战。这个入口越顺畅、越透明、越安全Agent 就越愿意遵守规则整体生态就越干净。这也正是我开源 ANX 协议的根本原因——我一个人解决不了所有应用的接入问题但如果协议本身是开放、标准、经过真实场景检验的就会有更多人一起把这套“人机共用”的基础设施建起来。如果你也想在项目里试验这套思路我的建议是从最小闭环开始先写一份 Capability Manifest 暴露三五个只读能力做一个协议入口接受 Agent 调用配上审计日志观察几天看看流量和行为是否符合预期。没问题之后再逐步开放写操作、引入审批流、扩展混合事务。循序渐进你会发现 Agent 用户就跟人类用户一样只要入口清晰、规则明确就能和你真正产生长期协作价值。
帮你守住博士论文的格式规范)
