6 mẫu JSON sẵn sàng sao chép · A2A v1.0

Ví dụ A2A Agent Card

Duyệt các mẫu A2A v1.0 thực tế, hiểu các quyết định thiết kế của chúng, sau đó điều chỉnh bất kỳ ví dụ nào cho agent của riêng bạn.

Khám phá agent công khai

Sử dụng các ví dụ này để định hình JSON mà một client A2A khác lấy trước khi quyết định liệu agent của bạn có thể hoàn thành một nhiệm vụ hay không.

Gửi lên marketplace

Điều chỉnh provider, skill, tag, capability, và metadata bảo mật để người đánh giá hiểu agent làm gì và ai vận hành nó.

Danh mục agent nội bộ

Chuẩn hóa mô tả endpoint, xác thực, và skill giữa các agent nội bộ trước khi các đội tích hợp chúng vào quy trình làm việc.

Mẫu JSON

Agent Card mẫu cho agent hỗ trợ, đặt chỗ, mua sắm, lập trình, nghiên cứu, và quy trình làm việc.

Xác thực một mẫu
Lọc

Agent Hỗ trợ Khách hàng

Xử lý câu hỏi về sản phẩm, tra cứu đơn hàng, hoàn trả, và chuyển giao khi cần leo thang.

Tại sao nó được xây dựng như vậy

  • Thông tin xác thực client OAuth 2.0 bảo vệ dữ liệu đơn hàng: Agent Card khai báo URL token và scope để client có thể xác thực mà không cần tài liệu ngoài băng tần.
  • streaming và pushNotifications đều là true vì các cuộc trò chuyện hỗ trợ kéo dài và cập nhật giải quyết đến không đồng bộ.
  • Skill duy nhất được giới hạn trong một ranh giới tác vụ (phân loại, giải quyết, leo thang) thay vì mô tả mơ hồ "giúp đỡ khách hàng", để router có thể khớp chính xác.
customer-support.json
{
  "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"
      ]
    }
  ]
}

Agent Đặt chỗ

Tìm các khung giờ hẹn có sẵn và chuẩn bị xác nhận đặt chỗ.

Tại sao nó được xây dựng như vậy

  • Một khóa API trong header là đủ ở đây: đặt chỗ có phạm vi theo tenant nhưng không mang vấn đề đồng ý ủy quyền người dùng mà OAuth giải quyết.
  • defaultOutputModes chỉ có application/json, báo hiệu rằng người gọi nhận được đề xuất đặt chỗ có cấu trúc thay vì văn xuôi.
  • pushNotifications là true để agent có thể xác nhận đặt chỗ sau khi backend giữ chỗ ổn định, mà không cần client thăm dò.
booking.json
{
  "name": "Agent Đặt chỗ",
  "description": "Tìm kiếm tình trạng phòng trống, đề xuất các lựa chọn đặt chỗ và chuẩn bị đặt chỗ cuộc hẹn để phê duyệt.",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/booking",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "Ví dụ Inc.",
    "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": "Tìm và chuẩn bị đặt chỗ",
      "description": "Kiểm tra tính khả dụng của tài nguyên, so sánh thời lượng đặt trước và trả về đề xuất đặt trước có cấu trúc.",
      "tags": [
        "booking",
        "calendar",
        "availability"
      ],
      "examples": [
        "Tìm một cuộc hẹn 30 phút vào chiều mai."
      ]
    }
  ],
  "securitySchemes": {
    "apiKey": {
      "apiKeySecurityScheme": {
        "location": "header",
        "name": "X-API-Key"
      }
    }
  },
  "security": [
    {
      "apiKey": []
    }
  ]
}

Agent Mua sắm

So sánh sản phẩm, tình trạng còn hàng, giá cả, và ràng buộc mua hàng.

Tại sao nó được xây dựng như vậy

  • Các đề xuất được xếp hạng truyền trực tiếp khi chúng được tính toán, vì vậy streaming là true trong khi pushNotifications vẫn là false — không có gì xảy ra sau khi phản hồi hoàn tất.
  • Mô tả skill cam kết trả về sự đánh đổi và lý do, điều này cho các bộ điều phối biết rằng agent này giải thích xếp hạng thay vì chỉ liệt kê sản phẩm.
  • Các scope OAuth kiểm soát dữ liệu liên quan đến mua hàng; một bản demo mua sắm công khai có thể bỏ hoàn toàn bảo mật và vẫn là một Agent Card hợp lệ.
