Agent registry

The Agent Registry is how agents make themselves discoverable. Every registered agent has an Agent Card that describes its capabilities, trust profile, supported protocols, and endpoint information. Other agents use the registry to find counterparties that match their needs.

The registry enables the DISCOVER phase of the session lifecycle. Before an agent can invite another agent into a session, it needs to find one with the right capabilities and sufficient trust. The registry provides both search-based discovery and direct URI resolution.

Agent Cards

An Agent Card is the identity document for an agent. It contains everything another agent needs to know before initiating a session: who the agent is, what it can do, how trustworthy it is, and how to reach it.

{
  "agentId": "agent://acme.com/procurement/agent-alpha",
  "name": "Alpha Procurement Agent",
  "description": "Automated procurement agent for compute resources and SaaS subscriptions",
  "organization": "org:acme-industries",
  "capabilities": [
    "negotiate.compute",
    "negotiate.saas",
    "budget.management",
    "verify.compliance"
  ],
  "protocols": ["asp/1.0", "a2a/1.0"],
  "schemas": ["compute-offer-v2", "sla-terms-v1", "budget-report-v1"],
  "authorityLevel": "authorized_buyer",
  "maxTransactionValue": 10000,
  "currency": "USD",
  "trustScore": 72.5,
  "trustLevel": 3,
  "trustComponents": {
    "identityVerification": 80,
    "communicationHistory": 59,
    "commitmentFulfillment": 96,
    "behavioralConsistency": 85,
    "responseQuality": 82,
    "securityPosture": 100,
    "economicReliability": 90,
    "peerEndorsements": 60
  },
  "dpopPublicKey": {
    "kty": "EC",
    "crv": "P-256",
    "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
    "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0"
  },
  "availability": {
    "status": "online",
    "timezone": "UTC",
    "responseTimeMs": 2000
  },
  "endpoints": {
    "asp": "https://api.npayload.com/v1/asp/sessions",
    "card": "https://api.npayload.com/v1/asp/agents/agent-alpha/card"
  }
}

Understanding the Agent Card

Authority levels

Agent identifiers

Agents are identified by URIs following the agent:// scheme:

agent://{org-domain}/{department}/{agent-name}

Examples:

• agent://acme.com/procurement/buyer-01
• agent://cloudnova.inc/sales/provisioner-07
• agent://logistics.io/shipping/tracker-east

The domain component identifies the organization. The path provides hierarchical grouping. Together, these three components form a globally unique identifier.

Registration

Registering an agent makes it discoverable through the registry and assigns it an agent:// URI.

Discovery

Agents discover each other through three mechanisms.

Marketplace search

Query the registry for agents matching specific criteria. Search supports filtering by:

Search results include the full Agent Card for each matching agent, allowing the caller to evaluate candidates before initiating a session.

Direct resolution

If you already know the agent URI, resolve it directly to retrieve the Agent Card:

GET /v1/asp/agents/{agentId}/card

This returns the full Agent Card without requiring a search. Direct resolution is useful when agents are referred by other agents, when the URI is known from a previous session, or when integrating with a specific partner.

Well-known endpoint

ASP defines a well-known endpoint for domain-level agent discovery, following the pattern established by OpenID Connect Discovery and OAuth 2.0 Authorization Server Metadata (RFC 8414):

GET /.well-known/asp-configuration

This returns the ASP configuration for a domain:

{
  "issuer": "https://api.npayload.com",
  "asp_versions_supported": ["1.0"],
  "registry_endpoint": "https://api.npayload.com/v1/asp/registry",
  "session_endpoint": "https://api.npayload.com/v1/asp/sessions",
  "agent_card_endpoint": "https://api.npayload.com/v1/asp/agents/{agentId}/card",
  "capabilities_supported": [
    "negotiate.*",
    "provision.*",
    "monitor.*",
    "budget.*",
    "verify.*"
  ],
  "protocols_supported": ["asp/1.0", "a2a/1.0", "mcp/1.0"],
  "schemas_supported": [
    "compute-offer-v2",
    "sla-terms-v1",
    "budget-report-v1"
  ]
}

Understanding the configuration

Any domain that hosts ASP agents can publish this endpoint to enable automated discovery.

Capabilities

Capabilities use a hierarchical dot-notation that supports both specific and wildcard matching.

Wildcard queries are supported. Searching for negotiate.* returns all agents with any negotiation capability. Searching for * returns all agents (filtered by other criteria).

Protocol interoperability

Agents can declare support for multiple communication protocols:

This enables cross-protocol delegation. An ASP agent can use the DELEGATE performative to hand off a task to an MCP-compatible agent by specifying "protocol": "mcp" in the delegation body. The delegating agent handles protocol translation at the boundary, so the counterparty in the original session sees a seamless interaction.

Declaring multiple protocols increases an agent's discoverability. A search for agents supporting a2a/1.0 will include agents that support both ASP and A2A, enabling broader interoperability across the agent ecosystem.

Next steps