Phase 13: Tools & Protocols

A2A Phương pháp giao dịch giữa các đại lý

Type: Build

Languages: Python (stdlib, Agent Card + Task harness)

Prerequisites: Phase 13 · 06 (MCP fundamentals), Phase 13 · 08 (MCP client)

Time: ~75 minutes

Mục tiêu học tập

• Sự khác biệt giữa các trường hợp sử dụng từ đại lý đến công cụ (MCP) và các trường hợp sử dụng từ đại lý đến đại lý (A2A).
• Giới thiệu thẻ đại lý tại /.well-known/agent-card.jsoncó kỹ năng vàsupportedInterfacesMetadata.
• Đi theo vòng đời nhiệm vụ: TASK_STATE_SUBMITTED- TASK_STATE_WORKING- TASK_STATE_INPUT_REQUIRED, và các trạng thái cuối cùng TASK_STATE_COMPLETED- TASK_STATE_FAILED- TASK_STATE_CANCELED- TASK_STATE_REJECTED- Tôi không biết.
• Sử dụng Thông điệp có từng phần chứa một phần của text- raw- url, hoặcdata, và các tác phẩm tạo ra như các sản phẩm.

Vấn đề

Một đại lý dịch vụ khách hàng cần ủy quyền viết báo cáo cho một đại lý viết chuyên ngành.

• REST API tùy chỉnh, hoạt động nhưng mỗi cặp đều là một lần.
• Hình thức chia sẻ mã, yêu cầu hai đại lý chạy cùng một khung.
• MCP không phù hợp: MCP là để gọi công cụ, không phải cho hai đại lý hợp tác trong khi vẫn giữ cho lý luận nội bộ không rõ ràng của mỗi đại lý.

A2A lấp đầy khoảng trống. Nó mô hình hóa sự tương tác khi một đại lý gửi một Task đến một đại lý khác, với chu kỳ sống, tin nhắn và đồ tạo. trạng thái nội bộ của đại lý được gọi vẫn không minh bạch người gọi chỉ thấy chuyển đổi trạng thái nhiệm vụ và đầu ra cuối cùng.

A2A là giao thức "cho phép các đại lý trên các khung nói chuyện với nhau".

Khái niệm

Cảnh sát Thư

Mỗi đại lý tuân thủ A2A đều xuất bản một thẻ tại /.well-known/agent-card.json- Có thể là:

jsonCopy{
  "name": "research-agent",
  "description": "Summarizes academic papers and drafts citations.",
  "version": "1.2.0",
  "supportedInterfaces": [
    {
      "url": "https:TOK0
      "protocolBinding": "JSONRPC",
      "protocolVersion": "1.0"
    }
  ],
  "capabilities": {"streaming": true, "pushNotifications": true},
  "securitySchemes": {
    "bearer": {"httpAuthSecurityScheme": {"scheme": "Bearer"}}
  },
  "securityRequirements": [{"schemes": {"bearer": {"list": []}}}],
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/markdown"],
  "skills": [
    {
      "id": "summarize_paper",
      "name": "Summarize a paper",
      "description": "Read a paper PDF and produce a 3-paragraph summary.",
      "tags": ["research", "summarization"],
      "inputModes": ["text/plain", "application/pdf"],
      "outputModes": ["text/markdown"]
    }
  ]
}

Khám phá dựa trên URL: lấy thẻ, chọn thẻ đầu tiên supportedInterfacesmục có protocolBindingkhách hàng của bạn nói, và liệt kê kỹ năng.

Thẻ đại lý đã ký

Một thẻ có thể mang theo một signaturesmỗi mục là một JWS (RFC 7515) được tính trên thẻ RFC 8785 JSON, với signaturesngười tiêu dùng canonicalize thẻ theo cùng một cách và xác minh. ngăn chặn giả mạo.

Chuyển đời của nhiệm vụ

textCopyTASK_STATE_SUBMITTED
  -> TASK_STATE_WORKING
  -> TASK_STATE_COMPLETED | TASK_STATE_FAILED | TASK_STATE_CANCELED | TASK_STATE_REJECTED

