2
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kai_kou(甲斐 甲)

A2A Protocol v1.0移行ガイド — Signed Cards・マルチテナント・gRPCをPythonで実装

2
Last updated at Posted at 2026-04-05

はじめに

2026年3月12日、AIエージェント間通信の標準プロトコルである A2A（Agent2Agent）Protocol の v1.0.0 が正式リリースされました。

A2AはもともとGoogleが2025年4月に発表し、同年6月23日にLinux Foundationへ寄贈されたオープン標準です。現在はAWS、Cisco、Google、IBM Research、Microsoft、Salesforce、SAP、ServiceNowの8社によるテクニカルステアリングコミッティー（TSC）が管理し、100社以上が対応を表明しています。

v1.0ではv0.3から 複数の破壊的変更 が導入されており、既存コードの移行が必要です。本記事では、v1.0の新機能と、v0.3からのPython SDK移行手順を公式ドキュメントに基づいて解説します。

この記事で学べること

  • A2A Protocol v1.0の主要新機能
  • v0.3からの破壊的変更と対処法
  • Python SDKの移行手順（コード例付き）
  • Signed Agent Cards（暗号署名）の実装方法

前提条件

TL;DR

  • v1.0.0 が2026年3月12日リリース。v0.3からの移行が必要
  • Signed Agent Cards（JWS署名）で組織間エージェントIDを暗号検証可能に
  • マルチテナント 対応で1エンドポイントから複数テナントを管理
  • Enum値が SCREAMING_SNAKE_CASE に統一（例："submitted" → "TASK_STATE_SUBMITTED"）
  • gRPC・JSON-RPC・RESTの3トランスポートが仕様として正式定義

A2A Protocol v1.0 の主な新機能

1. Signed Agent Cards（エージェントカード署名）

v1.0の最大の新機能です。エージェントのID情報を記述するAgent CardをJWS（JSON Web Signature、RFC 7515）で署名し、JSON Canonicalization（RFC 8785）で正規化することで、組織境界をまたいだエージェントIDの暗号検証 が可能になりました。

Signed Agent Cardの仕様は agent-card.json に次のように記述されます1：

{
  "name": "my-agent",
  "version": "1.0.0",
  "url": "https://my-agent.example.com/a2a",
  "protocolVersions": ["1.0", "0.3"],
  "capabilities": { "streaming": true },
  "skills": [
    {
      "id": "data-analysis",
      "name": "Data Analysis",
      "description": "Analyzes structured data"
    }
  ],
  "securitySchemes": {
    "oauth2": {
      "type": "oauth2",
      "flows": {
        "authorizationCode": {
          "authorizationUrl": "https://auth.example.com/authorize",
          "tokenUrl": "https://auth.example.com/token",
          "scopes": { "a2a:read": "Read access" }
        }
      }
    }
  }
}

Python SDK（v1.0.0-alpha.0）では AgentCard モデルがProtoベース型に移行しています。最新のAPIは公式リリースノートを参照してください。

Python SDK v1.0.0はアルファ版のため、APIは変更される可能性があります。本番環境では安定版（v0.3.25）の利用を推奨します。

署名検証により、マルウェア化したエージェントや偽装エージェントからのリクエストを拒否 できます。エンタープライズ向けマルチエージェントシステムでの採用が想定されています。

2. ネイティブマルチテナントサポート

リクエストに tenant フィールドが追加され、1つのエンドポイントから複数テナントを処理 できるようになりました。

from a2a.types import TaskSendParams, MessageSendParams

# v1.0: tenantフィールドを指定
params = TaskSendParams(
    message=MessageSendParams(
        role="user",
        parts=[{"kind": "text", "text": "データを分析してください"}],
    ),
    tenant="tenant-abc-123",  # 新規追加フィールド
)

マルチテナントSaaSやエンタープライズ向けの展開で、テナントごとにエージェントを分離できます。

3. tasks/list メソッド（カーソルベースのページネーション）

エージェントが保持するタスク一覧をページネーション付きで取得できる tasks/list メソッドが追加されました。

# tasks/list の呼び出し例（仕様ベース）
# JSON-RPCリクエスト
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tasks/list",
  "params": {
    "pageSize": 20,
    "cursor": null  # 次ページのカーソル（初回はnull）
  }
}

# レスポンス
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tasks": [
      {
        "id": "task-001",
        "state": "TASK_STATE_COMPLETED",
        "createdAt": "2026-03-15T10:30:00.123Z",
        "lastModified": "2026-03-15T10:31:05.456Z"
      }
    ],
    "nextCursor": "eyJwYWdlIjogMn0="
  }
}

長期実行タスクの一覧管理やダッシュボード機能の実装が容易になります。

4. OAuth 2.0 セキュリティ強化

OAuth 2.0の対応グラントが整理され、セキュリティが向上しました。

グラント v0.3 v1.0
Authorization Code（PKCE付き） ✓ ✓
Device Code（RFC 8628） - ✓ 追加
Client Credentials ✓ ✓
Implicit Grant ✓ ✗ 廃止
Password Grant ✓ ✗ 廃止

Implicit GrantとPassword Grantはセキュリティリスクのため廃止されています。既存コードを使用している場合は移行が必要です。

5. 3つのトランスポートバインディングの正式定義

v1.0では JSON-RPC・gRPC・REST の3つのトランスポートプロトコルが仕様として正式に定義されました。a2a.proto がプロトコルの規範的ソースオブトゥルースとなり、スキーマ定義の一元管理が実現しています。

