---
name: ap2-a2a-extension-7b48c58a6642
description: >
  Implement AP2 as an A2A extension — mandate DataParts in A2A messages, Agent
  Card AP2 capabilities, payment-specific task flows, and inter-agent payment
  communication. Use when integrating AP2 payment capabilities into A2A
  multi-agent systems.
---

# AP2 as an A2A Extension

## Before writing code

**Fetch live docs**:
1. Fetch `https://ap2-protocol.org/ap2/specification/` for the A2A extension specification
2. Fetch `https://ap2-protocol.org/ap2/implementation_considerations/` for protocol integration details
3. Web-search `site:github.com google-agentic-commerce AP2 a2a extension` for reference implementation
4. Web-search `site:github.com google-agentic-commerce AP2 samples a2a` for A2A-based samples

## Conceptual Architecture

### AP2 Extends A2A

AP2 is designed as a **direct extension of the A2A protocol**. It adds payment-specific capabilities to A2A's general-purpose agent-to-agent communication:

- A2A provides: tasks, messages, parts, streaming, agent cards
- AP2 adds: mandates, payment flows, VDCs, cryptographic signing, risk signals

### Why A2A is Required

As the documentation states: "A2A is required to standardize intra-agent communication — as soon as you have more than one agent you need A2A." AP2 adds payment standardization on top.

### How AP2 Rides on A2A

#### Agent Cards with AP2 Capabilities

AP2 agents declare payment support in their Agent Card:
```json
{
  "name": "MerchantAgent",
  "capabilities": {
    "extensions": [
      {
        "description": "AP2 Payment Extension",
        "required": true,
        "uri": "https://ap2-protocol.org/extension/v1"
      }
    ]
  },
  "skills": [
    {
      "id": "checkout",
      "name": "Cart and Payment",
      "description": "Handles product search and cart creation",
      "tags": ["ap2", "payment", "commerce"]
    }
  ],
  "security": [...],
  "securitySchemes": {...}
}
```

#### Mandates as A2A DataParts

AP2 mandates are transmitted as **DataParts** within A2A messages:
- Intent Mandate → DataPart in message from Shopping Agent to Merchant
- Checkout Mandate → DataPart in response from Merchant to Shopping Agent
- Payment Mandate → DataPart in payment flow messages

#### A2A Tasks for Payment Flows

Each phase of the AP2 flow maps to A2A tasks:
- Product search → A2A task (SA → Merchant)
- Payment method query → A2A task (SA → CP)
- Payment processing → A2A task (Merchant → MPP)
- Challenge handling → A2A messages within existing tasks

### Message Structure

A2A messages carrying AP2 mandates include:
```json
{
  "role": "user",
  "parts": [
    {
      "type": "text",
      "text": "I want to buy a coffee maker"
    },
    {
      "type": "data",
      "data": {
        "intent_mandate": { ... }
      }
    }
  ]
}
```

### Protocol Stack

```
┌─────────────────────────────┐
│ AP2 (Mandates, VDCs, Signing)│
├─────────────────────────────┤
│ A2A (Tasks, Messages, Parts) │
├─────────────────────────────┤
│ HTTP / JSON-RPC 2.0          │
└─────────────────────────────┘
```

### Discovery

Shopping Agents discover AP2-capable merchants by:
1. Fetching Agent Cards (from `.well-known/agent-card.json` or registries)
2. Checking for AP2 extension in `capabilities.extensions[]`
3. Examining skills for payment-related capabilities
4. Verifying authentication requirements

### Watch Log

The reference samples include a `watch.log` that captures:
- Raw HTTP data (methods, URLs, request/response bodies)
- A2A message data (instructions and DataParts)
- AP2 protocol data (IntentMandate, CheckoutMandate, PaymentMandate objects)

This is valuable for debugging the A2A ↔ AP2 integration.

### Best Practices

- Declare AP2 extension in Agent Cards for discoverable payment capabilities
- Use A2A DataParts (not TextParts) for mandate transmission
- Follow A2A task lifecycle for payment flow state management
- Implement A2A streaming for real-time payment status updates
- Use A2A authentication alongside AP2 mandate signing
- Test the full A2A + AP2 integration with the official samples
- Log both A2A and AP2 protocol data for debugging

Fetch the specification for exact A2A extension schema, DataPart structures for mandates, and Agent Card AP2 capability declaration before implementing.


---
Source attribution: OrcaQubits
Original project: https://github.com/OrcaQubits/agentic-commerce-skills-plugins/blob/30cd25c74c8aa7dc49b3ec4847d463f6104439f6/dist/codex/ap2-agentic-payments/skills/ap2-a2a-extension/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Dave AI.

## Upstream license notice

MIT License

Copyright (c) 2024-2026 OrcaQubits AI (https://orcaqubits-ai.com)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Dave AI resource metadata

Creator / publisher: OrcaQubits
Original project: https://github.com/OrcaQubits/agentic-commerce-skills-plugins/blob/30cd25c74c8aa7dc49b3ec4847d463f6104439f6/dist/codex/ap2-agentic-payments/skills/ap2-a2a-extension/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering, Product Management
Roles: Backend Developer, ML / AI Engineer, Product Manager
Specialties: API, Backend
Tools: Ap2 Protocol
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 49754b760ba610b7b6134baebf354353aa624d8b84e17c20ff7e141ba34c78e5