6 个开箱即用的 JSON 模板 · A2A v1.0

A2A Agent Card 示例

浏览实用的 A2A v1.0 模板，理解其设计决策，然后为你自己的智能体改写任意示例。

浏览模板打开生成器

公开智能体发现

用这些示例来塑造另一个 A2A 客户端在决定你的智能体能否完成任务之前会获取的 JSON。

市场提交

改写提供方、技能、标签、能力和安全元数据，让审核人员理解这个智能体做什么、由谁运营。

内部智能体目录

在团队将内部智能体集成到工作流之前，统一它们描述端点、身份验证和技能的方式。

JSON 模板

面向客服、预订、购物、编程、调研和工作流智能体的示例 Agent Card。

校验一个模板

筛选

客服智能体

处理产品咨询、订单查询、退货，以及升级转接。

为什么这样设计

OAuth 2.0 客户端凭据保护订单数据：Agent Card 声明了令牌 URL 和作用域，让客户端无需带外文档即可完成身份验证。
streaming 和 pushNotifications 都为 true，因为客服对话通常持续较长时间，且处理结果会异步到达。
这个单一技能被限定在一个任务边界内（分类、解决、升级），而不是模糊的“帮助客户”描述，因此路由系统可以精确匹配它。

customer-support.json

{
  "name": "客服智能体",
  "description": "回答客户支持问题、获取订单上下文，并将未解决的问题升级给人工团队。",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/customer-support",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "示例公司",
    "url": "https://example.com"
  },
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "extendedAgentCard": false
  },
  "defaultInputModes": [
    "text/plain",
    "application/json"
  ],
  "defaultOutputModes": [
    "text/plain",
    "application/json"
  ],
  "skills": [
    {
      "id": "resolve-customer-support-request",
      "name": "处理客户支持请求",
      "description": "对客户支持请求进行分类、收集所需上下文、提出解决方案，并在置信度较低时升级处理。",
      "tags": [
        "support",
        "orders",
        "returns"
      ],
      "examples": [
        "帮我退掉这个订单。"
      ]
    }
  ],
  "securitySchemes": {
    "oauth2": {
      "oauth2SecurityScheme": {
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://api.example.com/a2a/customer-support/oauth/token",
            "scopes": {
              "agent.invoke": "Invoke agent skills"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "oauth2": [
        "agent.invoke"
      ]
    }
  ]
}

预订智能体

查找可用的预约时段，并准备预订确认。

为什么这样设计

这里用请求头中的 API 密钥就足够：预订按租户划分范围，但不涉及 OAuth 要解决的委托用户同意问题。
defaultOutputModes 仅为 application/json，表明调用方获得的是结构化的预订提案而非散文文本。
pushNotifications 为 true，这样智能体可以在占位后端确认之后通知预订结果，而无需客户端轮询。

booking.json

{
  "name": "预订智能体",
  "description": "搜索可用时间、提出预订选项，并准备待确认的预约。",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/booking",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "示例公司",
    "url": "https://example.com"
  },
  "version": "1.0.0",
  "capabilities": {
    "streaming": false,
    "pushNotifications": true,
    "extendedAgentCard": false
  },
  "defaultInputModes": [
    "text/plain",
    "application/json"
  ],
  "defaultOutputModes": [
    "application/json"
  ],
  "skills": [
    {
      "id": "find-and-prepare-booking",
      "name": "查找并准备预订",
      "description": "检查资源可用性、比较预订时段，并返回结构化的预订提案。",
      "tags": [
        "booking",
        "calendar",
        "availability"
      ],
      "examples": [
        "帮我找明天下午 30 分钟的预约。"
      ]
    }
  ],
  "securitySchemes": {
    "apiKey": {
      "apiKeySecurityScheme": {
        "location": "header",
        "name": "X-API-Key"
      }
    }
  },
  "security": [
    {
      "apiKey": []
    }
  ]
}

购物智能体

比较商品、库存、价格和购买限制条件。

为什么这样设计

排名推荐结果在计算过程中流式传出，因此 streaming 为 true，而 pushNotifications 保持 false——响应完成后不再发生任何事。
技能描述承诺返回权衡取舍和理由，这告诉编排系统该智能体会解释排名，而不仅仅是列出商品。
OAuth 作用域限制了与购买相关的数据；一个公开的购物演示完全可以去掉安全声明，仍然是一份有效的 Agent Card。

shopping.json

