Pluggable Storage Alpha

Description

This alpha release expands a2a-cpp with a more production-oriented storage layer and stronger backend conformance coverage.

The main highlight is the introduction of pluggable server-side stores, including the existing in-memory backend and an optional PostgreSQL-backed implementation. This makes it possible to run the SDK with persistent task and push-notification storage while keeping the lightweight in-memory path available for examples, tests, and local development.

Highlights

• Added a pluggable store factory layer for task and push-notification stores.
• Added optional PostgreSQL-backed task storage.
• Added optional PostgreSQL-backed push-notification config storage.
• Added shared conformance tests to verify behavior parity between in-memory and PostgreSQL stores.
• Added local PostgreSQL development tooling and documentation.
• Updated CI/TCK flows to validate PostgreSQL-backed behavior.
• Improved example executor wiring so stores and task-id generation can be injected.
• Improved push-notification config ordering semantics across backends.
• Kept PostgreSQL support optional via CMake, so the default lightweight SDK build remains available.

Notes

This is still an alpha release. APIs and storage internals may continue to evolve before a stable 1.0 release.

PostgreSQL support is optional and must be enabled explicitly at build time with:

-DA2A_ENABLE_POSTGRES_STORE=ON

Use this release if you want to experiment with persistent A2A task/push-notification storage, run stronger backend conformance checks, or start integrating the SDK in environments where in-memory storage is not enough.

Push notifications, shared HTTP client, and full mandatory TCK compatibility

v0.1.0-alpha.4

This alpha release expands a2a-cpp from a core A2A C++ SDK into a more complete conformance-focused client/server SDK with push notification support, shared outbound HTTP infrastructure, and broader transport coverage.

Highlights

• Added first-class push notification support across the SDK:
  • push notification store abstraction;
  • in-memory push notification store;
  • push notification service;
  • push delivery client;
  • REST, JSON-RPC, and gRPC server/client wiring for push config create/get/list/delete.
• Added a shared optional libcurl-backed outbound HTTP layer:
  • new a2a::http target;
  • default HTTP requester/fetcher support for client transports and discovery;
  • push delivery now uses the shared HTTP client.
• Improved A2A transport coverage:
  • REST / HTTP+JSON;
  • JSON-RPC;
  • gRPC;
  • streaming support paths;
  • task listing filters and pagination paths;
  • push notification config pagination.
• Added and improved conformance-focused SUT wiring for TCK runs.
• Added more reusable SDK helpers:
  • AgentCardBuilder;
  • response/artifact builder helpers;
  • URL normalization helpers;
  • shared HTTP constants and protocol method constants.
• Expanded CI and validation:
  • mandatory A2A TCK workflow;
  • benchmark workflow and thresholds;
  • coverage/lint/test improvements.

TCK status

The SDK is validated in CI against the A2A TCK mandatory suite for:

• gRPC
• JSON-RPC
• HTTP+JSON

The current report shows OVERALL COMPATIBILITY: 100.0% for tested, non-skipped requirements. The level table’s non-zero Failed count should not be interpreted as actual failed executed tests unless the report also contains a FAILED REQUIREMENTS section.

Build notes

• C++20 is required.
• CMake minimum version is 3.25.
• gRPC and protobuf are required.
• libcurl-backed default outbound HTTP support is optional and controlled by A2A_ENABLE_LIBCURL.

Compatibility

This is still an alpha release. Public APIs may continue to evolve before a stable 1.0.0 SDK release.

TCK + Performance Gate Alpha

a2a-cpp v0.1.0-alpha.3

This is an alpha release of a2a-cpp, a C++20 SDK for building Agent2Agent (A2A) protocol clients and servers.

The release focuses on protocol compatibility, CI validation, documentation, examples, and performance-regression visibility. The SDK remains pre-1.0, so public APIs may still change before a stable release.

Highlights

C++20 A2A SDK foundation

• Provides public a2a::core, a2a::client, and a2a::server libraries.
• Supports core A2A workflows including client/server APIs, agent card discovery, task lifecycle APIs, streaming, and authentication hooks.
• Uses generated protobuf types for the A2A protocol model.
• Targets A2A protocol version 1.0.

Transport support

This alpha includes support for the main A2A transport paths:

• REST / HTTP JSON
• JSON-RPC
• gRPC

TCK conformance validation

The main branch includes CI validation for mandatory A2A TCK conformance.

The TCK workflow runs against the deterministic SUT and validates the mandatory category across:

• grpc
• jsonrpc
• http_json

This makes the release a stronger alpha baseline for protocol compatibility testing.

Performance benchmarks

This release includes an optional SDK microbenchmark suite.

The benchmark suite uses C++ / Google Benchmark to measure SDK internals directly, including:

