A2A レスポンス抽出

​

A2A の上の AdCP 慣例

• 単一アーティファクト不変条件。 AdCP タスクはすべての出力パーツを含む 1 つのアーティファクトを生成する。クライアントは artifacts[0] から読む。セラーが複数の distinct な成果物を必要とする場合、複数のアーティファクトではなく別々のタスクとしてモデル化すべき。
• Last-DataPart 権威。 1 つのアーティファクトに複数の DataPart が現れるとき（ストリーミング中に典型的）、最後のものが権威的。以前の DataPart は置き換えられた進捗スナップショット。
• First-DataPart は interim 用。 status.message.parts に複数の DataPart が現れるとき、最初のものが使われる — interim 更新は累積ではなく単一イベントのスナップショット。
• ラッパー拒否。 .data が { response: {...} }（response という単一キー）の DataPart は、有効なペイロードではなくフレームワークラッパーのバグとして扱われる。

​

ワイヤー形式の互換性

​

ステータスベースの抽出

​

抽出アルゴリズム

0. ストリームエンベロープをアンラップ。 入力が task、message、statusUpdate、artifactUpdate という正確に 1 つのトップレベルキーを持つオブジェクトで、そのキーの値が非 null・非配列オブジェクトなら、入力をその値で置き換える（A2A 1.0 StreamResponse oneof）。素の Task / TaskStatusUpdateEvent オブジェクト — 非ストリーミングレスポンスまたは v0.3 — は変更なく通過。artifactUpdate はタスクステータスを運ばない。アンラップされると status.state は欠如しステップ 1 は null を返す。 正確に一度 アンラップする。クライアントは再帰してはならない（MUST NOT）。アンラップされた内部オブジェクト自体が単一キーエンベロープ形状（{ task: { task: {...} } } または任意の組み合わせ）を持つ場合、不正な形式として扱い null を返す — これはネストされたエンベロープの密輸試行。内部値のトップレベルキーが task / message / statusUpdate / artifactUpdate のいずれかを含むエンベロープは拒否されなければならない（MUST）。 素の { message } エンベロープ（帯域外エージェントメッセージ）はタスク指向の抽出器によって無視されなければならない（MUST） — アンラップされたオブジェクトが status.state を持たないときステップ 1 は null を返す。Webhook/SSE ハンドラーは、認識されない { message } エンベロープに 200 OK 承認を返してはならない（MUST NOT）。エンドポイントをプローブする攻撃者への存在オラクルとして動作するのを避けるため、400 Bad Request を返すかトランスポート層で黙って破棄する。
1. status.state を読む。 欠如なら null を返す。比較前に小文字形式に正規化（TASK_STATE_COMPLETED → completed）。正規化後、state は 正確な ASCII 文字列等価 で既知の final/interim トークンの 1 つに一致しなければならない（MUST）。クライアントは、繰り返しのセパレーターを折り畳んだり、空白をトリムしたり、ASCII 小文字を超えた Unicode case-folding を適用したりしてはならない（MUST NOT）。他の任意の値 — クライアントが認識しない新しい TASK_STATE_* 入力を含む — は「unknown」で、抽出は null を返す（ステップ 4）。
2. Final 状態（completed、failed、canceled、rejected）: a. artifacts[0].parts[] で DataPart（data フィールドが非 null オブジェクトの Part — kind の存在にかかわらず）を探す。 b. 最後の DataPart を権威的として使う（Last-DataPart Authority を参照）。 c. ラッパーを拒否: DataPart の .data がオブジェクトを含む単一キー response を持つ場合、これはフレームワークラッパーのバグ。throw またはエラーをログ。 d. .data を返す。 e. フォールバック: アーティファクトがない、またはアーティファクトに DataPart がない場合、ステップ 3 を使って status.message.parts[] を確認。
3. Interim 状態（working、submitted、input-required、auth-required）: a. status.message.parts[] で DataPart を探す。 b. 最初の DataPart を使う。 c. .data を返す、または DataPart が見つからなければ null。
4. Unknown 状態: null を返す。前方互換のクライアントは認識されないステータス値で throw すべきではない（SHOULD NOT）。

function normalizeState(state) {
  if (typeof state !== 'string') return null;
  return state.replace(/^TASK_STATE_/, '').toLowerCase().replace(/_/g, '-');
}

function isDataPart(p) {
  return p != null
    && p.data != null
    && typeof p.data === 'object'
    && !Array.isArray(p.data);
}

// A2A 1.0 StreamResponse oneof: { task } | { message } | { statusUpdate } | { artifactUpdate }
function unwrapStreamEnvelope(input) {
  if (input == null || typeof input !== 'object' || Array.isArray(input)) return input;
  const keys = Object.keys(input);
  if (keys.length !== 1) return input;
  const envelopeKeys = ['task', 'message', 'statusUpdate', 'artifactUpdate'];
  if (envelopeKeys.includes(keys[0]) && typeof input[keys[0]] === 'object' && input[keys[0]] !== null) {
    return input[keys[0]];
  }
  return input;
}

