Agent2Agent プロトコル（A2A）テクニカル・ドキュメント（日本語訳まとめ）

原文：https://google.github.io/A2A/#/documentation

Agent2Agent プロトコル（A2A）

不透明なエージェントシステム間の相互運用性を可能にするオープンプロトコル

1. はじめに

1.1 フィードバックと変更

A2Aは進行中の仕様であり、コミュニティからのフィードバックに基づいて変更されることが想定されています。このリポジトリには初期の仕様、ドキュメント、サンプルコード（sample code）が含まれています。新機能や追加例、仕様、ライブラリが利用可能になり次第、順次更新していきます。仕様とサンプルが本番品質のSDKとして成熟した段階で、バージョン1.0を宣言し、安定版リリースを維持します。

1.2 重要原則

• シンプル: 既存の標準を再利用

• Enterprise Ready: 認証、セキュリティ、プライバシー、トレース、モニタリング対応

• 非同期優先: 長時間実行タスクや人間の介入を含むタスクをサポート

• モダリティ非依存: テキスト、オーディオ/ビデオ、フォーム、iframe などに対応

• ブラックボックス実行: エージェントは内部の思考や計画、ツールを共有する必要がない

1.3 詳細な議論トピック

• A2AとMCP（A2A and MCP）

• Enterprise Ready（Enterprise Ready）

• プッシュ通知（Push Notifications）

• エージェント発見（Agent Discovery）

2. 概要

2.1 アクター

• ユーザー: タスクを達成するためにエージェントシステムを利用する人間またはサービス

• クライアント: ユーザーに代わりアクションを要求するサービス、エージェント、アプリケーション

• リモートエージェント（サーバー）: A2Aサーバーとして動作するブラックボックス型エージェント

2.2 トランスポート

通信にはHTTPを使用し、必要に応じてステータス更新受信用にSSE（Server-Sent Events）を活用します。

2.3 データ形式

クライアントとリモートエージェント間のデータ交換にはJSON-RPC 2.0を使用します。

2.4 非同期処理

ポーリング、SSE、プッシュ通知によりタスク進捗の非同期更新が可能です。

3. 認証と認可

• OpenAPI認証仕様に準拠（OpenAPI’s Authentication specification ）

• 認証情報（トークンなど）はHTTPヘッダーで送信

• サーバーはAgent Card（ Agent Card）で認証要件を公開

• タスク実行中に追加認証が必要な場合は”input-required”で通知

4. エージェントカード

4.1 発見（Discovery）

通常、エージェントはhttps://<base URL>/.well-known/agent.jsonでAgent Cardを公開します。

4.2 表現（Representation）

interface AgentCard {
  name: string;
  description: string;
  url: string;
  provider?: { organization: string; url: string; };
  version: string;
  documentationUrl?: string;
  capabilities: {
    streaming?: boolean;
    pushNotifications?: boolean;
    stateTransitionHistory?: boolean;
  };
  authentication: {
    schemes: string[];
    credentials?: string;
  };
  defaultInputModes: string[];
  defaultOutputModes: string[];
  skills: {
    id: string;
    name: string;
    description: string;
    tags: string[];
    examples?: string[];
    inputModes?: string[];
    outputModes?: string[];
  }[];
}

5. エージェント間通信

クライアントとリモートエージェントはTaskオブジェクトを介してタスクを完了させます。進捗更新にはポーリング、SSE、プッシュ通知が利用可能です。

6. コアオブジェクト

6.1 Task

interface Task {
  id: string;
  sessionId: string;
  status: TaskStatus;
  history?: Message[];
  artifacts?: Artifact[];
  metadata?: Record<string, any>;
}

interface TaskStatus {
  state: TaskState;
  message?: Message;
  timestamp?: string;
}

type TaskState =
  | "submitted"
  | "working"
  | "input-required"
  | "completed"
  | "canceled"
  | "failed"
  | "unknown";

6.2 Artifact

interface Artifact {
  name?: string;
  description?: string;
  parts: Part[];
  metadata?: Record<string, any>;
  index: number;
  append?: boolean;
  lastChunk?: boolean;
}

6.3 Message

interface Message {
  role: "user" | "agent";
  parts: Part[];
  metadata?: Record<string, any>;
}

6.4 Part

interface TextPart {
  type: "text";
  text: string;
}
interface FilePart {
  type: "file";
  file: {
    name?: string;
    mimeType?: string;
    bytes?: string;
    uri?: string;
  };
}
interface DataPart {
  type: "data";
  data: Record<string, any>;
}

type Part = (TextPart | FilePart | DataPart) & { metadata: Record<string, any> };

7. プッシュ通知

interface PushNotificationConfig {
  url: string;
  token?: string;
  authentication?: {
    schemes: string[];
    credentials?: string;
  };
}

interface TaskPushNotificationConfig {
  id: string;
  pushNotificationConfig: PushNotificationConfig;
}

8. エラー処理

interface ErrorMessage {
  code: number;
  message: string;
  data?: any;
}