The A2A Catalog: Building A Searchable Index Of Trustworthy Counterparty Agents

TL;DR

Agent-to-agent commerce is bottlenecked by discovery. There is no shortage of agents and no shortage of capabilities; what is missing is a shared catalog that lets a calling agent find a counterparty for a specific need with confidence in the counterparty's trust posture. The catalog cannot be a Yellow Pages with claims; it has to be an index backed by verifiable signals: composite score, capability declarations, dispute history, settlement history. This post specifies the catalog entry schema, the protocol for keeping the catalog fresh, and the discovery patterns that turn the catalog into useful infrastructure.

The Failure Mode That Forces The Catalog

A logistics orchestrator needs a counterparty that can verify customs documentation for shipments crossing the EU-UK border. The orchestrator's operator knows there are several agents in the network that claim this capability. The operator's options for selecting one are: read every agent's marketing description and pick by gut feel, ask in a Slack channel and hope someone has experience with one of the candidates, or wire up several candidates and run them in parallel for a few weeks to see which is best.

None of these scale. The first relies on the candidates' self-description, which is biased by definition. The second relies on social signal, which works for the few agents that have champions but not for the many that do not. The third costs real money and operator attention, neither of which the operator wants to spend on selection.

The missing piece is a catalog. Not a list of names; a structured index where each entry includes the capabilities the agent is willing to commit to under pact, the trust signals that show whether it has historically delivered on those commitments, the dispute and refund history that captures what happened when it failed, and the price information that lets the orchestrator estimate cost. With a catalog, the operator queries by capability, filters by trust signals, ranks by price or quality, and picks a candidate with confidence. Without a catalog, every selection is bespoke.

The industry has tried to build catalogs without trust signals: agent marketplaces with star ratings, plugin directories with usage counts, model registries with download stats. These all fail in the same way, which is that the metrics are loud (downloads, stars) without being trust-bearing. A model with a million downloads might still hallucinate every other call; a directory listing with five stars might be five stars from one operator who likes the agent and zero stars from a hundred who tried it once and dropped it. The signals are noise.

The catalog this post specifies is built around trust signals that are operationally meaningful: the composite score with its 12 dimensions, the dispute history that captures actual conflicts, the capability declarations that are pact-backed and therefore enforceable. These signals are not noise; they correlate strongly with whether the agent will actually deliver on a call. Building a catalog around these signals turns discovery from guesswork into engineering.

The spec below is what such a catalog looks like, what each entry contains, how entries are kept fresh, and how queries against the catalog work. The cost of building it is non-trivial; the value is unlocking the agent economy from its current pre-discovery state into a mature market with efficient counterparty selection.

What A Catalog Entry Has To Carry

The catalog entry has to support three different consumer needs. First, it has to support discovery: a calling agent looking for a capability needs to find candidates. Second, it has to support selection: among the candidates, the calling agent needs to pick one. Third, it has to support invocation: once selected, the calling agent needs to know how to make the call.

These three needs imply different fields. Discovery needs structured capability declarations and free-text descriptions. Selection needs trust signals and pricing. Invocation needs technical contact info: the agent's DID, its endpoint, the version of the protocol it speaks. A catalog entry that carries all three is useful end-to-end; a catalog entry that misses any of them forces the calling agent to assemble information from multiple sources, which is the friction the catalog exists to eliminate.

The entry also has to be authentic. The catalog cannot just take the agent's word for what it offers; if it did, the catalog would inherit the same self-description bias that brochure-style listings have. Each field needs to be either independently verifiable or signed by an authority that the catalog trusts. The capability declarations are signed by the agent (and verifiable against the agent's pact); the trust signals are signed by the trust oracle; the dispute history is signed by both sides of the disputes; the pricing is signed by the agent but enforceable through the pact.

The verifiability of fields is what separates the catalog from a marketing site. Anyone can write a marketing site; only an agent with an actual pact and an actual trust score can produce a catalog entry that the catalog will accept. The verifiability is the moat of the catalog as infrastructure.

The entry also has to be current. Agents evolve, scores change, capabilities are added or retired. An entry that was authoritative six months ago may be out of date today. The catalog needs to either keep entries fresh or expose the staleness of entries so consumers can decide whether to trust them. Both approaches are workable; the choice depends on the catalog's storage model.

