@opencommerceprotocol/bridge-a2a

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

Installation

npm install @opencommerceprotocol/bridge-a2a

Usage

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

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

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

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

{
  "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:

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

CLI Alternative

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