OAM and A2A¶

A2A (Agent-to-Agent) is Google's protocol for cross-organization agent federation. It defines how agents from different companies discover and invoke each other over HTTP, using a standard Agent Card format.

OAM is designed to work with A2A, not against it. The relationship is straightforward:

• OAM = internal fabric (agents within your organization, over NATS)
• A2A = external bridge (agents across organizations, over HTTP)

from openagentmesh import AgentMesh

mesh = AgentMesh("nats://mesh.company.com:4222")
contract = await mesh.contract("summarizer")

# The contract is already A2A-compatible. Project it to an
# A2A Agent Card, injecting the url at the federation boundary:
card = contract.to_agent_card(url="https://agents.example.com/summarizer")

Contract compatibility¶

OAM contracts are an A2A-compatible superset. The contract schema places A2A-standard fields at the top level and OAM-specific extensions under x-agentmesh:

{
  "name": "summarizer",
  "description": "Summarizes input text...",
  "version": "1.0.0",
  "capabilities": { "streaming": false, "invocable": true },
  "skills": [
    {
      "id": "summarizer",
      "name": "Summarize text",
      "description": "...",
      "tags": ["text", "summarization"],
      "inputSchema": { },
      "outputSchema": { }
    }
  ],
  "x-agentmesh": {
    "channel": "nlp",
    "subject": "mesh.agent.nlp.summarizer",
    "tags": ["text", "summarization"]
  }
}

The projection from OAM contract to A2A Agent Card is a thin operation: strip the x-agentmesh extension and inject the url field. The url is the only A2A field not stored in the OAM registry, because it's gateway-provided at the federation boundary.

The url field¶

Internally, agents are addressed by NATS subject (mesh.agent.nlp.summarizer). They don't have HTTP URLs. When you expose an agent externally via an A2A-compatible gateway, the gateway assigns the URL.

The contract's to_agent_card(url=None) method produces the A2A Agent Card: the registry document with the x-agentmesh block stripped and the url injected when you pass one. Without a url (the default), the field is omitted — useful for inspecting the card shape before a gateway assigns the address.

When to use which¶

For how OAM relates to MCP, see OAM and MCP. For the technology choices behind OAM, see Technology Stack.