AI Catalog Interop¶
a2a shares its catalog store with ai-catalog-cli, the reference CLI for AI Catalogs. This example goes both ways: a contact saved with a2a shows up in ai-catalog search, and a catalog registered with ai-catalog is searchable and callable from a2a.

Prerequisites¶
a2a.ai-catalog, from its releases orbrew install ai-catalogafterbrew tap Agent-Card/ai-catalog-cli https://github.com/Agent-Card/ai-catalog-cli.- No model or API key.
start-agents.shruns three small local agents witha2a server --exec, on ports 9101 to 9103.
Run the commands in this directory. Start the agents in a second terminal:
./start-agents.sh
A contact, seen by ai-catalog¶
Save the weather agent as a contact:
a2a contact add weather localhost:9101 --note "Forecasts for trip planning"
Added contact weather: Weather (urn:ai-catalog:a2a-cli:weather)
The contact book is a catalog of its own, registered in the shared store as a2a-contacts, so ai-catalog lists and searches it:
ai-catalog catalog list
ai-catalog search weather
NAME URL ENTRIES LAST UPDATED HASH
--------------------------------------------------------------------------------------------------------
a2a-contacts file:///home/you/.config/a2a-cli/catalog.json 1 2026-11-16T09:58:03 da99b5df
IDENTIFIER NAME DESCRIPTION TYPE CATALOG
------------------------------------------------------------------------------------------------------------------------------
urn:ai-catalog:a2a-cli:weather Weather Current weather for any city application/a2a-agent-card+json file:///home/you/.config/a2…
A catalog, used by a2a¶
acme-catalog.json lists two of Acme's agents. Register it with ai-catalog:
ai-catalog catalog add acme ./acme-catalog.json
Fetching catalog from ./acme-catalog.json...
✓ "acme" added (2 entries)
a2a reads the same store, so it sees the catalog and finds its agents:
a2a catalog list
a2a catalog search travel
NAME SOURCE ENTRIES LAST UPDATED
a2a-contacts file:///home/you/.config/a2a-cli/catalog.json 1 2026-11-16 09:58:03
acme file:///home/you/ai-catalog-interop/acme-catalog.json 2 2026-11-16 09:58:03
IDENTIFIER NAME VERSION CATALOG DESCRIPTION
urn:air:acme.example:agent:travel Travel Desk - acme Books flights and hotels within Acme's travel policy
urn:air:acme.example:agent:expenses Expenses - acme Files expense reports and answers questions about reimburse…
Talk to an agent by its identifier:
a2a send -a urn:air:acme.example:agent:travel "Lisbon, 3 nights from Dec 2"
Status: completed (2026-11-16T09:57:38Z)
Artifacts:
[01a1e3ca-7391-71d0-8a3d-dc63f6766e82] Booked: Lisbon, 3 nights from Dec 2. Confirmation TD-4821.
Save it as a contact to give it a short name. The contact keeps the catalog identifier:
a2a contact add travel urn:air:acme.example:agent:travel
a2a send -a travel "Porto, 1 night from Dec 5"
a2a contact list
NAME AGENT IDENTIFIER NOTE
travel Travel Desk urn:air:acme.example:agent:travel -
weather Weather urn:ai-catalog:a2a-cli:weather Forecasts for trip planning
How it works¶
Both tools keep registered catalogs in ~/.ai-catalog, or the directory in AI_CATALOG_CACHE_DIR. a2a catalog add and ai-catalog catalog add write the same entries, so each tool sees the other's catalogs. The contact book at ~/.config/a2a-cli/catalog.json is an ordinary AI Catalog that only a2a writes; a2a contact add registers it in the store the first time.
AI Catalogs and Contacts describe both features.
Clean up¶
a2a contact remove weather travel
ai-catalog catalog remove acme