--- id: "2026-03-24-agent-friendly-deep-research" title: "Agent Friendly 深度研究：让系统对 AI Agent 友好的设计范式" slug: "agent-friendly-deep-research" status: "inbox" content_type: "article" channels: ["wechat", "x"] language: "zh-CN" source_urls: - "https://agentexperience.ax/" - "https://llmstxt.org/" - "https://agents.md/" - "https://modelcontextprotocol.io/specification/2025-11-25" - "https://a2a-protocol.org" - "https://github.com/stefanbuck/ai-api-best-practices" - "https://github.com/janwilmake/agent-friendly" - "https://workos.com/blog/build-agent-friendly-products" - "https://biilmann.blog/articles/introducing-ax/" - "https://blogs.mulesoft.com/automation/api-design-for-agentic-ai/" - "https://www.apideck.com/blog/api-design-principles-agentic-era" - "https://refactoring.fm/p/how-to-design-apis-for-an-ai-world" - "https://www.postman.com/ai/ai-ready-apis/" - "https://arxiv.org/abs/2505.02279" - "https://arxiv.org/abs/2504.16736" assets: [] cover_image: "" template: "article" owner: "content-forge" created_at: "2026-03-24T00:00:00+08:00" updated_at: "2026-03-24T00:00:00+08:00" published_at: null tags: ["agent-friendly", "AX", "MCP", "A2A", "API-design", "agentic-AI"] --- # Agent Friendly 深度研究报告 ## 一、定义与演进 **Agent Friendly** = 让 AI Agent 能自主**发现、理解、调用、验证**你的系统，无需人类在旁翻译。 类比链： ``` Mobile Friendly (2010s) → Developer Friendly / DX (2011) → Agent Friendly / AX (2025) 网站适配手机 API 适配开发者 系统适配 AI Agent ``` **AX（Agent Experience）** 由 Netlify CEO **Matt Biilmann** 于 2025 年初正式命名，定位为 UX → DX 之后的第三代体验设计范式。 > "Your documentation is now your product's UI -- for agents." — WorkOS --- ## 二、为什么现在重要？ | 数据点 | 来源 | |--------|------| | 89% 开发者日常使用 AI 工具，但仅 **24%** 为 Agent 设计 API | Postman 2025 | | Cloudflare 2024 年首次报告自动化流量超过人类流量 | Cloudflare | | RAG Agent 流量 2025 年初飙升 **49%** | Apideck | | Gartner：2026 年底 **40%** 企业应用将嵌入 AI Agent | Gartner | | Gartner：2028 年 **90%** B2B 采购由 Agent 代理，涉及 **$15T** | Gartner | | AI 引荐流量转化率高 **31%**，单次访问收入高 **254%** | Adobe | | Agentic AI 市场：$7B (2025) → **$236B (2034)** | 多方预测 | --- ## 三、协议栈全景（The "Big Five"） ``` ┌──────────────────────────────────────────────────────────────┐ │ Agentic AI Foundation (AAIF) │ │ Linux Foundation · Anthropic + OpenAI + Block │ ├──────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │ │ llms.txt │ │ AGENTS.md │ │ Schema.org/JSON-LD│ │ │ │ 文档发现层 │ │ 项目指令层 │ │ 结构化数据层 │ │ │ └──────┬──────┘ └──────┬──────┘ └──────────┬──────────┘ │ │ │ │ │ │ │ ┌──────▼──────────────────────────────────────▼──────────┐ │ │ │ MCP (Model Context Protocol) │ │ │ │ Agent ←→ Tool 垂直连接 │ │ │ │ Anthropic 创建，97M+ 月下载 │ │ │ └──────────────────────┬────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────▼────────────────────────────────┐ │ │ │ A2A (Agent-to-Agent Protocol) │ │ │ │ Agent ←→ Agent 水平互操作 │ │ │ │ Google 创建，150+ 组织支持，RC 1.0 │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ └──────────────────────────────────────────────────────────────┘ ``` ### 协议对比 | 维度 | MCP | A2A | llms.txt | AGENTS.md | |------|-----|-----|----------|-----------| | **层** | Agent→Tool | Agent→Agent | 文档发现 | 项目指令 | | **传输** | JSON-RPC, stdio | HTTP, SSE, gRPC | 静态文件 | 静态文件 | | **发现** | 服务端定义 | Agent Card (.well-known) | /llms.txt | 仓库根目录 | | **治理** | AAIF/Linux Foundation | Linux Foundation | 社区 | AAIF | | **采纳量** | 10,000+ MCP Server | 150+ 组织 | 600+ 网站 | 60,000+ 仓库 | --- ## 四、Agent Friendly 的 10 条设计原则 综合自 Apideck、Stefan Buck、O'Reilly、The New Stack、WorkOS 等多个权威来源。 | # | 原则 | 说明 | |---|------|------| | 1 | **Schema-First** | 完整 OpenAPI 3.0+ spec，每个端点/参数/响应都有富描述 | | 2 | **可预测 & 一致** | 统一命名、一致 JSON 结构、类型化错误码 | | 3 | **自描述** | 响应中包含足够上下文让 Agent 知道下一步做什么（HATEOAS） | | 4 | **可组合** | 小而可链的端点，非巨型操作 | | 5 | **程序化认证** | API Key / OAuth 2.0，无 CAPTCHA、无"联系销售" | | 6 | **丰富错误响应** | 说明 WHY 失败 + HOW 修复 + is_retriable + retry_after | | 7 | **机器可读文档** | llms.txt、Markdown-first、结构化元数据 | | 8 | **逻辑下沉到 API** | 计算和验证在 API 端完成，LLM 只做语言理解 | | 9 | **安全机制** | dry-run 模式、不可逆操作确认步、成本感知 | | 10 | **内容协商** | 按 Accept header 返回 HTML（浏览器）或 Markdown/JSON（Agent） | --- ## 五、标杆实践 ### Stripe — 当前最完整的 Agent Friendly 生态 ``` ┌─────────────────────────────────────────────┐ │ Stripe Agent 生态 │ ├─────────────┬───────────────────────────────┤ │ Agent Toolkit │ @stripe/agent-toolkit │ │ (SDK 集成) │ OpenAI / LangChain / CrewAI │ ├─────────────┼───────────────────────────────┤ │ Remote MCP │ mcp.stripe.com (OAuth) │ ├─────────────┼───────────────────────────────┤ │ ACP 协议 │ Agentic Commerce Protocol │ │ │ (与 OpenAI 联合，Apache 2.0) │ ├─────────────┼───────────────────────────────┤ │ 集成基准 │ 首个生产级 Agent 集成评测 │ │ │ "支付必须 100% 正确" │ ├─────────────┼───────────────────────────────┤ │ llms.txt │ 含 instructions section │ │ │ 主动纠正模型漂移 │ └─────────────┴───────────────────────────────┘ ``` ### 其他标杆 | 公司 | Agent Friendly 举措 | |------|---------------------| | **Shopify** | 双 MCP Server（Dev + Storefront）、Catalog API（数十亿商品）、Checkout Kit | | **Twilio** | AI Assistants 框架、ConversationRelay（电话→LLM）、BYOLLM | | **HubSpot** | 双 MCP 架构（远程 CRM + 本地开发） | | **Clerk** | 全自动 Agent 认证流程（零人工介入） | | **Visa** | Trusted Agent Protocol (TAP)，2025 年底完成数百笔 Agent 交易 | | **Mastercard** | Agent Pay，2025 年 11 月全美上线 | --- ## 六、文档发现层三剑客 | 标准 | 角色 | 格式 | 采纳 | |------|------|------|------| | **llms.txt** | "robots.txt for AI" — 网站摘要 | Markdown @ `/llms.txt` | 600+ 网站 | | **llms-full.txt** | 完整文档单文件 | Markdown @ `/llms-full.txt` | Mintlify/Anthropic 联合 | | **Agent Card** | Agent 能力声明 | JSON @ `/.well-known/agent-card.json` | A2A 生态 | **现实检查**：截至 2025 年 8 月，主要 LLM 爬虫（GPTBot、ClaudeBot）尚未主动读取 llms.txt。robots.txt 仍是实际控制机制。llms.txt 更多被 MCP/RAG 管道消费。 --- ## 七、Agent SEO — 让 Agent 发现你 ``` 传统 SEO Agent SEO (LLMO) ───────────────── ───────────────── 关键词密度 结构化数据 (JSON-LD) 反向链接 llms.txt + Agent Card HTML Schema.org markup Google SERP 排名 AI Overview 引用率 点击率 (CTR) 零点击占比 (58.5%) ``` 关键数据： - 58.5% Google 搜索零点击 - AI Overview 出现时，有机 CTR 下降 **61%+** - Google（2025 年 5 月）官方推荐 JSON-LD - SearchVIU 测试确认 ChatGPT/Claude/Perplexity/Gemini 均处理 Schema Markup --- ## 八、中国生态：智能体友好 国内 MCP 采纳爆发式增长： - 支付宝 MCP 服务（首个国内 AI 支付场景工具） - MiniMax 多模态 MCP 服务 - 多个"MCP 广场"（市场）上线 - 讯飞星辰（StarAgent）支持 MCP Server 发布 国内实践共识的 4 层 Agent 架构： ``` ┌─────────────────────────┐ │ 认知层 (Cognitive) │ LLM 意图理解 + 任务分解 ├─────────────────────────┤ │ 技能层 (Skill) │ 原子执行单元，明确输入/输出 Schema ├─────────────────────────┤ │ 连接层 (Connection) │ MCP / 数据库 / SaaS / 企业内网 ├─────────────────────────┤ │ 持续层 (Persistence) │ 状态、记忆、任务检查点管理 └─────────────────────────┘ ``` --- ## 九、学术论文 | 论文 | arXiv | 焦点 | |------|-------|------| | Survey of Agent Interoperability Protocols | 2505.02279 | MCP→ACP→A2A→ANP 分阶段采纳路线图 | | A Survey of AI Agent Protocols | 2504.16736 | 类比早期碎片化 Internet | | Multi-Agent Collaboration Mechanisms | 2501.06322 | 协作维度可扩展框架 | | Orchestration of Multi-Agent Systems | 2601.13671 | 统一架构框架 | | Evolution of AI Agent Registry Solutions | 2508.03095 | 5 种注册发现架构对比 | --- ## 十、关键引用 > "Designing for AI agents is designing for the strictest, most literal and tireless user imaginable." — Apidog > "APIs weren't built for machines that think." — MuleSoft > "Your documentation is now your product's UI -- for agents." — WorkOS > "All the usual best practices in API design matter **more** when making an API agent-ready. LLMs are pattern-followers." — Apideck > "Gartner predicts that by 2026, over 30% of the growing demand for APIs will come not from human developers, but from AI agents." --- ## 十一、核心资源链接 ### 协议 & 标准 - MCP 规范: https://modelcontextprotocol.io/specification/2025-11-25 - A2A 协议: https://a2a-protocol.org - llms.txt 规范: https://llmstxt.org - AGENTS.md: https://agents.md - AAIF: https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation - Agentic Commerce Protocol (Stripe + OpenAI): https://stripe.com/blog/developing-an-open-standard-for-agentic-commerce ### 设计指南 - AX 官网: https://agentexperience.ax - Stefan Buck AI API 最佳实践: https://github.com/stefanbuck/ai-api-best-practices - Agent-Friendly Web 原则: https://github.com/janwilmake/agent-friendly - AX 设计模式库 (26 patterns): https://agent-experience.dev - Apideck 设计原则: https://www.apideck.com/blog/api-design-principles-agentic-era - WorkOS "How to build agent-friendly products": https://workos.com/blog/build-agent-friendly-products - Biilmann "Introducing AX": https://biilmann.blog/articles/introducing-ax/ - MuleSoft "API Design for Agentic AI": https://blogs.mulesoft.com/automation/api-design-for-agentic-ai/ - Refactoring.fm "APIs for an AI World": https://refactoring.fm/p/how-to-design-apis-for-an-ai-world - O'Reilly "How to Write a Good Spec for AI Agents": https://www.oreilly.com/radar/how-to-write-a-good-spec-for-ai-agents/ ### 评估工具 - Postman API Agent Readiness (48 项检查): https://www.postman.com/ai/ai-ready-apis/ - FourWeekMBA Readiness Checker: https://fourweekmba.com/api-agent-readiness-checker/ ### 行业报告 - Postman 2025 State of API: https://voyager.postman.com/doc/postman-state-of-the-api-report-2025.pdf ### 关键人物 - **Matt Biilmann** (Netlify CEO) — 命名 AX (Agent Experience) - **Jeremy Howard** (Answer.AI) — 提出 llms.txt 规范 - **janwilmake** — Agent-Friendly Web 原则 - **Stefan Buck** — AI API 最佳实践 --- ## 十二、写作角度备选 1. **"好设计的自然延伸"** — Agent Friendly 不是新概念，MCP 借鉴 LSP，llms.txt 借鉴 robots.txt，Agent Card 借鉴 .well-known，每个"新"标准都是已验证设计智慧的重组 2. **"从 DX 到 AX"** — 开发者体验演进史，UX→DX→AX 三代范式对比 3. **"API 的新用户不是人"** — 从 Postman 89% vs 24% 的数据切入，Agent 作为 API 第一消费者 4. **"Agent Friendly = 约束 > 能力"** — 与 content-forge 项目设计哲学呼应，好的 Agent Friendly 设计是消除 Agent 需要猜测的一切 5. **"协议战争"** — MCP vs A2A vs ACP，类比 HTTP 早期标准化历史 6. **"中国智能体友好生态"** — 国内 MCP 广场爆发、4 层架构共识、安全挑战