shopping.json
{
  "name": "Agent Mua sắm",
  "description": "So sánh các sản phẩm với các ràng buộc của người dùng và trả về các tùy chọn mua hàng được xếp hạng với sự đánh đổi.",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/shopping",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "Ví dụ Inc.",
    "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": "So sánh các lựa chọn mua sắm",
      "description": "Đánh giá các sản phẩm ứng viên, lọc theo ràng buộc và trả về các đề xuất được xếp hạng có lý do căn bản.",
      "tags": [
        "shopping",
        "commerce",
        "recommendations"
      ],
      "examples": [
        "So sánh máy tính xách tay nhẹ dưới 1.200 USD."
      ]
    }
  ],
  "securitySchemes": {
    "oauth2": {
      "oauth2SecurityScheme": {
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://api.example.com/a2a/shopping/oauth/token",
            "scopes": {
              "agent.invoke": "Invoke agent skills"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "oauth2": [
        "agent.invoke"
      ]
    }
  ]
}

Agent Lập trình

Xem xét các tác vụ code, đề xuất bản vá, và giải thích các quyết định triển khai.

Tại sao nó được xây dựng như vậy

  • extendedAgentCard là true: Agent Card công khai liệt kê một skill chung "thực hiện thay đổi code", trong khi các skill riêng cho từng repository chỉ được tiết lộ cho client đã xác thực thông qua GetExtendedAgentCard.
  • Cả đầu ra text/plain và application/json đều được khai báo vì agent trả về giải thích dễ đọc cho con người cùng với các bản vá có thể áp dụng bằng máy.
  • Streaming quan trọng đối với các vòng lặp biên dịch và kiểm thử dài; client thấy tiến trình trung gian thay vì một lệnh gọi im lặng kéo dài nhiều phút.
coding.json
{
  "name": "Agent Lập trình",
  "description": "Hỗ trợ các nhiệm vụ kỹ thuật phần mềm bằng cách phân tích mã, đề xuất thay đổi và gửi lại các ghi chú triển khai.",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/coding",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "Ví dụ Inc.",
    "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": "Thực hiện thay đổi mã",
      "description": "Đọc yêu cầu mã hóa, kiểm tra các tệp có liên quan, trả về đề xuất bản vá và tóm tắt các bước xác minh.",
      "tags": [
        "coding",
        "review",
        "patches"
      ],
      "examples": [
        "Thêm phân trang vào API người dùng."
      ]
    }
  ],
  "securitySchemes": {
    "apiKey": {
      "apiKeySecurityScheme": {
        "location": "header",
        "name": "X-API-Key"
      }
    }
  },
  "security": [
    {
      "apiKey": []
    }
  ]
}

Agent Nghiên cứu

Thu thập nguồn, trích xuất bằng chứng, và trả về ghi chú nghiên cứu có cấu trúc.

Tại sao nó được xây dựng như vậy

  • Hoàn toàn không có securitySchemes: endpoint được cố ý công khai, và việc bỏ qua trường này là cách đúng để nói điều đó — một bản đồ scheme trống sẽ mơ hồ.
  • Đầu vào chỉ là text/plain, vì các bản tóm tắt nghiên cứu bắt đầu từ các câu hỏi bằng ngôn ngữ tự nhiên; đầu ra có cấu trúc đến dưới dạng ghi chú application/json.
  • Đây là Agent Card v1.0 hữu ích tối thiểu: danh tính, một interface, capability, chế độ, và một skill được gắn tag tốt.