TASK_STATE_WORKING
  -> TASK_STATE_INPUT_REQUIRED
  -> TASK_STATE_WORKING (the client sends a message with the same taskId)

Khách hàng bắt đầu với SendMessage, và máy chủ tạo Task. người gọi là đại lý chuyển qua các trạng thái; khách hàng thăm dò với GetTaskhoặc chảy qua SSE với SendStreamingMessagevà SubscribeToTaskMột dòng chảy mang theostatusUpdatevà artifactUpdatecác sự kiện và kết thúc khi nhiệm vụ đạt đến trạng thái cuối cùng.finalcờ.

Thông điệp và phần

Một tin nhắn có một messageId, một role(ROLE_USERhoặc ROLE_AGENT), và một hoặc nhiều phần. Mỗi phần chứa chính xác một trường nội dung, và tên trường đó là loại. Không có kindtrường.

• text: nội dung đơn giản.
• raw: file bytes, base64 trong JSON, thường với filenamevà mediaType- Tôi không biết.
• url: một liên kết đến nội dung tập tin.
• data: tải trọng hữu ích JSON có cấu trúc (truyền nhập có cấu trúc cho đại lý được gọi).

Ví dụ:

jsonCopy{
  "messageId": "msg-001",
  "role": "ROLE_USER",
  "parts": [
    {"text": "Summarize this paper."},
    {"raw": "...", "filename": "paper.pdf", "mediaType": "application/pdf"},
    {"data": {"targetLength": "3 paragraphs"}, "mediaType": "application/json"}
  ]
}

Các đồ tạo tác

Các sản phẩm là các sản phẩm, không phải chuỗi nguyên liệu. Một sản phẩm là một sản phẩm có tên, được gõ:

jsonCopy{
  "artifactId": "art-001",
  "name": "summary",
  "parts": [{"text": "...", "mediaType": "text/markdown"}]
}

Các đồ tạo vật có thể được chuyển qua các mảnh.artifactUpdateSự kiện mang theo đồ tạo vật cộng với appendvà lastChunkNgười gọi sẽ tích lũy.

Ba giao thức liên kết

1. JSON-RPC 2.0 over HTTP(JSONRPC). POST cho các yêu cầu, SSE cho phát trực tuyến.SendMessage- SendStreamingMessage- GetTask- ListTasks- CancelTask- SubscribeToTask- CreateTaskPushNotificationConfig- GetTaskPushNotificationConfig- ListTaskPushNotificationConfigs- DeleteTaskPushNotificationConfig, vàGetExtendedAgentCard- Tôi không biết.
2. gRPC(GRPC(c) Đối với môi trường doanh nghiệp nơi gRPC là bản địa.
3. HTTP+JSON/REST(HTTP+JSON). Các URL tài nguyên như POST /message:sendvà GET /tasks/{id}- Tôi không biết.

Cả ba liên kết đều có cùng mô hình dữ liệu.supportedInterfacestên mục một liên kết và của nó protocolVersionKhách hàng gửi tiêu đềA2A-Version: 1.0trên mỗi yêu cầu, bởi vì một máy chủ đọc một yêu cầu mà không có nó như phiên bản 0.3.

httpCopyPOST /a2a HTTP/1.1
Host: research.example.com
Content-Type: application/json
A2A-Version: 1.0

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "msg-001",
      "role": "ROLE_USER",
      "parts": [{"text": "Summarize this paper."}]
    }
  }
}

Bảo tồn độ trống

Một nguyên tắc thiết kế chính: trạng thái nội bộ của đại lý được gọi là không minh bạch. Người gọi thấy trạng thái nhiệm vụ và các vật liệu. Dòng tư tưởng của đại lý được gọi, các cuộc gọi công cụ của nó, đại diện phụ của nó tất cả đều vô hình. Điều này khác với MCP, nơi các cuộc gọi công cụ là minh bạch.

Lý luận: A2A cho phép các đối thủ cạnh tranh hợp tác mà không tiết lộ nội bộ. A2A có thể là "hãy gọi cho đại lý dịch vụ khách hàng này" mà không cần người gọi học cách đại lý đó thực hiện dịch vụ.

