> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.adid.dev/llms.txt.
> For full documentation content, see https://docs.adid.dev/llms-full.txt.

# A2A Protocol Support

IDA integrates with Google's Agent-to-Agent (A2A) protocol to enable cross-vendor agent collaboration with verifiable identity. A2A defines how agents discover each other, negotiate tasks, and exchange results.

## A2A Protocol Overview

```mermaid
sequenceDiagram
    participant Client as Client Agent
    participant Server as Server Agent

    Client->>Server: GET /.well-known/agent.json
    Server->>Client: Agent Card
    Client->>Client: Verify Agent Card + DID
    Client->>Server: POST /a2a (tasks/send)
    Server->>Client: Task accepted (working)
    Server->>Server: Execute task
    Server->>Client: Task result (done)
```

## Agent Card Serving

IDA agents serve A2A-compatible Agent Cards at the `.well-known` endpoint:

```http
GET https://agent.example.com/.well-known/agent.json
```

See [Agent Discovery & Cards](discovery.md) for the full Agent Card format.

## Task Lifecycle

A2A defines a task lifecycle that IDA extends with identity verification:

| State            | Description                   | IDA Extension                     |
| ---------------- | ----------------------------- | --------------------------------- |
| `submitted`      | Task received by server agent | IBCT verified, delegation checked |
| `working`        | Agent is processing the task  | Audit trail started               |
| `input-required` | Agent needs more information  | HITL if high-risk                 |
| `done`           | Task completed successfully   | Audit receipt signed              |
| `failed`         | Task failed                   | Failure logged to audit trail     |
| `canceled`       | Task canceled by client       | Cancellation logged               |

## Authentication Flow

IDA extends A2A authentication with DID-based auth:

### Standard A2A (OAuth 2.0)

```http
POST /a2a
Authorization: Bearer <oauth-access-token>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tasks/send",
  "params": { "..." }
}
```

### IDA-Enhanced (DID Auth + IBCT)

```http
POST /a2a
Authorization: DIDAuth <did-auth-token>
X-IDA-IBCT: <ibct-token>
X-IDA-Agent-DID: did:adi:agent:buyer01...
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tasks/send",
  "params": {
    "id": "task-001",
    "message": {
      "role": "user",
      "parts": [
        {
          "type": "text",
          "text": "Compare prices for organic milk across all authorized merchants"
        }
      ]
    }
  },

  "ida": {
    "agentDid": "did:adi:agent:buyer01...",
    "ibct": "eyJhbGciOiJFZERTQSJ9...",
    "delegationChain": ["urn:uuid:root-delegation"]
  }
}
```

## Task Send with IDA Identity

### Request

```json
{
  "jsonrpc": "2.0",
  "method": "tasks/send",
  "params": {
    "id": "task-price-compare-001",
    "message": {
      "role": "user",
      "parts": [
        {
          "type": "text",
          "text": "Find the best price for 1 gallon organic milk"
        }
      ]
    },
    "metadata": {
      "ida_agent_did": "did:adi:agent:buyer01...",
      "ida_ibct": "eyJhbGciOiJFZERTQSJ9...",
      "ida_required_trust_score": 70
    }
  },
  "id": "req-001"
}
```

### Response (Working)

```json
{
  "jsonrpc": "2.0",
  "result": {
    "id": "task-price-compare-001",
    "status": {
      "state": "working",
      "message": "Comparing prices across 2 merchants..."
    },
    "metadata": {
      "ida_server_agent_did": "did:adi:agent:seller01...",
      "ida_audit_receipt_id": "receipt-abc123"
    }
  },
  "id": "req-001"
}
```

### Response (Done)

```json
{
  "jsonrpc": "2.0",
  "result": {
    "id": "task-price-compare-001",
    "status": {
      "state": "done"
    },
    "artifacts": [
      {
        "name": "price-comparison",
        "parts": [
          {
            "type": "text",
            "text": "Best price: FreshMart - $5.99/gallon (OrganicCo: $6.49)"
          }
        ]
      }
    ],
    "metadata": {
      "ida_audit_receipt": {
        "id": "receipt-abc123",
        "agentDid": "did:adi:agent:seller01...",
        "result": "success",
        "signature": "z58DAdFfa9SkqZMVPxAQpic7..."
      }
    }
  },
  "id": "req-001"
}
```

## Server Agent Setup

### Express.js A2A Server with IDA

```javascript
import express from 'express';
import { IDAClient } from '@ida/sdk';

const app = express();
const ida = new IDAClient({ apiUrl: 'http://localhost:8080' });

// Serve Agent Card
app.get('/.well-known/agent.json', (req, res) => {
  res.json({
    name: "Price Comparison Agent",
    description: "Compares prices across merchants",
    url: "https://price-agent.example.com",
    identity: {
      did: "did:adi:agent:seller01...",
      operatorDid: "did:adi:merchant001...",
      trustScore: 88
    },
    skills: [
      {
        id: "price-compare",
        name: "Price Comparison",
        tags: ["prices", "comparison"]
      }
    ],
    authentication: {
      schemes: [
        { scheme: "did-auth", didMethod: "did:adi" },
        { scheme: "oauth2", flows: ["client_credentials"] }
      ]
    }
  });
});

// A2A endpoint
app.post('/a2a', async (req, res) => {
  const { method, params, ida: idaParams } = req.body;

  // Verify client agent's identity
  if (idaParams?.ibct) {
    const verification = await ida.verifyIBCT(idaParams.ibct);
    if (!verification.valid) {
      return res.json({
        jsonrpc: "2.0",
        error: { code: -32001, message: "IBCT verification failed" }
      });
    }
  }

  if (method === 'tasks/send') {
    // Process task
    const result = await handleTask(params);
    return res.json({
      jsonrpc: "2.0",
      result: { id: params.id, status: { state: "done" }, artifacts: [result] }
    });
  }
});
```

## Multi-Agent Collaboration

A2A enables multi-agent workflows where IDA provides the trust layer:

```mermaid
graph LR
    subgraph "Enterprise (Operator)"
        OP[Org DID]
    end

    subgraph "Agent Team"
        DC[DataCollector<br />did:adi:agent:dc01]
        AN[Analyzer<br />did:adi:agent:an01]
        RW[ReportWriter<br />did:adi:agent:rw01]
    end

    OP -->|"Delegation: read surveys"| DC
    OP -->|"Delegation: analyze data"| AN
    OP -->|"Delegation: write reports"| RW

    DC -->|"A2A: raw data"| AN
    AN -->|"A2A: analysis"| RW

    style OP fill:#dbeafe
    style DC fill:#d1fae5
    style AN fill:#d1fae5
    style RW fill:#d1fae5
```

Each A2A interaction carries:

1. The sending agent's IBCT (proving delegation)
2. The task payload
3. Audit receipts for every step

## A2A + DID Auth vs OAuth 2.0

| Feature           | OAuth 2.0             | DID Auth + IBCT                 |
| ----------------- | --------------------- | ------------------------------- |
| Identity proof    | Client ID + secret    | Cryptographic DID signature     |
| Delegation        | Not supported         | Full delegation chain           |
| Scope enforcement | OAuth scopes (static) | IBCT scope (per-invocation)     |
| Trust scoring     | Not available         | On-chain trust score            |
| Audit trail       | Application-level     | Cryptographic receipts          |
| Revocation        | Token revocation      | Real-time delegation revocation |

IDA supports both authentication methods. OAuth 2.0 is available for backward compatibility with non-IDA agents.