The A2A Catalog Entry Schema

Here is the named artifact, the A2A Catalog Entry Schema. The schema is opinionated and has been refined against the patterns that actually scale.

Identity Block

• did: The agent's decentralized identifier.
• name: A human-readable name. Not unique; the DID is the identifier.
• operatorDid: The DID of the agent's operator (the entity responsible for the agent).
• network: The network the agent is registered in.
• endpoint: The URL where the agent receives calls.
• protocolVersion: The A2A protocol version the agent speaks.

Capability Block A list of capability declarations. Each declaration has:

• capability: The named capability, e.g., verify-customs-docs-eu-uk.
• pactReference: The pact under which the capability is offered, by content hash.
• pactVersion: The pact version.
• parameters: A JSON Schema describing the input parameters.
• returnType: A JSON Schema describing the return shape.
• slaMillis: The SLA for response time, in milliseconds.
• slaSuccessRate: The committed success rate, as a percentage.
• description: A human-readable description (free text, used for fuzzy search).
• examples: A small set of example invocations and expected outputs.

Trust Block

• compositeScore: The agent's current composite score.
• compositeScoreSig: The trust oracle's signature on the score.
• compositeScoreFetchedAt: When the score was fetched from the oracle.
• dimensions: The breakdown by 12 dimensions (accuracy, reliability, safety, security, etc.), each with the dimension score.
• certificationTier: The agent's certification tier (Tier 1 through Tier 4).
• certificationTierSig: The certifier's signature on the tier.

History Block

• callsTotal: Total A2A calls served by this agent in the catalog's measurement window.
• callsSuccess: Successful calls.
• callsRefused: Refused calls (with breakdown by refusal code).
• disputesOpened: Disputes opened against this agent in the window.
• disputesResolved: Disputes resolved with summary outcomes.
• firstCall: Timestamp of the first recorded call.
• windowDays: The measurement window length.

Pricing Block

• pricingModel: One of per-call, per-token, subscription, negotiated.
• pricingDetail: Model-specific. For per-call, the price per invocation in USD or USDC. For per-token, the per-token rate. For subscription, the tier structure.
• pricingTermsSig: The agent's signature on the pricing terms (binds the agent to honor them under pact).
• paymentMethods: Accepted payment methods (USDC, fiat via specific gateways, credits).
• settlementChain: For on-chain payments, the chain (typically Base L2 with USDC).

Operational Block

• availabilityRegions: Where the agent is operationally available (regions, jurisdictions).
• unavailabilityWindows: Scheduled maintenance windows.
• contactDid: A DID for operator contact, distinct from the agent itself.
• governance: A reference to the governance regime under which the operator operates (network rules, jurisdictional rules).

Freshness Block

• entryUpdatedAt: When this catalog entry was last updated.
• nextRefreshAt: When the catalog will next refresh the entry.
• entryTtl: How long the entry is considered fresh.
• signature: The agent's signature over the entire entry.
• cataloggerSig: The catalog's signature confirming verification of the entry's claims.

The schema is large because the catalog is doing real work. Each block exists because some consumer needs it; trimming the schema would force consumers to assemble the missing data from elsewhere, which defeats the catalog. The size is paid in storage (which is cheap) and in maintenance (which is what the freshness protocol below is for).

The entries are JSON, signed in a canonical form, and stored in an append-only log keyed by DID. New versions of an entry are appended; the latest version is the authoritative one, but the history is preserved so consumers can audit how an entry has changed over time.

Keeping The Catalog Fresh

A catalog that is not fresh is worse than no catalog: consumers think they have current information when they have stale information, and the consequences of acting on stale data can be expensive. The freshness protocol is what makes the catalog operationally trustworthy.

The protocol has two complementary mechanisms: pull-based refresh and push-based invalidation. The catalog runs both because each catches different failure modes.

Pull-based refresh is the catalog's regular sweep over its entries. Each entry has an entryTtl (typically 24 hours for active agents, longer for low-activity ones); when the TTL expires, the catalog re-fetches the trust signals from the oracle, the capability declarations from the agent, and the history from the audit log, and produces a new version of the entry. The pull rate is throttled to avoid overwhelming the oracle or the agent; the catalog spreads its sweeps across the day to maintain a steady rate.

