Initial version of integration test kit (#445) · a2aproject/a2a-samples@1ca7bc0 · GitHub
Skip to content

Commit 1ca7bc0

Browse files
kdziedzic70Krzysztof Dziedzic
kdziedzic70
and
Krzysztof Dziedzic
authored
Initial version of integration test kit (#445)
# Description The pull request includes: * Implementation of a2a python sdk-v0.3 agent handling the Instruction proto exposed through jsonrpc, grpc and http_json * Implementation of the a2a go sdk-v0.3 agent handling the Instruction proto exposed through jsonrpc, grpc * Test runner implementation for verification of both SDKs compatibility - [x] Follow the [`CONTRIBUTING` Guide](https://github.com/a2aproject/a2a-samples/blob/main/CONTRIBUTING.md). Fixes #<issue_number_goes_here> 🦕 Co-authored-by: Krzysztof Dziedzic <dziedzick@google.com>
1 parent f140c6d commit 1ca7bc0

23 files changed

Lines changed: 2815 additions & 1 deletion

‎.github/workflows/linter.yaml‎

Lines changed: 1 addition & 1 deletion

‎itk/README.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# 🛠 ITK: Integration Test Kit
2+
3+
![Platform](https://img.shields.io/badge/Platform-Linux-orange.svg)
4+
![Go](https://img.shields.io/badge/Language-Go-blue.svg)
5+
![Python](https://img.shields.io/badge/Language-Python-green.svg)
6+
7+
ITK is a technical toolkit designed to verify compatibility across different A2A SDK implementations and versions. It uses a multi-hop traversal model to ensure that messages can be routed across Go and Python agents using varied transport protocols (JSON-RPC, gRPC, and REST).
8+
9+
---
10+
11+
## 🏗 Architecture
12+
13+
The kit operates by dispatching a single, deeply nested instruction through a chain of agents. Each "hop" in the chain requires the receiving agent to resolve the next target's agent card, map the requested transport, and forward the remaining instructions.
14+
15+
```mermaid
16+
graph LR
17+
Runner[Test Runner] -->|JSON-RPC| Py1[Python Agent]
18+
Py1 -->|JSON-RPC| Go1[Go Agent]
19+
Go1 -->|JSON-RPC| Py2[Python Agent]
20+
Py2 -->|gRPC| Go2[Go Agent]
21+
Go2 -->|gRPC| Py3[Python Agent]
22+
Py3 -->|HTTP/REST| PySelf[Python Self-Call]
23+
```
24+
25+
---
26+
27+
## ⛓ Multi-Hop Traversal Test
28+
29+
The primary verification suite executes a 6-hop traversal to test cross-SDK interop and protocol switching in a single session.
30+
31+
### Traversal Path
32+
33+
| Hop | Source | Target | Transport |
34+
| :--- | :--- | :--- | :--- |
35+
| 1 | Test Runner | Python v0.3 | JSON-RPC |
36+
| 2 | Python v0.3 | Go v0.3 | JSON-RPC |
37+
| 3 | Go v0.3 | Python v0.3 | JSON-RPC |
38+
| 4 | Python v0.3 | Go v0.3 | gRPC |
39+
| 5 | Go v0.3 | Python v0.3 | gRPC |
40+
| 6 | Python v0.3 | Python v0.3 | HTTP-JSON (REST) |
41+
42+
---
43+
44+
## 📂 Project Structure
45+
46+
- `agents/python/v03/`: Consolidated Python agent using the v0.3 SDK.
47+
- `agents/go/v03/`: Go agent implementation using the v0.3 Go SDK.
48+
- `run_tests.py`: Orchestration script that spawns agents and executes the traversal.
49+
- `pyproject.toml`: Root-level `uv` workspace configuration.
50+
51+
---
52+
53+
## 🚀 Getting Started
54+
55+
### Prerequisites
56+
- [uv](https://github.com/astral-sh/uv) for Python dependency management.
57+
- Go 1.21+ for the Go agent build.
58+
59+
### Running the Tests
60+
Execute the integration suite from the project root:
61+
```bash
62+
uv run run_tests.py
63+
```
64+
65+
The script will automatically clean up ports, spawn agents, wait for readiness, and verify the traversal traces.

‎itk/__init__.py‎

Whitespace-only changes.

‎itk/agents/go/v03/build_protos.sh‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
#!/bin/bash
2+
3+
# Script to build Go proto library from .proto files
4+
# Required dependencies: protoc, protoc-gen-go
5+
6+
# Ensure we are in the go directory
7+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
8+
cd "$SCRIPT_DIR" || exit 1
9+
10+
echo "Compiling protos from ../../../protos into pb/..."
11+
12+
# Create pb directory if it doesn't exist
13+
mkdir -p pb
14+
15+
# Run protoc
16+
# -I../../../protos: look for imports in the protos directory
17+
# --go_out=pb: output generated files into the pb directory
18+
# --go_opt=Minstruction.proto=itk/agents/go/v03/pb: map instruction.proto to the local pb package
19+
# --go_opt=paths=source_relative: use relative paths for output
20+
protoc --proto_path=../../../protos \
21+
--go_out=pb \
22+
--go_opt=Minstruction.proto=itk/agents/go/v03/pb \
23+
--go_opt=paths=source_relative \
24+
../../../protos/instruction.proto
25+
26+
echo "Done. Generated files are in pb/"

‎itk/agents/go/v03/go.mod‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
module itk/agents/go/v03
2+
3+
go 1.24.13
4+
5+
require (
6+
github.com/a2aproject/a2a-go v0.3.7
7+
golang.org/x/sync v0.15.0
8+
google.golang.org/grpc v1.73.0
9+
google.golang.org/protobuf v1.36.11
10+
)
11+
12+
require (
13+
github.com/google/uuid v1.6.0 // indirect
14+
golang.org/x/net v0.41.0 // indirect
15+
golang.org/x/sys v0.33.0 // indirect
16+
golang.org/x/text v0.26.0 // indirect
17+
google.golang.org/genproto/googleapis/api v0.0.0-20250715232539-7130f93afb79 // indirect
18+
google.golang.org/genproto/googleapis/rpc v0.0.0-20250715232539-7130f93afb79 // indirect
19+
)

‎itk/agents/go/v03/go.sum‎

Lines changed: 40 additions & 0 deletions

0 commit comments

Comments
 (0)