npm package: @opencommerceprotocol/bridge-a2a
Description: Open Commerce Protocol — Google A2A (Agent-to-Agent) bridge
Latest version: 1.0.0

# @opencommerceprotocol/bridge-a2a

Google A2A (Agent-to-Agent) bridge for the [Open Commerce Protocol](https://opencommerceprotocol.org). Converts an OCP manifest into a Google A2A agent card, enabling A2A-compatible agents to discover and invoke OCP tools.

## Installation

```bash
npm install @opencommerceprotocol/bridge-a2a
```

## Usage

```typescript
import { ocpToA2ACard, generateA2AWellKnown } from '@opencommerceprotocol/bridge-a2a';
import type { OCPManifest } from '@opencommerceprotocol/spec';

const ocpManifest: OCPManifest = { /* your manifest */ };

// Convert to A2A agent card object
const card = ocpToA2ACard(ocpManifest);

// Or generate the JSON string for serving at /.well-known/agent.json
const agentJson = generateA2AWellKnown(ocpManifest);
```

## Serving the A2A Agent Card

### Express

```typescript
import express from 'express';
import { generateA2AWellKnown } from '@opencommerceprotocol/bridge-a2a';
import manifest from './.well-known/ocp.json';

const app = express();

app.get('/.well-known/agent.json', (req, res) => {
  res.setHeader('Content-Type', 'application/json');
  res.send(generateA2AWellKnown(manifest));
});
```

### Hono

```typescript
import { Hono } from 'hono';
import { ocpToA2ACard } from '@opencommerceprotocol/bridge-a2a';
import manifest from './.well-known/ocp.json';

const app = new Hono();
app.get('/.well-known/agent.json', (c) => c.json(ocpToA2ACard(manifest)));
```

## Output: `A2AAgentCard`

```typescript
interface A2AAgentCard {
  name: string;           // '<merchant name> Shopping Agent'
  description: string;    // from merchant.description or auto-generated
  url: string;            // merchant.url
  iconUrl?: string;       // merchant.logo
  version: string;        // '1.0.0'
  capabilities: {
    streaming: boolean;
    pushNotifications: boolean;
    stateTransitionHistory: boolean;
  };
  authentication: {
    schemes: string[];    // ['none'] by default
  };
  skills: A2ASkill[];
  ocp_source?: string;    // link back to /.well-known/ocp.json
}

interface A2ASkill {
  id: string;            // OCP tool name, e.g. 'search_products'
  name: string;          // Human-readable, e.g. 'Search Products'
  description: string;   // OCP tool description
  tags?: string[];       // e.g. ['shopping', 'search', 'catalog']
  examples?: string[];   // sample queries
  inputModes?: string[]; // ['application/json']
  outputModes?: string[];// ['application/json']
}
```

## Tool → Skill Mapping

Each OCP tool in `manifest.interact.tools` becomes an A2A skill:

| OCP Tool | Tags | Example Queries |
|----------|------|-----------------|
| `search_products` | shopping, search, catalog | "Find blue running shoes under $100" |
| `get_product` | shopping, product, catalog | "Get details for product ID 12345" |
| `get_product_qa` | shopping, product, qa | "Does product 123 fit a 6-foot person?" |
| `compare_products` | shopping, comparison | "Compare products 123, 456, and 789" |
| `add_to_cart` | shopping, cart, purchase | "Add 2 units of product 123 to cart" |
| `get_cart` | shopping, cart | "What is in my cart?" |
| `update_cart` | shopping, cart | "Update product 123 quantity to 3" |
| `begin_checkout` | shopping, checkout, purchase | "Start checkout" |
| `check_availability` | shopping, inventory | "Is product 123 in stock?" |

## Example Agent Card Output

```json
{
  "name": "My Store Shopping Agent",
  "description": "AI shopping agent for My Store. Search products, manage cart, and begin checkout via OCP.",
  "url": "https://mystore.com",
  "version": "1.0.0",
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "stateTransitionHistory": false
  },
  "authentication": { "schemes": ["none"] },
  "skills": [
    {
      "id": "search_products",
      "name": "Search Products",
      "description": "Search the product catalog by keyword, category, or price range",
      "tags": ["shopping", "search", "catalog"],
      "examples": ["Find blue running shoes under $100"],
      "inputModes": ["application/json"],
      "outputModes": ["application/json"]
    }
  ],
  "ocp_source": "https://mystore.com/.well-known/ocp.json"
}
```

## OCP Manifest Declaration

Declare your A2A endpoint in the OCP manifest:

```json
{
  "bridge": {
    "a2a": "https://mystore.com/.well-known/agent.json"
  }
}
```

## CLI Alternative

```bash
npx @opencommerceprotocol/cli bridge --protocol a2a --manifest .well-known/ocp.json
```