290 lines
15 KiB
Markdown
290 lines
15 KiB
Markdown
---
|
||
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 <title> 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 层架构共识、安全挑战
|