{
  "name": "购物智能体",
  "description": "根据用户限制条件比较商品，并返回附有取舍说明的排序购买选项。",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/shopping",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "示例公司",
    "url": "https://example.com"
  },
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "extendedAgentCard": false
  },
  "defaultInputModes": [
    "text/plain",
    "application/json"
  ],
  "defaultOutputModes": [
    "application/json"
  ],
  "skills": [
    {
      "id": "compare-shopping-options",
      "name": "比较购物选项",
      "description": "评估候选商品、按限制条件筛选，并返回附带理由的排序推荐。",
      "tags": [
        "shopping",
        "commerce",
        "recommendations"
      ],
      "examples": [
        "比较价格低于 1,200 美元的轻薄笔记本电脑。"
      ]
    }
  ],
  "securitySchemes": {
    "oauth2": {
      "oauth2SecurityScheme": {
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://api.example.com/a2a/shopping/oauth/token",
            "scopes": {
              "agent.invoke": "Invoke agent skills"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "oauth2": [
        "agent.invoke"
      ]
    }
  ]
}

编程智能体

审阅编码任务，提出补丁，并解释实现决策。

为什么这样设计

extendedAgentCard 为 true：公开 Agent Card 只列出通用的“实现代码变更”技能，而特定于仓库的技能只通过 GetExtendedAgentCard 向经过身份验证的客户端展示。
同时声明了 text/plain 和 application/json 两种输出，因为该智能体既返回人类可读的解释，也返回机器可应用的补丁。
流式传输对于漫长的编译-测试循环很重要；客户端能看到中间进度，而不是一次沉默的多分钟调用。

coding.json

{
  "name": "编程智能体",
  "description": "通过分析代码、提出修改建议并返回实现说明来协助软件工程任务。",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/coding",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "示例公司",
    "url": "https://example.com"
  },
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "extendedAgentCard": true
  },
  "defaultInputModes": [
    "text/plain",
    "application/json"
  ],
  "defaultOutputModes": [
    "text/plain",
    "application/json"
  ],
  "skills": [
    {
      "id": "implement-code-change",
      "name": "实现代码变更",
      "description": "读取编码请求、检查相关文件、返回补丁建议，并总结验证步骤。",
      "tags": [
        "coding",
        "review",
        "patches"
      ],
      "examples": [
        "为用户 API 添加分页。"
      ]
    }
  ],
  "securitySchemes": {
    "apiKey": {
      "apiKeySecurityScheme": {
        "location": "header",
        "name": "X-API-Key"
      }
    }
  },
  "security": [
    {
      "apiKey": []
    }
  ]
}

调研智能体

收集资料来源，提取证据，并返回结构化的调研笔记。

为什么这样设计

完全没有 securitySchemes：该端点是刻意公开的，省略该字段正是表达这一点的正确方式——一个空的方案映射反而会产生歧义。
输入仅为 text/plain，因为调研简报都是从自然语言问题开始的；结构化输出以 application/json 笔记的形式到达。
这是一份最小可用的 v1.0 Agent Card：身份、一个接口、能力、模式，以及一个打好标签的技能。

research.json

{
  "name": "调研智能体",
  "description": "收集来源材料、提取证据，并产出带引文的结构化调研笔记。",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/research",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "示例公司",
    "url": "https://example.com"
  },
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "extendedAgentCard": false
  },
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain",
    "application/json"
  ],
  "skills": [
    {
      "id": "prepare-research-brief",
      "name": "准备调研简报",
      "description": "检索已批准的来源、提取主张和证据，并返回简明的调研简报。",
      "tags": [
        "research",
        "evidence",
        "citations"
      ],
      "examples": [
        "准备一份关于可再生能源政策的带引文简报。"
      ]
    }
  ]
}

内部工作流智能体

协调审批、状态检查，以及后台工作流更新。

为什么这样设计

application/json 是唯一的输入输出模式：这个智能体由其他系统调用，绝不会有人直接输入散文文本。
OAuth 2.0 加上 extendedAgentCard 很适合企业审计——安全团队可以公开看到身份验证要求，而敏感的工作流技能仍留在身份验证之后。
pushNotifications 至关重要，因为审批链可能耗时数小时甚至数天；webhook 取代轮询来处理状态变化。

internal-workflow.json

{
  "name": "内部工作流智能体",
  "description": "协调内部审批、检查系统状态，并为运营团队准备工作流更新。",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/workflow",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "示例公司",
    "url": "https://example.com"
  },
  "version": "1.0.0",
  "capabilities": {
    "streaming": false,
    "pushNotifications": true,
    "extendedAgentCard": true
  },
  "defaultInputModes": [
    "application/json"
  ],
  "defaultOutputModes": [
    "application/json"
  ],
  "skills": [
    {
      "id": "coordinate-internal-workflow",
      "name": "协调内部工作流",
      "description": "接收工作流意图、检查策略要求、收集审批，并报告最终状态。",
      "tags": [
        "workflow",
        "operations",
        "approval"
      ],
      "examples": [
        "申请批准部署薪资系统更新。"
      ]
    }
  ],
  "securitySchemes": {
    "oauth2": {
      "oauth2SecurityScheme": {
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://api.example.com/a2a/workflow/oauth/token",
            "scopes": {
              "agent.invoke": "Invoke agent skills"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "oauth2": [
        "agent.invoke"
      ]
    }
  ]
}

自信地改写

如何改写一个 Agent Card 示例

每个 Agent Card 示例都刻意做到足够完整以便直接复制，但 Agent Card 不应原封不动地发布。把它当作你自己 A2A 服务器的字段映射表：用生产环境的值替换身份、端点、提供方、身份验证、能力、模式和技能细节。

最出色的 Agent Card 会用通俗语言和机器可读的元数据来解释智能体的任务边界。客户端应该能够判断这个智能体能做什么、不能做什么、该调用哪个 URL，以及是否需要凭据。

发布前须知

把每一个 example.com URL 替换成你已部署的 A2A 端点和提供方网站。

针对实际的任务边界重写技能名称、描述、标签（v1.0 中为必填）和示例。

设置 provider.organization，并在 Agent Card 内容变化时提升顶层 version。

只有当端点是刻意公开时，才移除身份验证字段。

保持 defaultInputModes 和 defaultOutputModes 与你的服务器实际接受和返回的内容一致。

校验最终的 JSON，并将其发布在你服务域名下的 /.well-known/agent-card.json。

校验一个示例阅读 schema 指南

准备开始构建

从一个示例开始，然后把它变成你自己的。

在 Agent Card 生成器中打开任意模式，审查 JSON，并在发布前进行校验。

打开 Agent Card 生成器校验一份 Agent Card