トランスポート 特徴 推奨ユースケース
JSON-RPC シンプル、広く対応 Webアプリ、汎用API
gRPC 高スループット、型安全 マイクロサービス、内部通信
REST（HTTP+JSON） 標準的、キャッシュ対応 パブリックAPI、既存インフラ

v0.3からの破壊的変更

変更1：Enum値が SCREAMING_SNAKE_CASE に統一

タスク状態などのEnum値の表現が変更されました。

// v0.3（旧）— kebab-case / lowercase
task.status.state === "completed"   // タスク状態
message.role === "user"             // メッセージロール

// v1.0（新）— SCREAMING_SNAKE_CASE
task.status.state === "TASK_STATE_COMPLETED"
message.role === "ROLE_USER"

主要なEnum値の対応表：

v0.3 v1.0
"submitted" "TASK_STATE_SUBMITTED"
"working" "TASK_STATE_WORKING"
"completed" "TASK_STATE_COMPLETED"
"failed" "TASK_STATE_FAILED"
"user" "ROLE_USER"
"agent" "ROLE_AGENT"

文字列リテラルで比較しているコードはすべて更新が必要です。

変更2：Part 型の統合とmember-based polymorphism

v0.3では TextPart、FilePart、DataPart として分かれていた型が、v1.0では Part 型に統合されました。さらに、v1.0では kind ディスクリミネータフィールドが 廃止 され、member-based polymorphism（どのフィールドが存在するかで型を判別）に変更されています2。

// v0.3.x — "kind" フィールドで型を判別
if (part.kind === "text") return part.text;
if (part.kind === "file") return part.file.bytes;

// v1.0 — "kind" フィールド廃止。フィールドの存在で判別
if ("text" in part) return part.text;
if ("file" in part) return part.file.bytes;

JSON仕様レベルでのPart表現も変わります：

// v0.3（旧）
{"kind": "text", "text": "解析してください"}
{"kind": "file", "file": {"bytes": "...", "mimeType": "application/json"}}

// v1.0（新）— kindフィールドなし
{"text": "解析してください"}
{"file": {"bytes": "...", "mimeType": "application/json"}}

Python SDK（v1.0.0-alpha.0）の型APIは現在アルファ版のため、安定版リリース後に確認してください。

変更3：タスクへのタイムスタンプ追加

タスクオブジェクトに createdAt と lastModified フィールドが追加されました（ISO 8601 UTC、ミリ秒精度）。

# v1.0でアクセス可能
print(task.createdAt)    # 例: "2026-03-15T10:30:00.123Z"
print(task.lastModified) # 例: "2026-03-15T10:31:05.456Z"

Python SDK v1.0 への移行手順

ステップ1：パッケージのアップグレード

# 安定版（v0.3.x系）
pip install a2a-sdk==0.3.25

# v1.0対応版（アルファ）
pip install a2a-sdk==1.0.0a0

公式の移行ガイドラインによると、v1.0.0-alpha.0はA2A 1.0仕様へのアップグレードを含み、Protoベース型への移行、トランスポート非依存インターセプター、gRPC・JSON-RPC・REST全体にわたるテナントコンテキスト伝播が含まれています3。

ステップ2：クライアント側の移行

v0.3とv1.0の主な差異を概念的に示します（Python SDK v1.0.0 安定版リリース後に正確なAPIを確認してください）。

# v0.3（旧）— TextPart/FilePart等の個別型
from a2a.client import A2AClient
from a2a.types import TextPart  # 個別の型クラス

client = A2AClient(base_url="https://my-agent.example.com/a2a")
# TextPartで構築
parts = [TextPart(text="解析してください")]

# v1.0（新）— 統合されたPart型、tenantフィールド、ROLE_USERのenum値
# メッセージのJSON表現（仕様ベース）:
# {
#   "role": "ROLE_USER",      ← v0.3は "user"
#   "parts": [
#     {"text": "解析してください"}  ← "kind"フィールドなし
#   ],
#   "tenant": "default"       ← 新規フィールド
# }

Python SDK v1.0.0-alpha.0はプレリリースです。本番移行は公式リリースノートで安定版の公開を確認してから実施することを推奨します。

ステップ3：後方互換性の確認

v1.0のAgentCardはv0.3との後方互換性をサポートしており、段階的な移行が可能です。サーバー側でv1.0とv0.3の両方をアドバタイズすることで、クライアントを一度に移行しなくても対応できます。

{
  "protocolVersions": ["1.0", "0.3"],
  "name": "my-agent",
  "url": "https://my-agent.example.com/a2a"
}

まとめ

A2A Protocol v1.0は、マルチエージェントシステムを本番運用するための重要な機能強化を提供しています。

  • Signed Agent Cards でエージェントIDの暗号検証が実現、なりすまし攻撃への対策が可能
  • マルチテナント 対応でSaaS・エンタープライズ向け展開が効率化
  • Enum統一・Part型統合 など型安全性が向上
  • gRPC正式サポート でハイスループット要件に対応

Python SDKのv1.0対応安定版（v1.0.0 stable）は近日リリース予定です。現時点では安定版のv0.3.25を本番で使用しつつ、v1.0.0-alpha.0で動作確認を進めておくことが推奨されます。

A2Aとの組み合わせで広く使われているMCP（Model Context Protocol）側のアップデートと合わせて、マルチエージェントシステムのアーキテクチャを継続的に見直していきましょう。

参考リンク

  1. A2A Protocol v1.0 仕様 - AgentCard（公式仕様） ↩

  2. What's New in v1.0 - Part Type Unification（member-based polymorphism への移行） ↩

  3. a2a-python Releases - a2aproject/a2a-python（v1.0.0a0 は2026年3月17日リリース） ↩

2
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
2
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?