A2A protocol features in Apicurio Registry

Apicurio Registry implements the A2A (Agent-to-Agent) protocol for AI agent discovery, orchestration, and lifecycle management.

A2A protocol overview

With the A2A protocol, AI agents can discover and communicate with each other through standardized endpoints. Apicurio Registry serves as both an A2A agent and an agent registry.

Apicurio Registry as an A2A agent

Apicurio Registry provides its own capabilities, including schema validation, search, and artifact management.

Apicurio Registry as an agent registry

Apicurio Registry stores and discovers other agents' Agent Cards.

Table 1. Apicurio Registry dual-role A2A architecture
Apicurio Registry as an A2A agent Apicurio Registry as an agent card registry

Endpoint: /.well-known/agent.json

Built-in skills:

  • schema-validation

  • schema-search

  • artifact-management

  • compatibility-check

  • agent-discovery

Endpoints:

  • /.well-known/agents

  • /.well-known/agents/{groupId}/{artifactId}

Capabilities:

  • Store agent cards as AGENT_CARD artifacts

  • Search by skill, capability, or input/output mode

  • Version management and compatibility checking

A2A configuration properties

You can control A2A features by using the following configuration properties.

Table 2. A2A configuration properties
Property Default Description

apicurio.a2a.enabled

false

Enable or disable A2A protocol support

apicurio.a2a.agent.name

Apicurio Registry

Name of the registry as an A2A agent

apicurio.a2a.agent.description

API and Schema Registry with A2A Agent support

Description of the registry agent

apicurio.a2a.agent.version

app version

Agent version (defaults to application version)

apicurio.a2a.agent.url

registry base URL

URL reported in the Agent Card supportedInterfaces entry. Defaults to the base URL of the registry.

apicurio.a2a.agent.provider.organization

Apicurio

Provider organization name

apicurio.a2a.agent.provider.url

https://www.apicur.io

Provider organization URL

apicurio.a2a.agent.capabilities.streaming

false

Whether streaming is supported

apicurio.a2a.agent.capabilities.push-notifications

false

Whether push notifications are supported

apicurio.a2a.agent.protocol-version

1.0

A2A protocol version reported in the Agent Card and in its supported interfaces

apicurio.a2a.agent.documentation-url

not set

URL of the registry agent documentation, reported as documentationUrl when set

apicurio.a2a.agent.icon-url

not set

URL of the registry agent icon, reported as iconUrl when set

apicurio.a2a.agent.auth.api-key.enabled

false

Advertise API key authentication with the X-API-Key header in the Agent Card security schemes

A2A well-known endpoints

Apicurio Registry provides the following well-known endpoints for A2A agent discovery and retrieval.

GET /.well-known/agent.json

Retrieves the Agent Card for the Apicurio Registry instance. This endpoint requires no authentication. The same card is available at /.well-known/agent-card.json.

Response: Agent Card JSON document

{
  "name": "Apicurio Registry",
  "description": "API and Schema Registry with A2A Agent support",
  "version": "3.3.3",
  "protocolVersion": "1.0",
  "supportedInterfaces": [
    {
      "url": "http://localhost:8080",
      "protocolBinding": "http+json",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "Apicurio",
    "url": "https://www.apicur.io"
  },
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "extendedAgentCard": false
  },
  "skills": [
    {
      "id": "schema-validation",
      "name": "Schema Validation",
      "description": "Validate schemas against format specifications (Avro, JSON Schema, Protobuf, OpenAPI, etc.)",
      "tags": ["schema", "validation", "avro", "json-schema", "protobuf", "openapi"]
    },
    {
      "id": "schema-search",
      "name": "Schema Search",
      "description": "Search for schemas and APIs in the registry by name, description, labels, or content",
      "tags": ["schema", "search", "discovery"]
    }
  ],
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "securitySchemes": {
    "bearer": {
      "type": "httpAuth",
      "scheme": "Bearer"
    }
  }
}

The example shows two of the five built-in skills. The securitySchemes object lists only the mechanisms that are enabled: bearer when OIDC authentication is enabled, basic when basic authentication is enabled, and apiKey when apicurio.a2a.agent.auth.api-key.enabled is true. The Agent Card includes documentationUrl and iconUrl only when you configure the corresponding properties.

GET /.well-known/agents

Searches for registered Agent Cards with filtering support. This endpoint requires no authentication. When any authentication mechanism is enabled, the search returns only the Agent Cards that the caller has permission to view, based on the apicurio.agent.visibility label.

Table 3. Query parameters for /.well-known/agents
Parameter Type Description

name

string