research.json
{
  "name": "Agent Nghiên cứu",
  "description": "Thu thập tài liệu nguồn, trích xuất bằng chứng và tạo ra các ghi chú nghiên cứu có cấu trúc kèm theo các trích dẫn.",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/research",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "Ví dụ Inc.",
    "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": "Chuẩn bị tóm tắt nghiên cứu",
      "description": "Tìm kiếm các nguồn đã được phê duyệt, trích xuất các tuyên bố và bằng chứng, đồng thời trả về bản tóm tắt nghiên cứu ngắn gọn.",
      "tags": [
        "research",
        "evidence",
        "citations"
      ],
      "examples": [
        "Chuẩn bị một bản tóm tắt được trích dẫn về chính sách năng lượng tái tạo."
      ]
    }
  ]
}

Agent Quy trình Làm việc Nội bộ

Điều phối phê duyệt, kiểm tra trạng thái, và cập nhật quy trình làm việc văn phòng.

Tại sao nó được xây dựng như vậy

  • application/json là chế độ đầu vào và đầu ra duy nhất: agent này được gọi bởi các hệ thống khác, không bao giờ bởi người gõ văn xuôi.
  • OAuth 2.0 cộng với extendedAgentCard phù hợp với kiểm toán doanh nghiệp — đội bảo mật có thể thấy công khai các yêu cầu xác thực trong khi các skill quy trình làm việc nhạy cảm vẫn nằm sau xác thực.
  • pushNotifications là thiết yếu vì chuỗi phê duyệt mất hàng giờ hoặc hàng ngày; webhook thay thế thăm dò cho các thay đổi trạng thái.
internal-workflow.json
{
  "name": "Agent Quy trình Làm việc Nội bộ",
  "description": "Điều phối các phê duyệt nội bộ, kiểm tra trạng thái hệ thống và chuẩn bị cập nhật quy trình làm việc cho các nhóm vận hành.",
  "supportedInterfaces": [
    {
      "url": "https://api.example.com/a2a/workflow",
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "Ví dụ Inc.",
    "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": "Điều phối quy trình làm việc nội bộ",
      "description": "Nhận ý định của quy trình làm việc, kiểm tra các yêu cầu chính sách, thu thập phê duyệt và báo cáo trạng thái cuối cùng.",
      "tags": [
        "workflow",
        "operations",
        "approval"
      ],
      "examples": [
        "Yêu cầu phê duyệt để triển khai bản cập nhật bảng lương."
      ]
    }
  ],
  "securitySchemes": {
    "oauth2": {
      "oauth2SecurityScheme": {
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://api.example.com/a2a/workflow/oauth/token",
            "scopes": {
              "agent.invoke": "Invoke agent skills"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "oauth2": [
        "agent.invoke"
      ]
    }
  ]
}

Điều chỉnh một cách tự tin

Cách điều chỉnh một ví dụ Agent Card

Mỗi ví dụ Agent Card được cố ý hoàn chỉnh đủ để sao chép, nhưng Agent Card không nên được xuất bản mà không thay đổi. Hãy coi nó như một bản đồ trường cho server A2A của riêng bạn: thay thế danh tính, endpoint, provider, xác thực, capability, chế độ, và chi tiết skill bằng giá trị production.

Các Agent Card mạnh nhất giải thích ranh giới tác vụ của agent bằng cả ngôn ngữ đơn giản và metadata máy có thể đọc được. Một client nên có thể biết agent có thể làm gì, không thể làm gì, cần gọi URL nào, và có cần thông tin xác thực hay không.

Trước khi xuất bản

Thay thế mọi URL example.com bằng endpoint A2A đã triển khai và trang web provider của bạn.

Viết lại tên skill, mô tả, tag (bắt buộc trong v1.0), và ví dụ cho ranh giới tác vụ thực tế.

Đặt provider.organization và tăng version cấp cao nhất bất cứ khi nào nội dung Agent Card thay đổi.

Chỉ xóa các trường xác thực khi endpoint được cố ý công khai.

Giữ defaultInputModes và defaultOutputModes phù hợp với những gì server của bạn thực sự chấp nhận và trả về.

Xác thực JSON cuối cùng và xuất bản nó tại /.well-known/agent-card.json trên tên miền dịch vụ của bạn.

Sẵn sàng xây dựng

Bắt đầu với một ví dụ, sau đó biến nó thành của riêng bạn.

Mở bất kỳ mẫu nào trong Trình tạo Agent Card, xem lại JSON, và xác thực nó trước khi xuất bản.