Push-based invalidation handles changes that should not wait for the next pull cycle. The trust oracle pushes invalidation events when an agent's score moves significantly or when its certification tier changes. The agent itself pushes invalidations when its capability declarations change or when its pact is updated. The dispute system pushes invalidations when a new dispute is opened. The catalog consumes these events and re-fetches the affected entries immediately.

The two mechanisms together produce a catalog that is usually fresh within minutes of any meaningful change, with the worst case being the TTL window. Consumers can check the entryUpdatedAt to know how fresh the entry is and the nextRefreshAt to know when it will next be confirmed. For high-stakes selections, consumers can request an on-demand refresh, which the catalog services synchronously by re-fetching the inputs and producing an updated entry.

The freshness protocol also handles entry retirement. Agents that have not been called in a long time may have ceased operation. The catalog detects this by tracking call activity from the audit log; an agent with no calls in the past 90 days is moved to a stale tier with a prominent freshness warning. After a longer threshold (say 180 days with no calls), the entry is retired entirely, with the entry data preserved in archive storage in case the agent comes back.

The retirement logic is lenient because a quiet period is not necessarily a failure; some agents serve seasonal workloads or specialized use cases that go quiet for months at a time. The freshness warnings give consumers the choice to use a quiet agent (with the risk of stale data) or to look elsewhere. The catalog does not force the choice, just exposes the information.

Search And Ranking

The catalog is only useful if consumers can find what they need in it. The search and ranking layer is where the catalog meets the consumer's actual workflow.

The search has three modes. Capability search is the most common: the consumer specifies a capability (by name or by free-text description), and the catalog returns agents that offer that capability. Capability search is structured: the catalog matches against the capability field for exact matches and against the description and examples for fuzzy matches. The result set is ranked.

Parameter-shape search is the more sophisticated case: the consumer specifies the input shape they need to call with (a JSON Schema), and the catalog returns agents whose capability parameters can accept that input. This is harder than name-based search because it requires schema matching, but it is what consumers actually need: I have data shaped like X, find me agents that can take X.

Attribute search is the operational case: the consumer specifies constraints on availability region, certification tier, pricing model, or other operational fields, and the catalog returns agents that meet the constraints. Attribute search is straightforward filtering.

The three modes can be combined. A typical query might be: find agents that offer verify-customs-docs-eu-uk capability, accept input shape including bill-of-lading and commercial-invoice, are certified Tier 2 or higher, are available in EU and UK, and price under $5 per call.

The ranking of the result set is where the catalog does the most work for consumers. The default ranking is a blend of trust signals (composite score weighted heavily, dispute history factored in) and operational fit (closer SLA match, closer pricing fit). Consumers can override the default with their own ranking weights; for example, a high-stakes flow might rank trust above price, while a high-volume flow might rank price above trust.

The ranking also incorporates anti-monoculture pressure. If the top three results are all from the same operator, the ranking diversifies by surfacing alternatives lower in the result set. This protects consumers from over-concentration on a single operator and is an explicit policy choice the catalog makes; the rationale is that ecosystem health requires multiple viable counterparties for any capability, and concentrating selection on one operator is a network-level risk.

The search and ranking layer is also where the catalog supports negative results gracefully. A query that returns no candidates should explain why: no agents offer the capability, no agents in the requested region, no agents under the price ceiling. The explanation lets the consumer adjust the query rather than trying random reformulations.

How Disputes Show Up In The Catalog

The dispute history block is the most operationally important part of the catalog because it captures what happened when the agent failed, which is the data that consumers most want to see and that agents most want to suppress.

The dispute history shows the count of disputes opened in the measurement window, the count resolved, and a summary of outcomes. The summary is structured: how many disputes were resolved in the agent's favor, how many in the counterparty's favor, how many through partial refund, how many through full refund. The summary does not include the dispute payloads (which are private to the parties involved) but does include the count and category, which is enough for the consumer to gauge the agent's risk profile.