Filter by artifact name or artifact ID. A value without matches anywhere in the name or ID. Use as a prefix or suffix wildcard, for example weather*.

skill

string (repeatable)

Filter by skill ID

capability

string (repeatable)

Filter by capability (for example, streaming:true). Append :false to require that a capability is absent or disabled.

inputMode

string (repeatable)

Filter by input mode (for example, text, image)

outputMode

string (repeatable)

Filter by output mode

offset

integer

Pagination offset (default: 0)

limit

integer

Pagination limit (default: 20, maximum: 500)
Example request
curl "http://localhost:8080/.well-known/agents?skill=translation&capability=streaming:true"
Example response: AgentSearchResults
{
  "count": 1,
  "agents": [
    {
      "groupId": "ai-agents",
      "artifactId": "translator-agent",
      "name": "Translation Agent",
      "description": "Translates text between languages",
      "owner": "alice",
      "createdOn": 1756720530000,
      "supportedInterfaces": [
        {
          "url": "http://translator:9001",
          "protocolBinding": "http+json",
          "protocolVersion": "1.0"
        }
      ],
      "skills": ["translation"],
      "capabilities": {
        "streaming": true,
        "pushNotifications": false
      }
    }
  ]
}

The count field is the total number of matching Agent Cards, not the number of entries in the current page. The skills array lists skill IDs only. To get skill names and descriptions, retrieve the full Agent Card from /.well-known/agents/{groupId}/{artifactId}.

GET /.well-known/agents/{groupId}/{artifactId}

Retrieves a specific registered Agent Card.

Path parameters

  • groupId - The group containing the agent card

  • artifactId - The artifact ID of the agent card

    Query parameters

  • version (optional) - Specific version (defaults to latest)

    Response: Agent Card JSON document

Agent visibility model

Agent Cards support three visibility levels, controlled by the apicurio.agent.visibility artifact label. When any authentication mechanism is enabled, GET /.well-known/agents and the AI Catalog and ARD endpoints described in AI Catalog and ARD discovery enforce visibility.

Table 4. Agent visibility levels
Visibility Behavior

public

Visible to everyone, including unauthenticated clients

entitled

Visible to callers who can read artifacts: a registry role (sr-readonly, sr-developer or sr-admin) when role-based authorization is enabled, any authenticated user when apicurio.auth.authenticated-read-access.enabled is set or a trusted proxy has authorized the request, and unauthenticated clients when apicurio.auth.anonymous-read-access.enabled is set (this is the default)

private

Visible only to the artifact owner and registry administrators
Visibility label example
curl -X PUT "http://localhost:8080/apis/registry/v3/groups/my-agents/artifacts/my-agent" \
  -H "Content-Type: application/json" \
  -d '{"labels": {"apicurio.agent.visibility": "public"}}'

How entitlements work: Apicurio Registry maps the A2A community entitlement concept to its existing RBAC model:

  • Groups act as organizational namespaces

  • Entitling a client = granting read access to the group containing the Agent Card artifacts

  • Client authentication happens in an external identity provider, such as Keycloak or another OIDC provider

  • No new authorization primitives are required

Table 5. Discovery and entitlement configuration properties
Property Default Description

apicurio.a2a.default-visibility

entitled

Default visibility for new Agent Card artifacts (public, entitled, or private)

Visibility labels control which Agent Cards appear in /.well-known/agents search results and in the AI Catalog and ARD responses. When you retrieve a card by ID through /.well-known/agents/{groupId}/{artifactId} or the core REST API, only read authorization applies. Apicurio Registry does not check the visibility label.

When no authentication mechanism is configured (OIDC, basic, proxy header, Kubernetes, or form), Apicurio Registry skips visibility filtering and all agents are visible to all users.

Agent Card artifact type

Apicurio Registry stores Agent Cards as artifacts with type AGENT_CARD. You can create Agent Cards by using the REST API and you can validate them against the A2A specification JSON schema.

Agent Card creation example
curl -X POST "http://localhost:8080/apis/registry/v3/groups/ai-agents/artifacts" \
  -H "Content-Type: application/json" \
  -d '{
    "artifactId": "my-agent",
    "artifactType": "AGENT_CARD",
    "firstVersion": {
      "version": "1.0.0",
      "content": {
        "contentType": "application/json",
        "content": "{\"name\": \"My Agent\", \"skills\": [{\"id\": \"task\", \"name\": \"Task Execution\"}]}"
      }
    }
  }'

Agent Cards must conform to the A2A specification:

