A2A PHP SDK

A PHP implementation of the A2A (Agent-to-Agent) Protocol (v0.3.0). The repository includes the unofficial library implementation and 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"

# (Optional, recommended in production) restrict push webhook hosts
export A2A_WEBHOOK_ALLOWLIST="hooks.example.com,callbacks.example.com"

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

Verified against the official A2A Test Compatibility Kit pinned at 0.3.0.beta5 (the latest v0.3.0-era TCK release) — every category passes:

The TCK is re-run on every pull request by CI (.github/workflows/ci.yml); the pin and upgrade procedure are documented in docs/tck-upgrade.md.

Configuration

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

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

# Full PHPUnit suite (unit + integration + e2e; the e2e suite boots the
# reference server and a webhook receiver on ephemeral ports by itself)
composer test

# Static analysis and coding standard
composer analyse        # PHPStan level 8 (baseline-ratcheted)
vendor/bin/phpcs -n     # PSR-12

# Official TCK, pinned version (see docs/tck-upgrade.md)
git clone --branch 0.3.0.beta5 https://github.com/a2aproject/a2a-tck.git ../a2a-tck
cd ../a2a-tck && pip install -e . && cd -
php -S localhost:8081 examples/complete_a2a_server.php &
python3 ../a2a-tck/run_tck.py --sut-url http://localhost:8081 --category all

The TCK run exercises JSON-RPC validation, streaming behaviour, push notification management and delivery, and task-state transitions. PHPUnit covers golden-path, edge-case, error-path and end-to-end scenarios for the PHP components.

Manual review guide

For reviewing a change or release by hand:

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.
• docs/tck-upgrade.md – TCK version pin and upgrade procedure.
• docs/UPGRADE-1.0.md – upgrade path to A2A protocol v1.0 (planning doc).
• docs/adr/ – architecture decision records.

For HTTPS deployment details, see A2A_HTTPS_IMPLEMENTATION.md and HTTPS_SUMMARY.md. Security policy: SECURITY.md. Release history: CHANGELOG.md.

Contributing

See CONTRIBUTING.md. In short: fork, branch, composer install, add golden-path/edge/error tests for the change, keep composer test, composer analyse, vendor/bin/phpcs -n and the pinned TCK green, then open a PR describing the validation steps.

License

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