Thời gian

• 2025-04-09.Google công bố A2A.
• 2025-06-23.Được tặng cho Linux Foundation.
• 2025-08.Thuốc ACP của IBM.
• 2025-09.Tàu mở rộng AP2 (Giá nhân viên).
• 2026-04.v1.0 được phát hành với 150+ tổ chức hỗ trợ.

Mối quan hệ với MCP

Sử dụng MCP khi bạn muốn gọi một công cụ cụ thể. Sử dụng A2A khi bạn muốn ủy thác toàn bộ nhiệm vụ cho một đại lý khác. Nhiều hệ thống sản xuất sử dụng cả hai: một đại lý sử dụng MCP cho lớp công cụ của mình và A2A cho lớp hợp tác của mình.

Sử dụng nó

code/main.pythực hiện một vòng A2A tối thiểu: đại lý viết xuất bản thẻ của mình, đại lý nghiên cứu gửi nó một SendMessageyêu cầu với một phần PDF và một hướng dẫn văn bản, và nhiệm vụ di chuyển qua TASK_STATE_WORKING→ TASK_STATE_INPUT_REQUIRED→ TASK_STATE_WORKING→ TASK_STATE_COMPLETEDtrước khi trả lại một vật liệu văn bản. Tất cả stdlib; sử dụng một di chuyển trong bộ nhớ để tập trung vào hình dạng tin nhắn.

Những gì cần xem:

• Hình dạng JSON của thẻ đại lý.
• Đề xuất ID nhiệm vụ bên máy chủ và chuyển đổi trạng thái.
• Các phần được đánh dấu bởi các trường nội dung hiện diện.
• TASK_STATE_INPUT_REQUIREDLớp giữa nhiệm vụ.
• Các vật liệu sẽ được trả về khi hoàn thành.

Chuyển nó

Bài học này sẽ mang lại kết quả outputs/skill-a2a-agent-spec.mdVới một đại lý mới mà nên được gọi bởi các đại lý khác, kỹ năng tạo ra thẻ đại lý JSON, kế hoạch kỹ năng và bản phác thảo điểm cuối.

Các bài tập

1. Đi chạycode/main.py. Theo dõi toàn bộ chu kỳ đời của nhiệm vụ, bao gồm cả TASK_STATE_INPUT_REQUIREDdừng lại khi đại lý gọi yêu cầu giải thích.

1. Thêm thẻ đại lý ký tên, thêm một mục JWS vào.signaturesvới algđược thiết lậpHS256, ký kết JSON của thẻ không có signaturesviết một xác minh và xác nhận nó thất bại trên một thẻ đột biến.

1. Thực hiện các nhiệm vụ streaming với SendStreamingMessage: đại lý viết phát task, ba artifactUpdatecác mảnh, và một statusUpdatevới TASK_STATE_COMPLETEDNgười gọi sẽ tích lũy các mảnh.

1. Thiết kế một đại lý A2A bao gồm một máy chủ MCP. Bản đồ mỗi công cụ MCP để một kỹ năng A2A. Lưu ý các sự thỏa hiệp bất độ sáng bị mất?

1. Đọc thông báo A2A v1.0 và xác định một tính năng chưa được thực hiện bởi bất kỳ khung nào vào tháng 4 năm 2026. (Thông dụ: nó liên quan đến ủy quyền nhiệm vụ đa hop).

Các điều khoản chính

Đọc thêm

• a2a-protocol.org Cấu chỉ A2A
• a2aproject/A2A — GitHub Các thực hiện và SDK tham chiếu
• A2A v1.0.1 release: các thẻ docs/specification.mdvà quy định specification/a2a.protoBài học này tiếp theo
• Linux Foundation — A2A launch press release Tháng 6 năm 2025 chuyển giao quản trị
• Google Cloud — A2A protocol upgrade Bản đồ đường và động lực của đối tác
• Google Dev — A2A 1.0 milestone v1.0 thông báo phát hành và hướng dẫn ngược

This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.

Browse the complete course catalog or open this lesson on GitHub.