zhukang/content-forge-vault

Fork 0

lizikk 09aad62ec3 vault: auto-sync 2026-03-25 02:00

2026-03-25 02:00:01 +08:00

15 KiB

Raw Blame History

title

slug

status

content_type

channels

language

source_urls

assets

cover_image

template

owner

created_at

updated_at

published_at

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."

十一、核心资源链接

关键人物

Matt Biilmann (Netlify CEO) — 命名 AX (Agent Experience)
Jeremy Howard (Answer.AI) — 提出 llms.txt 规范
janwilmake — Agent-Friendly Web 原则
Stefan Buck — AI API 最佳实践

十二、写作角度备选

"好设计的自然延伸" — Agent Friendly 不是新概念，MCP 借鉴 LSP，llms.txt 借鉴 robots.txt，Agent Card 借鉴 .well-known，每个"新"标准都是已验证设计智慧的重组
"从 DX 到 AX" — 开发者体验演进史，UX→DX→AX 三代范式对比
"API 的新用户不是人" — 从 Postman 89% vs 24% 的数据切入，Agent 作为 API 第一消费者
"Agent Friendly = 约束 > 能力" — 与 content-forge 项目设计哲学呼应，好的 Agent Friendly 设计是消除 Agent 需要猜测的一切
"协议战争" — MCP vs A2A vs ACP，类比 HTTP 早期标准化历史
"中国智能体友好生态" — 国内 MCP 广场爆发、4 层架构共识、安全挑战

15 KiB Raw Blame History Unescape Escape