Agent Card JSON schema
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["name"],
  "properties": {
    "name": {"type": "string"},
    "description": {"type": "string"},
    "version": {"type": "string"},
    "url": {"type": "string", "format": "uri"},
    "provider": {
      "type": "object",
      "properties": {
        "organization": {"type": "string"},
        "url": {"type": "string", "format": "uri"}
      }
    },
    "capabilities": {
      "type": "object",
      "properties": {
        "streaming": {"type": "boolean"},
        "pushNotifications": {"type": "boolean"}
      }
    },
    "skills": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["id", "name"],
        "properties": {
          "id": {"type": "string"},
          "name": {"type": "string"},
          "description": {"type": "string"},
          "tags": {"type": "array", "items": {"type": "string"}},
          "examples": {"type": "array", "items": {"type": "string"}}
        }
      }
    },
    "defaultInputModes": {"type": "array", "items": {"type": "string"}},
    "defaultOutputModes": {"type": "array", "items": {"type": "string"}},
    "authentication": {
      "type": "object",
      "properties": {
        "schemes": {"type": "array", "items": {"type": "string"}}
      }
    }
  }
}

Auto-generating Agent Cards from OpenAPI specifications

If you already document your API with OpenAPI, you can embed Agent Card metadata directly in your OpenAPI specification’s info block using the x-agent-card vendor extension, instead of authoring and maintaining a separate AGENT_CARD artifact by hand. Apicurio Registry detects the extension, assembles a valid Agent Card from it, and stores it as a companion artifact.

Table 6. Enabling OpenAPI-to-Agent-Card auto-generation
Property Default Description

apicurio.a2a.openapi-integration.enabled

false

Auto-generate a companion AGENT_CARD artifact from the x-agent-card OpenAPI vendor extension

apicurio.a2a.openapi-integration.sync-on-update.enabled

true

Update the generated Agent Card whenever its source OpenAPI artifact is updated
apicurio.a2a.openapi-integration.enabled is an experimental property. You must also set apicurio.features.experimental.enabled=true to use it.
Example x-agent-card extension
openapi: "3.0.0"
info:
  title: Weather API
  description: Retrieves weather forecasts by city
  version: "1.0.0"
  x-agent-card:
    capabilities: {}
    skills:
      - id: get-weather
        name: Get Weather
        description: Retrieve the current weather for a city
        tags: [weather]
    defaultInputModes: [text]
    defaultOutputModes: [text]
servers:
  - url: https://weather.example.com

When Apicurio Registry publishes an OPENAPI artifact version with an x-agent-card extension under info, it:

  1. Derives any of name, description, and version that the extension does not explicitly set, from the OpenAPI document’s own info.title, info.description, and info.version.

  2. Derives supportedInterfaces from servers[] only when omitted, expanding server variables using their string defaults and using http+json as the binding. Explicit malformed values are rejected rather than replaced. Relative URLs require explicit absolute supportedInterfaces; the registry does not guess a base URL. Publishers must ensure the advertised endpoint actually implements A2A; OpenAPI alone does not establish this.

  3. Validates the assembled Agent Card against the same A2A v1.0 schema used for AGENT_CARD artifacts. If the assembled card is not valid, the OpenAPI write itself is rejected (HTTP 400) with a RuleViolationException, and nothing is persisted.

  4. Creates or updates <artifactId>-agent-card in the same group, checking companion ownership and applying its configured rules. Companion failure is logged and leaves the successful source write intact; rejected companion content is never persisted.

Ordinary DRAFT creates/edits do not generate published companions. Transitioning a draft to a published state validates and generates from its edited content. Dry-run requests do not write companions. Published updates re-read the source tip, and conditional target-version writes prevent a concurrent manual version from being superseded.

Required Agent Card fields with no OpenAPI equivalent — capabilities, skills, defaultInputModes, and defaultOutputModes — must always be supplied explicitly in the extension.

Provenance and sync labels

The companion artifact and its source OpenAPI artifact are marked with apicurio.a2a.openapi-agent-card.* labels:

Label Meaning

apicurio.a2a.openapi-agent-card.generated (on the companion)

true if this artifact was generated by this feature

apicurio.a2a.openapi-agent-card.source-group-id / .source-artifact-id (on the companion)

Identifies the source OpenAPI artifact this companion was generated from

apicurio.a2a.openapi-agent-card.generated-hash (on each generated companion version)

Canonical hash committed with that generated content. Missing or mismatched provenance stops automatic synchronization.

apicurio.a2a.openapi-agent-card.source-global-id (on each generated companion version)

The exact source version; deletion/recreation of the source does not silently adopt the old companion.

apicurio.a2a.openapi-agent-card.artifact-id (on the source OpenAPI artifact)

