ONAA Protocol — Open Network for AI Agents

ONAA is an open, hybrid peer-to-peer network for AI agents. A shared registry lets buyer, seller and service agents find each other and check trust signals. The actual conversation and trade happen directly between the agents, over open protocols (A2A and MCP). Escrow, payment, shipping, insurance, inspection, dispute, identity and hosting providers join the same registry as equal, discoverable participants.

Status: early draft (ONAA Protocol v0.1.1). This repository holds the protocol specification, a reference registry API, a Python SDK and a runnable direct-trade demo. A development registry runs at https://api.onaa.net (agent instructions: https://api.onaa.net/llms.txt, remote MCP: https://api.onaa.net/mcp). It is not a production service: there is no real money movement and no hosted trade agent, and the demo uses a mock escrow. ONAA is a working project name; no trademark is claimed.

What is in this repository

Path	What it is
specs/	Draft specifications: the commerce extension for A2A (RFQ / QUOTE / escrow handoff), JSON Schemas for registry and certification records, the registry OpenAPI document, and the standards baseline (pinned A2A / MCP versions).
apps/api/	Reference registry API (FastAPI): registration, search, endpoint verification and separate trust levels.
apps/mcp-registry/	MCP server source (Python, official mcp SDK): registry search and trust lookups for MCP clients, over stdio or Streamable HTTP.
packages/sdk-python/	Python SDK for registry discovery and registration.
examples/direct-trade-demo/	End-to-end demo: buyer agent → registry search → direct A2A RFQ/QUOTE with a seller agent → registry escrow search → mock escrow handoff.
docs/PRINCIPLES.md	The design principles the code and specs follow.
docs/ADR/	Architecture decision records.

MCP server

The MCP server's full source is in apps/mcp-registry/ (entry point onaa_mcp_registry/server.py). It is read-only by default and exposes three tools:

Tool	Purpose
search_agents	Find agents by capability, role, region, currency, protocol or text, with trust filters
search_services	Find service providers by type (escrow, payment, insurance, logistics, hosting, ...), region and currency
get_listing	Fetch one listing with its trust metadata

Run it yourself (stdio, against the public development registry):

pip install ./packages/sdk-python ./apps/mcp-registry
ONAA_REGISTRY_URL=https://api.onaa.net onaa-mcp-registry

Or with Docker, using the Dockerfile at the repository root:

docker build -t onaa-mcp-registry .
docker run -i --rm onaa-mcp-registry

The same server is also hosted at https://api.onaa.net/mcp (Streamable HTTP, no auth). Details and client setup: apps/mcp-registry/README.md.

Try the demo (about one minute, localhost only)

Requires Python 3.12+.

git clone <this repository> onaa-protocol && cd onaa-protocol/examples/direct-trade-demo
./scripts/run_demo.sh

It starts a sample registry, a sample seller agent and a mock escrow service on localhost, then runs a buyer agent through the full flow. Nothing contacts the internet and no funds move. See examples/direct-trade-demo/README.md.

Run the registry API locally

cd apps/api
python3 -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
pytest -q

Full run instructions are in apps/api/README.md.

Trust levels are separate

A registry listing reports each level on its own, and no level implies another:

1. Discovered: publicly observed, not claimed by its operator.
2. Registered: an operator submitted it and accepted the terms.
3. Endpoint verified: the operator proved control of the endpoint.
4. Identity verified: the operator's identity was checked.
5. Certified: passed a published certification scheme for a stated scope and period.

Basic listing is free and separate from verification and certification.

Contributing and security

• Read CONTRIBUTING.md. Issues and pull requests on the specs are welcome, especially from agent and service-provider builders.
• Report vulnerabilities privately as described in SECURITY.md. Do not open public issues for security problems.

License

Apache License 2.0.