Tài liệu tham khảo schema · 14 fieldsA2A v1.0
Agent Card là tài liệu JSON được chuẩn hóa cho client A2A biết một agent là ai, liên hệ ở đâu, có thể làm gì, và quyền truy cập được bảo vệ như thế nào. Tài liệu tham khảo này bao gồm mọi trường v1.0 với loại, yêu cầu, ví dụ, và các lỗi mà trình kiểm định thường phát hiện nhất.
Cách khám phá hoạt động
Một client A2A lấy Agent Card từ URI well-known, đánh giá skill, capability, và yêu cầu bảo mật theo tác vụ của nó, sau đó gọi interface ưu tiên — mục đầu tiên trong supportedInterfaces. Nếu capabilities.extendedAgentCard là true, client đã xác thực có thể yêu cầu một Agent Card phong phú hơn thông qua thao tác GetExtendedAgentCard.
Đặc tả đăng ký /.well-known/agent-card.json như vị trí chuẩn. Các triển khai v0.x cũ hơn sử dụng /.well-known/agent.json, đó là lý do trình kiểm định của chúng tôi kiểm tra cả hai.
# Fetch a public Agent Card
GET /.well-known/agent-card.json HTTP/1.1
Host: agent.example.com
HTTP/1.1 200 OK
Content-Type: application/a2a+json
{
"name": "GeoSpatial Route Planner Agent",
"supportedInterfaces": [
{ "url": "https://georoute-agent.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
],
...
}Tham khảo trường
Các cờ bắt buộc tuân theo định nghĩa protobuf v1.0 trong đặc tả chính thức. Liên kết neo giúp mỗi trường có thể được trích dẫn từ issue, đánh giá, và đầu ra CI.
Tên có thể đọc được của agent.
Hiển thị trong danh sách marketplace và giao diện client. Giữ ngắn gọn và cụ thể — client sử dụng nó làm nhãn chính khi so sánh các agent ứng viên.
Lỗi thường gặp: Sử dụng tên chung chung như "AI Assistant" không cho hệ thống định tuyến bất kỳ điều gì để phân biệt.
"name": "Đại lý lập kế hoạch tuyến đường không gian địa lý"
Agent làm gì và khi nào agent khác nên gọi nó.
Đây là tín hiệu văn bản tự do chính cho cả người tích hợp và router dựa trên LLM quyết định xem agent của bạn có phù hợp với một tác vụ hay không. Nêu rõ lĩnh vực tác vụ, khả năng chính, và giới hạn.
Lỗi thường gặp: Mô tả một dòng dưới 20 ký tự. Router không thể khớp những gì bạn không mô tả.
"description": "Cung cấp các dịch vụ lập kế hoạch tuyến đường, phân tích lưu lượng truy cập và tạo bản đồ tùy chỉnh nâng cao."
Danh sách có thứ tự các endpoint và protocol binding. Mục đầu tiên được ưu tiên.
Mới trong v1.0: thay thế các trường cấp cao nhất cũ url, preferredTransport, và additionalInterfaces. Mỗi mục khai báo url riêng, protocolBinding (JSONRPC, GRPC, HTTP+JSON, hoặc URI binding tùy chỉnh), protocolVersion, và khóa định tuyến tenant tùy chọn — vì vậy một agent có thể phục vụ nhiều phiên bản giao thức và phương thức truyền tải cùng lúc.
Lỗi thường gặp: Khai báo một binding mà server thực tế không phục vụ tại URL đó — đặc tả yêu cầu mỗi mục phải chính xác.
"supportedInterfaces": [
{ "url": "https://api.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
]Ai vận hành agent: tổ chức và trang web.
Tín hiệu tin cậy cho marketplace và kiểm toán doanh nghiệp. v1.0 đã đổi tên trường name thành organization; url là bắt buộc bên trong đối tượng khi có mặt.
Lỗi thường gặp: Vẫn sử dụng provider.name (trước v1.0). Trình kiểm định đọc Agent Card v1.0 sẽ không nhận ra nó.
"provider": {
"organization": "Ví dụ Geo Services Inc.",
"url": "https://www.examplegeoservices.com"
}Phiên bản của chính agent, không phải giao thức.
Cho phép client phát hiện khi nào Agent Card đã thay đổi đáng kể và đánh giá lại khả năng tương thích. Tuân theo lược đồ phát hành riêng của bạn, thường là semver.
Lỗi thường gặp: Nhầm lẫn điều này với phiên bản giao thức A2A — giờ đây nó nằm trên mỗi mục supportedInterfaces.
"version": "1.2.0"
Liên kết đến tài liệu có thể đọc được của agent.
Cho người tích hợp một nơi để đọc hợp đồng API đầy đủ, giới hạn tốc độ, và các điều khoản không thuộc về tài liệu khám phá.
Lỗi thường gặp: Trỏ đến trang chủ tiếp thị thay vì tài liệu kỹ thuật.
"documentationUrl": "https://docs.example.com/agent"
Cờ tính năng giao thức: streaming, pushNotifications, extensions, extendedAgentCard.
Client KHÔNG ĐƯỢC gọi các tính năng bạn chưa khai báo — các cuộc gọi streaming không khai báo trả về lỗi. extendedAgentCard: true công bố một Agent Card đã xác thực phong phú hơn thông qua thao tác GetExtendedAgentCard. v1.0 đã xóa stateTransitionHistory.
Lỗi thường gặp: Khai báo streaming: true khi server không có endpoint streaming. Client sẽ gọi nó và thất bại.
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
}Các sơ đồ xác thực có tên: khóa API, xác thực HTTP, OAuth 2.0, OpenID Connect, hoặc TLS song phương.
Mỗi sơ đồ có tên bọc một đối tượng sơ đồ cụ thể (apiKeySecurityScheme, httpAuthSecurityScheme, oauth2SecurityScheme, openIdConnectSecurityScheme, mtlsSecurityScheme). Client tìm hiểu cách xác thực từ đây — bản thân thông tin xác thực luôn được lấy ngoài băng tần.
Lỗi thường gặp: Nhúng khóa API hoặc token thực vào Agent Card. Agent Card là tài liệu công khai.
"securitySchemes": {
"google": {
"openIdConnectSecurityScheme": {
"openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
}
}
}Những sơ đồ đã khai báo (và phạm vi) nào cần thiết để gọi agent.
Mỗi mục ánh xạ một tên sơ đồ từ securitySchemes đến các phạm vi nó cần, phản ánh mẫu yêu cầu bảo mật OpenAPI. Bỏ qua cả hai trường hoàn toàn cho các agent công khai có chủ đích.
Lỗi thường gặp: Khai báo securitySchemes nhưng không có yêu cầu security, để client tự đoán xem xác thực có được thực thi hay không.
"security": [{ "google": ["openid", "profile", "email"] }]Các loại phương tiện mà agent chấp nhận trên tất cả các skill.
Các loại MIME chuẩn như text/plain, application/json, hoặc image/png. Từng skill riêng lẻ có thể ghi đè bằng inputModes riêng.
Lỗi thường gặp: Bỏ qua trường này. Nó bắt buộc trong v1.0 — client cần nó để định hình các yêu cầu.
"defaultInputModes": ["application/json", "text/plain"]
Các loại phương tiện mà agent trả về trên tất cả các skill.
Cho người gọi biết nên mong đợi văn bản, JSON có cấu trúc, hình ảnh, hay tệp. Skill có thể ghi đè theo từng skill với outputModes.
Lỗi thường gặp: Chỉ liệt kê text/plain khi agent thực tế trả về các sản phẩm có cấu trúc.
"defaultOutputModes": ["application/json", "image/png"]
Các khả năng cụ thể mà agent có khả năng thành công.
Mỗi skill yêu cầu id, name, description, và tags; examples, chế độ theo từng skill, và bảo mật theo từng skill là tùy chọn. Skill là đơn vị khám phá — router khớp tác vụ với chúng, vì vậy hãy giới hạn mỗi skill vào một ranh giới tác vụ duy nhất.
Lỗi thường gặp: Skill không có tag. Tag trở thành bắt buộc trong v1.0 và thúc đẩy việc khớp ở cấp độ skill.
"skills": [{
"id": "route-optimizer-traffic",
"name": "Trình tối ưu hóa lộ trình nhận biết lưu lượng truy cập",
"description": "Tính toán các tuyến đường lái xe tối ưu bằng cách sử dụng giao thông thời gian thực...",
"tags": ["maps", "routing", "traffic"],
"examples": ["Lập kế hoạch tuyến đường từ A đến B để tránh phí cầu đường."]
}]Chữ ký JSON Web chứng minh Agent Card được cấp bởi nhà cung cấp.
Mỗi chữ ký mang một header JWS được bảo vệ base64url và giá trị chữ ký, được tính trên Agent Card đã chuẩn hóa theo RFC 8785 (JCS). Client NÊN xác minh ít nhất một chữ ký trước khi tin tưởng một Agent Card được lấy từ web mở.
Lỗi thường gặp: Ký card rồi sau đó chỉnh sửa bất kỳ trường nào — ngay cả những thay đổi giá trị không đáng kể về khoảng trắng cũng làm JWS không hợp lệ.
"signatures": [{
"protected": "eyJhbGciOiJFUzI1NiIs...",
"signature": "QFdkNLNszlGj3z3u0YQ..."
}]URL đến biểu tượng đại diện cho agent.
Được sử dụng bởi danh mục và giao diện client. Phục vụ nó qua HTTPS từ một vị trí ổn định.
Lỗi thường gặp: Liên kết một biểu tượng trên một tên miền khác, không đáng tin cậy, có thể thay đổi mà không báo trước ẩn sau danh sách của bạn.
"iconUrl": "https://agent.example.com/icon.png"
Di trú phiên bản
Nếu Agent Card của bạn vẫn có url hoặc preferredTransport cấp cao nhất, nó có trước v1.0. Trình kiểm định sẽ tự động đánh dấu từng cái này.
| Trường v0.x | Thay thế v1.0 | Tại sao thay đổi |
|---|---|---|
| url | supportedInterfaces[0].url | Endpoint ưu tiên giờ đây đơn giản là mục interface đầu tiên. |
| preferredTransport | supportedInterfaces[] ordering | Ưu tiên được thể hiện bằng thứ tự mảng thay vì một trường riêng biệt. |
| additionalInterfaces | supportedInterfaces[] | Tất cả các interface nằm trong một mảng có thứ tự duy nhất. |
| protocolVersion (top level) | supportedInterfaces[].protocolVersion | Mỗi interface khai báo phiên bản giao thức riêng, cho phép hỗ trợ đa phiên bản. |
| supportsAuthenticatedExtendedCard | capabilities.extendedAgentCard | Đã chuyển vào đối tượng capabilities; RPC đã được đổi tên thành GetExtendedAgentCard. |
| provider.name | provider.organization | Đổi tên để rõ ràng hơn. |
| capabilities.stateTransitionHistory | — removed | Không phải là một phần của v1.0; hãy mô hình hóa hành vi tương đương như một tiện ích mở rộng nếu cần. |
Mã mẫu
Đặt các interface này vào client, server, hoặc kiểm tra CI để phân tích và tạo Agent Card với an toàn kiểu. Chúng phản ánh các định nghĩa protobuf trong kho lưu trữ đặc tả chính thức, ở dạng JSON camelCase mà Agent Card được công bố.
Đang xây dựng Agent Card thủ công thay vào đó? Trình tạo sản xuất đúng dạng này.
// A2A v1.0 Agent Card — TypeScript definitions
export interface AgentCard {
name: string
description: string
supportedInterfaces: AgentInterface[]
provider?: AgentProvider
version: string
documentationUrl?: string
capabilities: AgentCapabilities
securitySchemes?: Record<string, SecurityScheme>
security?: Record<string, string[]>[]
defaultInputModes: string[]
defaultOutputModes: string[]
skills: AgentSkill[]
signatures?: AgentCardSignature[]
iconUrl?: string
}
export interface AgentInterface {
url: string
protocolBinding: 'JSONRPC' | 'GRPC' | 'HTTP+JSON' | (string & {})
protocolVersion: string
tenant?: string
}
export interface AgentProvider {
organization: string
url: string
}
export interface AgentCapabilities {
streaming?: boolean
pushNotifications?: boolean
extensions?: AgentExtension[]
extendedAgentCard?: boolean
}
export interface AgentExtension {
uri: string
description?: string
required?: boolean
params?: Record<string, unknown>
}
export interface AgentSkill {
id: string
name: string
description: string
tags: string[]
examples?: string[]
inputModes?: string[]
outputModes?: string[]
}
export interface AgentCardSignature {
protected: string
signature: string
header?: Record<string, unknown>
}
export type SecurityScheme =
| { apiKeySecurityScheme: { location: 'header' | 'query' | 'cookie'; name: string; description?: string } }
| { httpAuthSecurityScheme: { scheme: string; bearerFormat?: string; description?: string } }
| { oauth2SecurityScheme: { flows: Record<string, unknown>; oauth2MetadataUrl?: string; description?: string } }
| { openIdConnectSecurityScheme: { openIdConnectUrl: string; description?: string } }
| { mtlsSecurityScheme: Record<string, never> }Tính toàn vẹn
Vì Agent Card được lấy từ web mở, v1.0 chính thức hóa việc ký: Agent Card (trừ trường signatures và các giá trị mặc định) được chuẩn hóa bằng RFC 8785 JSON Canonicalization, sau đó được ký dưới dạng JWS. Client nên xác minh ít nhất một chữ ký — qua header kid/jku hoặc kho khóa đáng tin cậy — trước khi hành động dựa trên một Agent Card. Nhiều chữ ký hỗ trợ luân chuyển khóa.
Phục vụ Agent Card tại /.well-known/agent-card.json qua HTTPS.
Mọi mục supportedInterfaces đều có thể truy cập và nói đúng binding đã khai báo.
Skill có tag bắt buộc cùng mô tả với ranh giới tác vụ rõ ràng.
Các capability đã khai báo khớp với server — các tính năng không khai báo phải trả về lỗi, các tính năng đã khai báo phải hoạt động.
securitySchemes mô tả cách xác thực; không có thông tin xác thực nào xuất hiện ở bất kỳ đâu trong Agent Card.
version được tăng lên bất cứ khi nào nội dung Agent Card thay đổi.
Một agent hỗ trợ khách hàng với OAuth 2.0, streaming, và thông báo đẩy — tất cả các trường bắt buộc đều hiện diện. Có thêm nhiều mẫu trong thư viện ví dụ.
{
"name": "Agent Hỗ trợ Khách hàng",
"description": "Trả lời các câu hỏi hỗ trợ khách hàng, truy xuất bối cảnh đơn hàng và chuyển các vấn đề chưa được giải quyết lên nhóm con người.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/customer-support",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Ví dụ Inc.",
"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": "Giải quyết yêu cầu hỗ trợ khách hàng",
"description": "Phân loại yêu cầu hỗ trợ khách hàng, thu thập bối cảnh cần thiết, đề xuất giải pháp và chuyển lên cấp cao hơn khi độ tin cậy thấp.",
"tags": [
"support",
"orders",
"returns"
],
"examples": [
"Hãy giúp tôi trả lại đơn hàng của tôi."
]
}
],
"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"
]
}
]
}Câu hỏi thường gặp
Các thay đổi phiên bản, trường khám phá, và chi tiết xuất bản quyết định liệu một Agent Card có vượt qua đánh giá hay không.
v1.0 đã hợp nhất url, preferredTransport, và additionalInterfaces thành một mảng supportedInterfaces có thứ tự duy nhất, nơi mỗi mục khai báo url, protocolBinding, và protocolVersion riêng. supportsAuthenticatedExtendedCard đã chuyển sang capabilities.extendedAgentCard, provider.name trở thành provider.organization, tag skill trở thành bắt buộc, và chữ ký Agent Card JWS được chính thức hóa với chuẩn hóa RFC 8785.
Không. Agent Card là tài liệu khám phá cho một agent. Nó tóm tắt danh tính, interface, capability, skill, chế độ, nhà cung cấp, và metadata bảo mật, trong khi schema API đầy đủ mô tả các hình dạng yêu cầu và phản hồi chi tiết. Nó đóng vai trò mà một README hoặc tổng quan OpenAPI đóng cho một dịch vụ: đủ để quyết định có nên gọi nó hay không và gọi như thế nào.
name, description, supportedInterfaces, skills (có tag), defaultInputModes, defaultOutputModes, capabilities, provider, và metadata bảo mật. Hệ thống định tuyến khớp tác vụ với description và tag skill của bạn, sau đó sử dụng interface và capability để lập kế hoạch cuộc gọi thực tế.
Chỉ công bố các skill an toàn cho việc khám phá không xác thực. Nếu cần một Agent Card riêng tư phong phú hơn, hãy đặt capabilities.extendedAgentCard thành true và công khai các skill nhạy cảm thông qua thao tác GetExtendedAgentCard đã xác thực.
Tại URI well-known https://{tên-miền-của-bạn}/.well-known/agent-card.json, được phục vụ với loại nội dung application/a2a+json (application/json cũng hoạt động trong thực tế). Các triển khai trước đây sử dụng /.well-known/agent.json, vì vậy việc công bố cả hai trong giai đoạn chuyển đổi là một lựa chọn thực tế.
Áp dụng schema
Tạo một Agent Card có dạng v1.0 từ chi tiết dịch vụ của bạn, hoặc dán một Agent Card hiện có vào trình kiểm định để xem chính xác trường nào cần chú ý.