The artifact ID of its generated companion Agent Card

If you edit the generated Agent Card artifact directly, Apicurio Registry detects this the next time the source OpenAPI artifact changes (the companion’s latest version content no longer matches its recorded generated hash) and skips the sync rather than overwriting your edit, logging a warning instead.

If an artifact already exists with the same name as the companion (<artifactId>-agent-card) but was not generated by this feature, Apicurio Registry leaves it untouched and logs a warning rather than overwriting it.

Labels are editable provenance/navigation hints, never authorization grants. Owner-only access is checked independently on the companion. Generation provenance is stored atomically with each version; failure updating the source navigation link can be repaired on a subsequent unchanged-content synchronization. A manually edited version without generation provenance is preserved. Regeneration after manual changes requires an explicit user decision, not deletion of its hash label.

Known limitations

  • REST publication paths trigger generation: first published version, new published version, ifExists=UPDATE/FIND_OR_CREATE_VERSION, and publication of an edited draft. KafkaSQL REST requests journal both writes; replay itself does not generate an extra companion. Confluent-compatible APIs and read-only GitOps/KubernetesOps imports do not trigger generation.

  • Source and companion are separate artifacts, not one transaction. Companion errors leave the source intact; repeated optimistic conflicts are bounded and logged. A later publication retries from current source content.

  • Deleting the source OpenAPI artifact does not delete its generated companion Agent Card.

  • AsyncAPI does not currently support the x-agent-card extension.

Agent Card validation rules

Agent Cards have three validation levels that control how much validation occurs when you create or update an Agent Card.

Level Description

NONE

No validation.

SYNTAX_ONLY

Validates that the content is syntactically valid JSON and is a JSON object.

FULL

Complete schema validation including:

  • Required name field (non-empty string)

  • description and version fields

  • supportedInterfaces array, where each interface has url, protocolBinding, and protocolVersion

  • provider object with organization and url

  • skills array, where each skill has id and name

  • capabilities object with boolean values

  • defaultInputModes and defaultOutputModes arrays

  • Authentication and security scheme validation

  • Valid JSON structure

Agent Card compatibility rules

When you version Agent Cards, Apicurio Registry enforces compatibility rules to ensure that changes do not break existing clients.

Compatible changes (allowed):

  • Adding new skills

  • Adding new capabilities

  • Adding authentication schemes

  • Adding input or output modes

Incompatible changes (can break clients):

  • Removing skills

  • Removing or disabling capabilities

  • Removing supported interfaces (matched by URL and protocol binding)

  • Changing the protocol version on an existing interface

  • Removing security schemes

  • Removing input or output modes

Automatic label extraction for Agent Cards

Apicurio Registry automatically extracts labels from Agent Cards for search. You can use these labels for efficient capability-based discovery by using the Apicurio Registry label search.

Label pattern Source

agent_card:skill:<id>

Each skill ID in the skills array

agent_card:capability:<name>

Each enabled capability in the capabilities object (where value is true)

agent_card:inputmode:<mode>

Each value in the defaultInputModes array

agent_card:outputmode:<mode>

Each value in the defaultOutputModes array

agent_card:protocolbinding:<binding>

Each protocolBinding value in the supportedInterfaces array

agent_card:securityscheme:<name>

Each key in the securitySchemes object

agent_card:tag:<value>

Each value in the tags array within each skill (deduplicated across skills)

Apicurio Registry built-in A2A skills

Apicurio Registry operates as an A2A agent with the following built-in skills.

Skill ID Description

schema-validation

Validate schemas against format specifications (Avro, JSON Schema, Protobuf, OpenAPI, AsyncAPI, GraphQL, Thrift, WSDL, XSD)

schema-search

Search for schemas and APIs in the registry by name, labels, or content

artifact-management

Create, update, and manage schema artifacts with full versioning

compatibility-check

Check schema compatibility between versions by using configurable rules

agent-discovery

Discover and manage A2A agent cards stored in the registry

LLM lifecycle management

A2A integration includes full LLM lifecycle management with additional artifact types, including MODEL_SCHEMA and PROMPT_TEMPLATE.

The MODEL_SCHEMA artifact type defines input and output schemas for LLM agents:

MODEL_SCHEMA artifact type
{
  "$schema": "https://apicurio.io/schemas/model-schema/v1",
  "modelId": "sentiment-analysis-output",
  "provider": "a2a-demo",
  "version": "1.0.0",
  "output": {
    "type": "object",
    "required": ["sentiment", "confidence"],
    "properties": {
      "sentiment": {"type": "string", "enum": ["positive", "negative", "neutral"]},
      "confidence": {"type": "number", "minimum": 0, "maximum": 1}
    }
  }
}