• proto/JSON serialization
• task store operations
• task lifecycle logic
• transport mux routing
• REST and JSON-RPC transport handling
• Agent Card generation
• UUIDv7 task ID generation
• HTTP adapter parsing and serialization

A Go-based benchmark runner parses Google Benchmark JSON output, checks thresholds from benchmarks/thresholds.json, and generates Markdown summaries for CI.

Benchmarks are intended to run in Release mode and are not built by default.

Build and package integration

The SDK supports:

• CMake 3.25+
• C++20 toolchains
• protobuf and gRPC dependencies
• vcpkg manifest usage
• installable CMake package exports

A preliminary Conan recipe exists, but Conan packaging is not yet treated as a fully supported or validated release path.

Examples

The release includes runnable examples for:

• discovery-only client
• REST client
• JSON-RPC client
• gRPC client
• streaming client
• minimal custom executor server
• list tasks client
• cancel task client
• push notification config client
• interceptor client
• auth policy server

Documentation

The documentation site covers:

• installation and quickstart
• client workflows
• discovery
• task operations
• server/custom executor setup
• REST, JSON-RPC, and gRPC transports
• streaming
• authentication
• CMake and vcpkg build paths
• API reference entry point

Known limitations

• This is still an alpha release.
• Public APIs may change before 1.0.
• Conan packaging is preliminary and not yet validated as a supported package distribution path.
• vcpkg public registry publication is not yet complete; the repository currently provides vcpkg manifest support.
• Performance thresholds are intended as CI regression guards, not as absolute performance guarantees across all machines.

Suggested validation before publishing

• Verify CI is green on main.
• Verify the TCK conformance workflow passes.
• Verify benchmark thresholds pass in the benchmark job.
• Verify examples build and run through the examples smoke workflow.
• Confirm the release tag matches the package metadata version line.

SDK service-layer, routing, and production-readiness update

v0.1.0-alpha.2

This alpha release continues the stabilization of a2a-cpp as a C++ SDK for building and consuming A2A-compatible agents.

The main focus of this release is moving more behavior from examples/ad-hoc code into reusable SDK components: task lifecycle management, production-ready task ID generation, HTTP routing, HTTP request/response handling, Agent Card construction, and shared URL utilities.

Highlights

• Added a reusable server-side task lifecycle service.
• Added injectable task ID generation with UUIDv7-based production IDs.
• Added deterministic sequential task IDs for tests and examples.
• Added a reusable HTTP adapter for request parsing and response writing.
• Added TransportMux for routing REST and JSON-RPC traffic through a shared HTTP entry point.
• Added fluent AgentCardBuilder API with transport presets.
• Added shared URL target extraction utilities.
• Improved task history append, deduplication, telemetry, and idempotency behavior.
• Improved Agent Card HTTP caching support.
• Expanded unit and interop coverage across server transports and SDK utilities.
• Added clang-tidy check profiling support for better static-analysis performance visibility.

New SDK components

Task lifecycle service

This release introduces TaskLifecycleService, a shared service-layer component for task creation, task updates, status transitions, history appending, and task ID resolution.

This reduces duplicated task-handling logic in examples and transports and makes lifecycle behavior easier to test and reuse.

Injectable task ID generation

The SDK now supports pluggable task ID generation through a TaskIdGenerator abstraction.

The default production strategy uses UUIDv7-style task IDs with a stable task- prefix, while examples and tests can inject SequentialTaskIdGenerator for deterministic behavior.

Example production-style ID:

task-0198f2d4-7c4a-7b21-9c02-dc6e7f2b8e91

This replaces earlier example-level task ID derivation from messageId.

TransportMux

a2a::server::TransportMux provides centralized HTTP request routing for SDK-backed servers.

It supports:

• registering REST and JSON-RPC routes;
• priority-based route matching;
• path normalization;
• default-path routing;
• structured route-miss responses;
• preserving query strings when forwarding requests to transports.

This is especially useful for hosting REST and JSON-RPC transports behind one HTTP listener.

HTTP adapter

The SDK now includes a reusable HTTP/1.1 adapter for request parsing and response serialization.

It centralizes:

• request-line parsing;
• header parsing;
• case-insensitive Content-Length handling;
• request-body framing;
• response writing;
• reason phrase mapping;
• cross-platform socket closing helpers.

The TCK HTTP SUT now uses this shared adapter instead of ad-hoc HTTP parsing logic.

AgentCardBuilder

The new fluent AgentCardBuilder API makes Agent Card construction easier and less error-prone.

It includes helper presets for:

• REST / HTTP+JSON
• JSON-RPC
• gRPC

It also adds validation for common Agent Card issues such as missing fields, invalid URLs, and duplicate interfaces.

URL utilities

A new a2a::core::ExtractTargetPath utility centralizes URL target extraction and normalization.

It supports configurable suffix handling for:

• path only;
• path + query;
• path + query + fragment.

Examples and tests now use the shared utility instead of local URL parsing helpers.

Task history and idempotency improvements

This release adds a more explicit task history append model in the SDK task store.

New behavior includes:

• centralized AppendTaskHistory(...);
• configurable deduplication policies;
• message ID and fingerprint-based deduplication;
• strict chronological append behavior;
• structured dedupe telemetry;
• history projection helpers;
• artifact projection helpers;
• documentation for SDK idempotency behavior.

This makes retry handling more deterministic across transports and easier to observe in production.

Agent Card caching

RestServerTransport now supports configurable Agent Card caching metadata.

Supported response headers include:

• ETag
• Cache-Control
• Last-Modified

This helps clients, proxies, and gateways cache the well-known Agent Card response more efficiently.

Tooling and CI improvements

• Consolidated TCK conformance execution across gRPC, JSON-RPC, and HTTP+JSON.
• Added clang-tidy check profiling support.
• Continued expanding unit coverage for:
  • gRPC server transport;
  • JSON-RPC server transport;
  • REST transport;
  • task store;
  • HTTP adapter;
  • TransportMux;
  • AgentCardBuilder;
  • URL utilities;
  • task ID generation.

Behavior changes

• Example task IDs are now generated through the service-layer task ID generator instead of being derived directly from messageId.
• Production task IDs are intended to be opaque SDK-generated IDs.
• Example/test paths may use deterministic sequential IDs such as task-test-1.
• HTTP routing through TransportMux preserves query strings when forwarding to transports, which is required for features such as historyLength.

Known limitations

This is still an alpha release.

APIs may continue to change before a stable release. The current focus remains SDK structure, protocol correctness, reusable server/client components, and conformance-driven behavior.

Push notification support remains limited and may return protocol-level “not supported” responses depending on the transport/path.

Recommended use

Use this release to:

• build early A2A C++ agent prototypes;
• test SDK-level REST, JSON-RPC, and gRPC integration;
• experiment with reusable server-side task lifecycle handling;
• validate Agent Card construction and transport discovery flows;
• prepare for production-oriented integration work while the API is still alpha.

Avoid treating this release as a stable API contract.

Tag

v0.1.0-alpha.2

Initial TCK-compliant A2A C++ SDK alpha

v0.1.0-alpha.1

This is the first alpha release of a2a-cpp, a C++ SDK implementation for the A2A protocol.

The main goal of this release is protocol correctness and interoperability. The SDK now includes client and server building blocks for the main A2A transports, with CI coverage and TCK conformance validation in place.

Highlights

• Initial C++ SDK support for A2A protocol integrations.
• TCK-compatible behavior across the currently supported transports:
  • gRPC
  • HTTP+JSON
  • JSON-RPC
• Server-side transport implementations for building A2A-compatible agents.
• Client-side transport implementations for calling A2A-compatible agents.
• Agent Card discovery and transport resolution support.
• Shared task lifecycle handling, including:
  • SendMessage
  • GetTask
  • CancelTask
  • ListTasks
  • streaming/subscribe flows where supported
• In-memory task store and example executor utilities for samples and tests.
• Structured protocol error handling aligned with A2A expectations.
• CI workflow coverage for build, lint, tests, interop checks, and TCK conformance.

New in this release

TransportMux HTTP routing component

This release includes a2a::server::TransportMux, a reusable HTTP routing/multiplexing component for dispatching requests to REST and JSON-RPC transports. It supports route registration, priority-based selection, path normalization, default-path handling, structured route-miss responses, and diagnostics through last_route_miss(). This replaces ad-hoc routing in the interop SUT and makes mixed HTTP transport setups easier to wire. :contentReference[oaicite:0]{index=0}

Improved TCK compatibility

Several fixes were made to align SDK behavior with the A2A TCK, including task lifecycle semantics, terminal task handling, history length handling, JSON-RPC response envelopes, gRPC error details, artifact/message serialization, and streaming/subscription behavior.

Better examples and interop coverage

The release includes updated samples and interop tests that exercise the SDK through real transport paths rather than only isolated unit-level logic.

Known limitations

This is an alpha release. APIs may still change before a stable v0.1.0 or v1.0.0.

Current focus is protocol correctness and SDK structure. Production hardening, richer documentation, packaging polish, and broader real-world integration examples are expected to improve in later releases.

Push notification configuration support is intentionally limited in the current implementation and may return protocol-level “not supported” responses depending on transport/path.

Recommended use

Use this release to:

• experiment with A2A agent/client integration in C++;
• validate transport-level behavior against A2A-compatible systems;
• build early prototypes;
• review SDK API design before stabilization.

Avoid treating this alpha as a frozen API surface.

Tag

v0.1.0-alpha.1