function extractAdcpResponseFromA2A(input) {
  const task = unwrapStreamEnvelope(input);
  const state = normalizeState(task?.status?.state);
  if (!state) return null;

  const FINAL = ['completed', 'failed', 'canceled', 'rejected'];
  const INTERIM = ['working', 'submitted', 'input-required', 'auth-required'];

  if (FINAL.includes(state)) {
    // Final: last DataPart from artifacts[0]
    const artifact = task.artifacts?.[0];
    if (artifact?.parts) {
      const dataParts = artifact.parts.filter(isDataPart);
      if (dataParts.length > 0) {
        const last = dataParts[dataParts.length - 1];
        // Reject framework wrappers
        const keys = Object.keys(last.data);
        if (keys.length === 1 && keys[0] === 'response' && typeof last.data.response === 'object') {
          throw new Error(
            'Invalid response format: DataPart contains wrapper object {response: {...}}. ' +
            'This is a server-side bug.'
          );
        }
        return last.data;
      }
    }
    // Fallback to status.message.parts
    return extractFromMessage(task);
  }

  if (INTERIM.includes(state)) {
    return extractFromMessage(task);
  }

  return null; // Unknown state
}

function extractFromMessage(task) {
  const parts = task.status?.message?.parts;
  if (!Array.isArray(parts)) return null;
  const dataPart = parts.find(isDataPart);
  return dataPart?.data ?? null;
}

​

Last-DataPart Authority

{
  "status": {"state": "TASK_STATE_COMPLETED"},
  "artifacts": [{
    "parts": [
      {"text": "Found products"},
      {"data": {"progress": 25}},
      {"data": {"products": [...], "total": 12}}
    ]
  }]
}

​

ラッパー拒否

// REJECTED: wrapper detected
{"data": {"response": {"products": [...]}}}

// ACCEPTED: direct payload
{"data": {"products": [...]}}

// NOT a wrapper — response is one of several keys
{"data": {"response": {...}, "status": "completed", "errors": []}}

​

エラー抽出との関係

function handleA2aResponse(task) {
  const data = extractAdcpResponseFromA2A(task);

  // Check if the extracted data is an error
  if (data?.adcp_error) {
    return handleError(data.adcp_error);
  }

  return handleSuccess(data);
}

​

セキュリティ考慮事項

​

セラー制御データ

​

プロトタイプ汚染

​

FilePart URI 検証

​

Auth チャレンジ URL 検証

• スキームは https でなければならない（MUST）。http:、javascript:、data:、file: を拒否。
• URL は userinfo コンポーネント（user:pass@host 形式）を含んではならない（MUST NOT）。
• ホストは、このエージェントカードの認証されたセラーの登録された auth オリジンに一致しなければならない（MUST）。クライアントは、タスクペイロードから導出されるのではなく、Agent Card の supportedInterfaces[].url オリジンまたは宣言された authOrigin 拡張フィールドからシードされたエージェントごとの許可リストを維持すべき（SHOULD）。
• 任意の redirect_uri、return_url、または類似のクエリパラメーターは、ナビゲーション前にクライアントによって落とされるか上書きされなければならない（MUST）。セラー供給のリダイレクトを決して転送しない。
• scopes は付与ではなくリクエストとして扱われなければならない（MUST）。scopes をユーザーに示し、各チャレンジで新鮮な同意を得る。

​

セラー制御文字列の衛生

​

サイズ制限

​

仲介者注入

​

クライアントライブラリ要件

1. A2A 1.0 ストリームエンベロープをアンラップ。 task、message、statusUpdate、artifactUpdate のキーを持つ単一キーオブジェクトは StreamResponse ラッパー — アルゴリズムの残りを適用する前に内部オブジェクトにアンラップ。素のオブジェクトは変更なく通過。
2. A2A 1.0 と v0.3 の両ワイヤー形状を受け入れる。 比較前に status.state を正規化（TASK_STATE_ プレフィックス除去、小文字化、アンダースコアをハイフンに）。kind ではなくフィールド存在（data が非 null オブジェクト）で DataPart を検出。
3. 正規化された state で分岐。 Final 状態（completed、failed、canceled、rejected）はアーティファクトを使い、interim 状態（working、submitted、input-required、auth-required）は status.message.parts を使う。
4. Final 状態には最後の DataPart を使う。 null、非オブジェクト、配列 .data の DataPart をスキップ。
5. Interim 状態には最初の DataPart を使う。
6. ラッパーを検出し拒否。 単一キー {response: {...}} ペイロードはバグ。
7. 優雅にフォールバック。 Final 状態でアーティファクトが空なら、status.message.parts を確認。
8. Unknown 状態を扱う。 null を返し、throw しない。

​

テストベクター

• status: A2A タスクステータス
• path: 抽出パス（artifact、status_message、または none）
• response: A2A Task または TaskStatusUpdateEvent
• expected_data: 抽出されるべき AdCP データ（または null）
• expected_error_type: 存在する場合、抽出は throw すべき（例: wrapper_detected）

​

関連項目

• A2A Response Format — セラーの正準レスポンス構造
• Transport Error Mapping — MCP と A2A からのエラー抽出
• MCP Response Extraction — MCP の同等仕様
• A2A Guide — A2A トランスポート統合