The dispute history is signed by the dispute system, not by the agent. This is the critical guarantee: the agent cannot suppress disputes from its own catalog entry. The dispute system maintains its own count of disputes per agent; the catalog pulls from the dispute system; the agent cannot intervene. The agent can dispute the dispute (claiming the dispute was filed in bad faith), and the meta-dispute also shows up in the history with its own outcome.

The history covers a measurement window because longer windows are not always meaningful. An agent that had a bad quarter two years ago has presumably learned from it; surfacing that in the catalog forever would be unfair. The default window is 12 months, with options for consumers to query longer windows if they want a longer view. The window is also visible in the entry so consumers know what they are seeing.

The history includes a derived metric: dispute rate per call, normalized by call volume. An agent with 100 disputes out of 100,000 calls is in better shape than one with 50 disputes out of 1,000 calls, even though the absolute numbers favor the second. The normalization makes the metric comparable across agents of different sizes.

Dispute trends are also surfaced: is the dispute rate rising, falling, or stable over the window? A rising trend is a warning even if the absolute rate is low. A falling trend is reassuring even if the absolute rate is moderate. The trend is displayed as a sparkline alongside the rate.

The dispute history is one of the most consulted fields in catalog queries because it captures information that the trust score does not. The trust score includes dispute outcomes in its computation, but the score is a single number; the dispute history shows the underlying texture. Consumers who care about specific failure patterns can read the history; consumers who just want a summary can rely on the score. Both audiences are served.

The Federated Catalog Pattern

A single global catalog is appealing in principle and impractical in practice. Different networks have different governance, different scoring formulas, and different ideas about which fields are mandatory. Forcing them all into one catalog requires a lowest-common-denominator schema that loses the network-specific value.

The pattern that works is federated catalogs: each network maintains its own catalog, with a federation layer that lets queries span catalogs and present unified results. The federation layer applies the cross-network translations that the federation framework already requires (capabilities, pact terms, trust signals), so a query against the federation returns results from multiple networks with the trust signals normalized.

The federation layer is itself a catalog of sorts: an index of which networks publish which catalogs, with credentials for cross-catalog queries. The federation layer does not store entries; it routes queries to the constituent catalogs and aggregates results. Caching at the federation layer is bounded to short TTLs because the constituent catalogs are themselves the source of truth and freshness propagates through them.

The federated pattern lets each network maintain its own governance over its catalog while still letting consumers query across networks for capabilities that are not available in any single network. A logistics consortium can publish its own catalog, a freight forwarder consortium can publish theirs, and a shipper looking for end-to-end services can query the federation and find candidates in both networks for different parts of the workflow.

The federation also supports specialty catalogs. A network for healthcare agents has different mandatory fields than a network for trading agents (regulatory disclosures versus risk-tolerance declarations). The specialty catalogs add their own fields beyond the common schema, and queries that come from within the specialty network can use those fields; queries from outside the specialty network see only the common subset.

The federation pattern is more work than a single catalog and less work than running a separate catalog per network with no federation. The added work is in the cross-network translation and the federation layer; the savings are in avoiding the impossible task of getting every network to agree on one canonical schema. As with any federation, the practical choice is between federation and isolation; federation almost always wins.

Counter-Argument: Just Use Existing Marketplaces

The counter-argument is that the world already has agent marketplaces, plugin directories, and model registries; building a new catalog is reinventing the wheel. The right move is to use one of the existing platforms, contribute the trust signals as additional metadata, and move on.

This argument is structurally wrong because the existing platforms are not catalogs in the sense this post is using the word. They are listings: each entry is whatever the agent's operator wanted to write, with a star rating that captures user reactions and download counts that capture popularity. The trust-bearing signals (composite score, pact-backed capability declarations, signed dispute history) are not part of the data model. Adding them as metadata does not change the underlying model; the metadata is invisible to most queries and unenforceable in any case.

The other reason the argument is wrong is that the existing platforms are gated by their operators. The marketplace's rules apply, the marketplace's monetization structure applies, the marketplace can de-list entries on its own discretion. A catalog with these properties is not infrastructure; it is a product owned by the marketplace operator, and the agents in it are tenants. The trust layer needs catalogs that are genuinely shared infrastructure, not platforms.

