Implement a2a registry support

[carlesarnal]

Disclaimer

I'm holding this until the official spec is released.

Summary

Implements full A2A (Agent-to-Agent) Agent Card Registry support for Apicurio Registry, including a dedicated A2A API, agent discovery endpoint, and compatibility checking. Fixes #7003

Root Cause

This change enables Apicurio Registry to serve as an Agent Registry for A2A protocol applications. The A2A protocol (Agent-to-Agent) is Google's standard for AI agent communication and discovery.
Agent Cards are JSON metadata documents that describe an AI agent's capabilities, skills, endpoints, and authentication requirements.

The implementation goes beyond the original prototype scope to include:

• A separate A2A API (/apis/a2a/v1) distinct from the core registry API, designed for future compatibility with the A2A registry specification
• Agent discovery endpoint following the .well-known convention
• Full content validation, compatibility checking, and content extraction

Changes

New A2A API (separate from v3 core API)

• common/src/main/resources/META-INF/openapi-a2a.json: New OpenAPI 3.0.3 specification defining the A2A Agent API at /apis/a2a/v1/agents with endpoints for:
  • GET /agents - List all registered agents
  • POST /agents - Register a new agent
  • GET /agents/search - Search agents by skill, capability, or tag
  • GET /agents/{agentId} - Get agent details
  • PUT /agents/{agentId} - Update an agent
  • DELETE /agents/{agentId} - Delete an agent
  • GET /agents/{agentId}/versions - List agent versions
• common/pom.xml: Added codegen execution for A2A API generation with io.apicurio.registry.rest.a2a package

A2A API Implementation

• app/src/main/java/io/apicurio/registry/rest/a2a/impl/AgentsResourceImpl.java: Implementation of the AgentsResource interface with agent CRUD operations, search by capability/skill/tag, and
  version management
• app/src/main/java/io/apicurio/registry/rest/a2a/AgentDiscoveryResource.java: Discovery endpoint at /.well-known/agents.json returning a catalog of all registered agents

New Artifact Type

• common/src/main/java/io/apicurio/registry/types/ArtifactType.java: Added AGENT_CARD artifact type constant

Schema Utilities (schema-util module)

• AgentCardArtifactTypeUtilProvider.java: Artifact type provider registering all Agent Card utilities with priority 10
• AgentCardContentAccepter.java: Content accepter validating JSON content type
• AgentCardContentExtractor.java: Extracts name and description from Agent Card JSON for artifact metadata
• AgentCardContentValidator.java: Full/Syntax validation checking required fields (name), skill structure, and JSON validity
• AgentCardCompatibilityChecker.java: Compatibility checker implementing BACKWARD and FORWARD compatibility rules:
  • Skills cannot be removed (backward compatibility)
  • New skills with required inputs require defaults (forward compatibility)
  • Capability downgrades not allowed

Tests

• integration-tests/.../AgentCardIT.java: Integration tests covering artifact type, validation, discovery endpoint, agents API, and agent search
• AgentCardCompatibilityCheckerTest.java: Unit tests for backward/forward compatibility scenarios
• AgentCardContentValidatorTest.java: Unit tests for JSON validation with test fixtures

Test Fixtures

• agentcard-valid.json, agentcard-minimal.json, agentcard-missing-name.json, agentcard-invalid-json.json, agentcard-invalid-skills.json

Known Limitations

This is a POC implementation with the following known limitations that should be addressed before production use:

Scalability Issues

• Hard-coded limit of 1000 agents: Both searchAgents() and the discovery endpoint (/.well-known/agents.json) load up to 1000 agents into memory for filtering. This won't scale for large deployments.
• In-memory filtering: Agent search by skill/capability/tag loads all agents and filters in memory rather than using database-level queries.
• No pagination on discovery endpoint: The /.well-known/agents.json endpoint returns all agents without pagination support.

API Response Issues

• createAgent() doesn't return the assigned agentId: When an agent is created without specifying an agentId, the server generates one, but the response only contains the AgentCard content without the assigned ID.
• getAgentVersions() response lacks version information: The endpoint returns SearchedAgent objects but doesn't include the actual version identifier for each entry.

Code Quality Issues

• Generic exception handling: Uses RuntimeException instead of proper JAX-RS exceptions (e.g., BadRequestException, InternalServerErrorException) for appropriate HTTP status codes.
• Duplicated constants: The AGENTS_GROUP_ID = "agents" constant is defined separately in both AgentsResourceImpl and AgentDiscoveryResource.
• AgentCatalog inner class: Should be a proper bean in the beans package or defined in the OpenAPI spec for consistency.

Functional Limitations

• AND-only filter logic: The search filters (skill, capability, tag) use AND logic only. No support for OR queries.
• No database-level search optimization: Skill/capability/tag searches could be optimized with JSON path queries at the database level.

Test plan

• Unit tests pass: AgentCardCompatibilityCheckerTest, AgentCardContentValidatorTest
• Integration tests pass: AgentCardIT (artifact type, validation, discovery, API, search)
• AGENT_CARD appears in artifact type list endpoint
• Agent Card JSON can be registered via /apis/a2a/v1/agents API
• Invalid Agent Card JSON is rejected with VALIDITY rule enabled
• Discovery endpoint /.well-known/agents.json returns agent catalog
• Agent search by skill, capability, and tag returns correct results
• Compatibility rules are enforced on agent updates
• All existing tests continue to pass
• Test with SQL storage variant
• Test with KafkaSQL storage variant

[carlesarnal]

Closing for now as the discussion is still ongoing. I'm re-opening #7007 that's contained here as a previous step, since the agen card spec is already official.