README

A PHP implementation of the A2A (Agent-to-Agent) Protocol v0.3.0. The repository includes a fully compliant sample server, strict JSON-RPC validation logic, task management utilities, streaming support, and push notification handling.

Quick start

# Install dependencies
composer install

# Start the reference server
php -S localhost:8081 examples/complete_a2a_server.php

# (Optional) expose an authenticated extended card
export A2A_DEMO_AUTH_TOKEN="example-secret"

The server exposes the JSON-RPC endpoint at http://localhost:8081/ and publishes the agent card at http://localhost:8081/.well-known/agent-card.json.

Compliance status

Category	Result
Mandatory	25 / 25 tests passing
Capability	14 / 14 tests passing
Quality	12 / 12 tests passing
Features	15 / 15 tests passing

Results are produced with the official A2A Test Compatibility Kit using python3 run_tck.py --category all.

Implementation highlights

Strict JSON-RPC 2.0 validation with precise error codes for malformed requests, invalid identifiers, or incorrect parameter payloads.
Task lifecycle support with history, metadata, artifact persistence, and idempotent cancellation semantics.
Server-Sent Events streaming, including the tasks/resubscribe snapshot feed that replays history before emitting the current task status.
Push notification configuration management with consistent list, get, set, and delete behaviour backed by the shared storage layer.
Authenticated extended agent card endpoint gated by the A2A_DEMO_AUTH_TOKEN environment variable for demonstration purposes.

Reference server methods

Method	Description	Notes
`get_agent_card`	Returns the public agent card.	JSON-RPC response.
`agent/getAuthenticatedExtendedCard`	Returns the extended card when `Authorization: Bearer` or `X-API-Key` matches `A2A_DEMO_AUTH_TOKEN`.	JSON-RPC response.
`message/send`	Processes an inbound message and returns the task snapshot.	Validates message parts and metadata.
`message/stream`	Starts an SSE session for live task updates while processing a streamed message.	Emits JSON-RPC envelopes over SSE.
`tasks/send`	Accepts an explicit task and message payload, ensuring reuse of existing task IDs.	Sets status to working and finalises with handler result.
`tasks/get`	Retrieves the latest task state, history, and artifacts.	Supports the optional `historyLength` parameter.
`tasks/cancel`	Cancels a running task once and reports an error on repeated cancellation attempts.	Uses `TaskManager::cancelTask`.
`tasks/resubscribe`	Emits task history and current status over SSE for reconnecting clients.	Utilises stored history snapshots.
`tasks/pushNotificationConfig/set`	Persists a push configuration for a task.	Stores webhook data in shared storage.
`tasks/pushNotificationConfig/get`	Returns the stored configuration for a task.	Null when absent.
`tasks/pushNotificationConfig/list`	Lists all stored configurations, optionally filtered by `taskId`.	Returns an array of summary objects.
`tasks/pushNotificationConfig/delete`	Removes the configuration for a task.	Returns `null` on success.
`ping`	Health-check method.	Returns `{ "status": "pong" }`.

Refer to docs/api-reference.md for complete request and response schemas.

Working with Server-Sent Events

The reference server streams events from the same JSON-RPC endpoint when the message/stream or tasks/resubscribe methods are invoked. Responses are encoded as JSON-RPC payloads and delivered as SSE events with IDs set to the task or message identifiers. The StreamingServer guarantees that a resubscribe replay includes every stored message history entry before the terminal task status update.

Testing

# Start the server in one terminal
php -S localhost:8081 examples/complete_a2a_server.php

# Run the TCK from the sibling repository
cd ../a2a-tck
python3 run_tck.py --sut-url http://localhost:8081 --category all

# Run the PHPUnit suite from the project root
cd ../a2a-php
composer test

The TCK run exercises JSON-RPC validation, streaming behaviour, push notification management, and task-state transitions. PHPUnit covers unit and integration scenarios for the PHP components.

Documentation

Additional documentation lives in the docs/ directory:

docs/README.md – high-level overview and architecture notes.
docs/api-reference.md – detailed method and data model reference.
docs/protocol-compliance.md – TCK summary and behavioural guarantees.

For HTTPS deployment details, see A2A_HTTPS_IMPLEMENTATION.md and HTTPS_SUMMARY.md.

Contributing

Fork the repository and create a feature branch.
Install dependencies with composer install.
Add unit tests or TCK scenarios covering the change.
Run composer test and (optionally) python3 ../a2a-tck/run_tck.py.
Open a pull request describing the change and validation steps.

License

Distributed under the Apache License 2.0. See LICENSE for the full text.

andreibesleaga / a2a-php

Maintainers

Details