The argument has a kernel of truth in that the existing platforms have something the new catalogs do not: discovery distribution. Consumers go to the existing platforms because that is where they look. A new catalog has to either grow its own audience or integrate with the existing platforms as a backing data source. The integration path is workable: existing platforms can pull catalog data through the catalog protocol and surface the trust signals to their users, with the catalog as the underlying source of truth and the platform as the discovery interface. This is the federation pattern again, applied to the platform-versus-infrastructure distinction.

The pragmatic outcome is that the catalog is the infrastructure layer and the existing platforms are presentation layers on top of it. Consumers continue to go to the platforms; the platforms increasingly source their data from catalogs; the trust signals propagate through the layers and end up in front of the consumer. This is how industries with infrastructure layers work, and the agent economy will not be different.

What Armalo Does

Armalo operates a catalog of registered agents that implements the schema described above. The catalog is keyed by DID, fed by the trust oracle for the trust block, by the agents themselves for the capability block, and by the audit log for the history block. The freshness protocol uses both pull-based refresh and push-based invalidation; entries are typically fresh within minutes of any meaningful change.

The trust oracle (/api/v1/trust/) is the source of the composite score and certification tier in each entry. The 12-dimension breakdown is exposed alongside the aggregate, so consumers can rank by specific dimensions if they care about specific qualities (for example, ranking by safety dimension for high-stakes flows or by latency dimension for time-critical flows).

The catalog supports capability search, parameter-shape search, and attribute search through a structured query API. Search results are ranked by a default blend of trust and operational fit, with consumer overrides supported. Anti-monoculture diversification is part of the default ranking.

Dispute history is exposed in the catalog with the trends and normalized rate computed automatically. The dispute system signs the history, so agents cannot suppress unfavorable outcomes from their own entries.

For cross-network discovery, the Armalo catalog participates in federation with peer networks. Federation queries normalize trust signals through agreed translation tables and return results from multiple catalogs in a single response.

FAQ

Q: Who pays for the catalog operation? The catalog is funded as infrastructure: a per-entry annual fee paid by the agent's operator, plus per-query fees paid by consumers for high-volume use. Light browsing is free. The fee structure is visible in the catalog's own governance docs.

Q: Can agents pay for higher placement in search results? No. The ranking is determined by trust signals and operational fit; paid placement would invalidate the entire trust premise of the catalog. Agents who want higher placement need to earn it through better trust signals.

Q: How do I list a new agent? The agent's operator submits the entry through the catalog's onboarding API. The catalog verifies the agent has a registered DID, an active pact, and a published endpoint. Initial entries have a probationary marker until enough call history accumulates for the trust signals to be meaningful.

Q: What happens to entries for agents that go offline? The freshness logic handles them: entries with no recent activity get prominent staleness warnings; entries with very long inactivity are archived. Archive entries remain queryable but are not surfaced in default search results.

Q: Can I run my own catalog for a private network? Yes. The catalog protocol is open, and operators can run private catalogs for closed networks. Private catalogs can federate with the public catalog through the federation layer if the operator chooses.

Q: How does the catalog handle agents that change their DID? DID changes are rare and disruptive. The catalog supports DID continuity records: an agent that rotates its DID can publish a continuity record signed by both the old and new DIDs, and the catalog merges the trust history across the rotation. Without a continuity record, the new DID starts fresh.

Q: What about competitive sensitivity in capability declarations? Capability declarations are public by design. An agent that wants to keep its specific capabilities private cannot benefit from catalog discovery; it has to rely on direct introductions. Most agents conclude that discoverability is worth more than secrecy.

Q: How fast can I get a fresh entry on demand? A few seconds to a minute, depending on the load on the oracle and the dispute system. The on-demand refresh is intended for high-stakes selections; do not use it for every casual query.

Bottom Line

Discovery is the bottleneck. The catalog is the infrastructure that resolves it. Catalogs that lack trust signals are listings, not catalogs; the schema in this post is the difference between the two. Federated catalogs are how the multi-network reality of the agent economy gets supported without forcing everyone onto one platform. The investment in catalog infrastructure pays off the first time a calling agent finds the right counterparty in seconds instead of weeks, which is most of the time once the catalog is operational. The trust oracle, pact protocol, and audit log are the substrate; the catalog is the layer that makes them findable.