@opencommerceprotocol/bridge-a2a

A2A Bridge

Convert an OCP manifest into a Google A2A (Agent-to-Agent) agent card. Each OCP tool becomes an A2A “skill,” enabling A2A-compatible agents to discover and invoke OCP store capabilities.

Installation

npm install @opencommerceprotocol/bridge-a2a

Usage

Two core functions: ocpToA2ACard() returns an agent card object, generateA2AWellKnown() returns a JSON string ready to serve.

convert.ts

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

server.ts

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

worker.ts

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)));

A2AAgentCard Type

types.ts

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 to Skill Mapping

Each OCP tool in manifest.interact.tools becomes an A2A skill with auto-generated tags and example queries:

search_products

shoppingsearchcatalog

“Find blue running shoes under $100”

get_product

shoppingproductcatalog

“Get details for product ID 12345”

get_product_qa

shoppingproductqa

“Does product 123 fit a 6-foot person?”

compare_products

shoppingcomparison

“Compare products 123, 456, and 789”

add_to_cart

shoppingcartpurchase

“Add 2 units of product 123 to cart”

get_cart

shoppingcart

“What is in my cart?”

update_cart

shoppingcart

“Update product 123 quantity to 3”

begin_checkout

shoppingcheckoutpurchase

“Start checkout”

check_availability

shoppinginventory

“Is product 123 in stock?”

Example Output

A generated agent card for a store called “My Store”:

/.well-known/agent.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 the A2A endpoint in your OCP manifest so agents can discover it:

/.well-known/ocp.json (excerpt)

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

CLI Alternative

Generate the A2A agent card without writing code:

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

Next Steps

Protocol Specification

Full reference for manifests, products, tools, and types.

MCP Bridge

Expose OCP tools to Claude Desktop and Cursor via MCP.

UCP Bridge

Convert OCP manifests for Google UCP checkout agents.

Playground

Validate your OCP implementation and see your score.