The PROMPT_TEMPLATE artifact type stores versioned prompt templates with variable support:

PROMPT_TEMPLATE artifact type
templateId: sentiment-analysis
name: Sentiment Analysis Prompt
version: "1.0.0"

template: |
  Analyze the sentiment of the following message:

  MESSAGE: {{customerMessage}}

  Respond with JSON containing sentiment and confidence.

variables:
  customerMessage:
    type: string
    required: true
    description: The message to analyze

metadata:
  outputSchema: urn:apicurio:llm-agents.schemas/sentiment-output

Agent Cards can reference their schemas and prompts by using URN references:

Artifact links
{
  "name": "Sentiment Agent",
  "skills": [
    {
      "id": "sentiment-analysis",
      "name": "Sentiment Analysis",
      "outputSchema": "urn:apicurio:llm-agents.schemas/sentiment-agent-output",
      "promptTemplate": "urn:apicurio:llm-agents.prompts/sentiment-agent-prompt"
    }
  ]
}

Multi-agent workflow example

You can chain context across multiple agents in a pipeline. The a2a-real-world-integration example in the Apicurio Registry repository demonstrates this pattern.

Table 7. Context chaining pipeline
Step Input context Output

1. Sentiment agent

{{original}}

{"sentiment": "very_negative", "urgency": "critical"}

2. Issue analyzer

{{original}} + {{sentiment}}

{"priority": "P1", "issue_type": "delayed_delivery"}

3. Response generator

{{original}} + {{sentiment}} + {{analysis}}

{"response": "Dear customer, I sincerely apologize…​"}

4. Translation agent

{{response}}

{"translated": "Estimado cliente, le pido disculpas…​"}

To run the example application locally, clone the Apicurio Registry repository and run the following commands:

Example commands
cd examples/a2a-real-world-integration
docker-compose up -d
mvn clean compile exec:java

The Web UI is available at localhost:9000.

Additional resources

Java SDK usage for A2A

You can use the Java SDK to discover agents and register Agent Cards programmatically.

Agent discovery example
RegistryClient client = RegistryClientFactory.create(
    RegistryClientOptions.create("http://localhost:8080/apis/registry/v3"));

// Search for agents with specific skill
var agents = client.wellKnown().agents()
    .get(config -> {
        config.queryParameters.skill = List.of("translation");
        config.queryParameters.limit = 10;
    });

for (var agent : agents.getAgents()) {
    System.out.println("Found: " + agent.getName() + " @ " + agent.getUrl());
}
Agent Card registration example
CreateArtifact artifact = new CreateArtifact();
artifact.setArtifactId("my-agent");
artifact.setArtifactType("AGENT_CARD");

CreateVersion version = new CreateVersion();
version.setVersion("1.0.0");

VersionContent content = new VersionContent();
content.setContentType("application/json");
content.setContent(agentCardJson);
version.setContent(content);

artifact.setFirstVersion(version);

client.groups().byGroupId("ai-agents").artifacts()
    .post(artifact, config -> {
        config.queryParameters.ifExists = IfArtifactExists.FIND_OR_CREATE_VERSION;
    });

A2A REST API endpoints

The following table describes the core A2A endpoints available in Apicurio Registry.

Endpoint Method Description

/.well-known/agent.json

GET

Get the registry’s own Agent Card

/.well-known/agents

GET

Search registered Agent Cards

/.well-known/agents/{groupId}/{artifactId}

GET

Get a specific Agent Card by artifact ID

/apis/registry/v3/groups/{groupId}/artifacts

POST

Create an Agent Card artifact (type: AGENT_CARD)

/apis/registry/v3/groups/{groupId}/artifacts/{artifactId}

GET

Get Agent Card artifact metadata

/apis/registry/v3/groups/{groupId}/artifacts/{artifactId}/versions/{version}/content

GET

Get Agent Card content

A2A troubleshooting

Use the following information to troubleshoot common issues with A2A features in Apicurio Registry.

A2A endpoints return 404

Set apicurio.a2a.enabled=true in your configuration:

apicurio.a2a.enabled=true
Agent Card validation fails

Verify the following conditions:

  • The name field is present and non-empty.

  • Skills have both id and name fields.

  • Capabilities are boolean values.

  • The JSON is well-formed.

Search returns no results

Verify the following conditions:

  • Agent Cards are stored with type AGENT_CARD.

  • The registry extracted labels correctly (check artifact labels).

  • Search filters match stored values exactly.

Additional resources