Skip to content

Commit 9894b41

Browse files
allen-stephenallen-stephen
authored
feat: integrate A2A Inspector for ADK w/ A2A cloud run deployments (#452)
* feat: integrate A2A Inspector for ADK w/ A2A cloud run deployments * fix: improve error handling in A2A inspector setup
1 parent 0f4a6fc commit 9894b41

File tree

6 files changed

+200
-2
lines changed

6 files changed

+200
-2
lines changed

‎agent_starter_pack/agents/adk_a2a_base/README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,18 @@ This agent uses the `gemini-2.5-flash` model and is equipped with two simple too
1111
* `get_weather`: Simulates fetching weather (hardcoded for SF).
1212
* `get_current_time`: Simulates fetching the time (hardcoded for SF).
1313

14+
## Validating Your A2A Implementation
15+
16+
When deploying to **Cloud Run**, this template includes the **[A2A Protocol Inspector](https://github.com/a2aproject/a2a-inspector)** for validating your agent's A2A implementation.
17+
18+
```bash
19+
make inspector
20+
```
21+
22+
**Note:** The inspector currently supports JSON-RPC 2.0 only and is not yet compatible with Agent Engine's HTTP-JSON transport protocol.
23+
24+
For detailed setup instructions including local and remote testing workflows, refer to the `README.md` in your generated project.
25+
1426
## Additional Resources
1527

1628
### ADK Resources

‎agent_starter_pack/base_template/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -195,3 +195,6 @@ my_env.tfvars
195195
.saved_chats
196196
.env
197197
.requirements.txt
198+
199+
# A2A Inspector
200+
tools/a2a-inspector/

‎agent_starter_pack/base_template/Makefile‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,69 @@ playground-dev:
149149
@echo "Starting frontend dev server..."
150150
$(MAKE) ui
151151
{%- endif %}
152+
{%- if cookiecutter.is_adk_a2a and cookiecutter.deployment_target == 'cloud_run' %}
153+
# TODO: Remove 'and cookiecutter.deployment_target == 'cloud_run'' condition
154+
# when a2a-inspector adds HTTP-JSON transport support (currently JSON-RPC 2.0 only)
155+
156+
# ==============================================================================
157+
# A2A Protocol Inspector
158+
# ==============================================================================
159+
160+
# Launch A2A Protocol Inspector to test your agent implementation
161+
inspector: setup-inspector-if-needed build-inspector-if-needed
162+
@echo "==============================================================================="
163+
@echo "| 🔍 A2A Protocol Inspector |"
164+
@echo "==============================================================================="
165+
@echo "| 🌐 Inspector UI: http://localhost:5001 |"
166+
@echo "| |"
167+
{%- if cookiecutter.deployment_target == 'cloud_run' %}
168+
@echo "| 💡 Testing Locally: |"
169+
@echo "| Connect to: http://localhost:8000 |"
170+
@echo "| |"
171+
{%- endif %}
172+
@echo "| 💡 Testing Remote Deployment: |"
173+
{%- if cookiecutter.deployment_target == 'cloud_run' %}
174+
@echo "| Connect to your deployed Cloud Run URL |"
175+
@echo "| 🔐 See README for authentication setup |"
176+
{%- else %}
177+
@echo "| Connect to your deployed Agent Engine URL |"
178+
@echo "| 🔐 See README for authentication setup |"
179+
@echo "| |"
180+
@echo "| ℹ️ Note: Local testing requires deploying to Agent Engine first. |"
181+
@echo "| Local 'make playground' uses ADK web interface (not A2A endpoints) |"
182+
{%- endif %}
183+
@echo "==============================================================================="
184+
@echo ""
185+
cd tools/a2a-inspector/backend && uv run app.py
186+
187+
# Internal: Setup inspector if not already present (runs once)
188+
# TODO: Update to --branch v1.0.0 when a2a-inspector publishes releases
189+
setup-inspector-if-needed:
190+
@if [ ! -d "tools/a2a-inspector" ]; then \
191+
echo "" && \
192+
echo "📦 First-time setup: Installing A2A Inspector..." && \
193+
echo "" && \
194+
mkdir -p tools && \
195+
git clone --quiet https://github.com/a2aproject/a2a-inspector.git tools/a2a-inspector && \
196+
(cd tools/a2a-inspector && git -c advice.detachedHead=false checkout --quiet 24086e48b244b503dc6ccc976c9485bd6ec04ec8) && \
197+
echo "📥 Installing Python dependencies..." && \
198+
(cd tools/a2a-inspector && uv sync --quiet) && \
199+
echo "📥 Installing Node.js dependencies..." && \
200+
(cd tools/a2a-inspector/frontend && npm install --silent) && \
201+
echo "🔨 Building frontend..." && \
202+
(cd tools/a2a-inspector/frontend && npm run build --silent) && \
203+
echo "" && \
204+
echo "✅ A2A Inspector setup complete!" && \
205+
echo ""; \
206+
fi
207+
208+
# Internal: Build inspector frontend if needed
209+
build-inspector-if-needed:
210+
@if [ ! -f "tools/a2a-inspector/frontend/public/script.js" ]; then \
211+
echo "🔨 Building inspector frontend..."; \
212+
cd tools/a2a-inspector/frontend && npm run build; \
213+
fi
214+
{%- endif %}
152215

153216
# ==============================================================================
154217
# Backend Deployment Targets

‎agent_starter_pack/base_template/README.md‎

Lines changed: 70 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,11 @@ make install && make playground
7373
{%- endif %}
7474
{%- if cookiecutter.is_adk %}
7575
| `make register-gemini-enterprise` | Register deployed agent to Gemini Enterprise ([docs](https://googlecloudplatform.github.io/agent-starter-pack/cli/register_gemini_enterprise.html)) |
76-
{%- endif %}
76+
{%- endif -%}
77+
{%- endif -%}
78+
{# TODO: Remove 'and cookiecutter.deployment_target == 'cloud_run'' when inspector adds HTTP-JSON support #}
79+
{%- if cookiecutter.is_adk_a2a and cookiecutter.deployment_target == 'cloud_run' %}
80+
| `make inspector` | Launch A2A Protocol Inspector to test your agent implementation |
7781
{%- endif %}
7882
| `make test` | Run unit and integration tests |
7983
| `make lint` | Run code quality checks (codespell, ruff, mypy) |
@@ -84,6 +88,71 @@ make install && make playground
8488

8589
For full command options and usage, refer to the [Makefile](Makefile).
8690

91+
{# TODO: Remove 'and cookiecutter.deployment_target == 'cloud_run'' condition #}
92+
{# when a2a-inspector adds HTTP-JSON transport support (currently JSON-RPC 2.0 only) #}
93+
{%- if cookiecutter.is_adk_a2a %}
94+
{%- if cookiecutter.deployment_target == 'cloud_run' %}
95+
96+
## Using the A2A Inspector
97+
98+
This agent implements the [Agent2Agent (A2A) Protocol](https://a2a-protocol.org/), enabling interoperability with agents across different frameworks and languages.
99+
100+
The [A2A Inspector](https://github.com/a2aproject/a2a-inspector) provides the following core features:
101+
- 🔍 View agent card and capabilities
102+
- ✅ Validate A2A specification compliance
103+
- 💬 Test communication with live chat interface
104+
- 🐛 Debug with raw JSON-RPC 2.0 message console
105+
106+
### Local Testing
107+
108+
1. Start your agent:
109+
```bash
110+
make local-backend
111+
```
112+
113+
2. In a separate terminal, launch the A2A Protocol Inspector:
114+
```bash
115+
make inspector
116+
```
117+
118+
3. Open http://localhost:5001 and connect to `http://localhost:8000`
119+
120+
### Remote Testing
121+
122+
1. Deploy your agent:
123+
```bash
124+
make deploy
125+
```
126+
127+
2. Launch the inspector:
128+
```bash
129+
make inspector
130+
```
131+
132+
3. Get an authentication token:
133+
```bash
134+
{%- if cookiecutter.deployment_target == 'cloud_run' %}
135+
gcloud auth print-identity-token
136+
{%- else %}
137+
gcloud auth print-access-token
138+
{%- endif %}
139+
```
140+
141+
4. In the inspector UI at http://localhost:5001:
142+
- Add an HTTP header with name: `Authorization`
143+
- Set the value to: `Bearer <your-token-from-step-3>`
144+
{%- if cookiecutter.deployment_target == 'cloud_run' %}
145+
- Connect to your deployed Cloud Run URL
146+
{%- else %}
147+
- Connect to your Agent Engine URL using this format:
148+
```
149+
https://us-central1-aiplatform.googleapis.com/v1beta1/projects/{PROJECT_ID}/locations/{REGION}/reasoningEngines/{ENGINE_ID}/a2a/v1/card
150+
```
151+
Find your `PROJECT_ID`, `REGION`, and `ENGINE_ID` in the `latest_deployment_metadata.json` file created after deployment.
152+
{%- endif %}
153+
{%- endif %}
154+
{%- endif %}
155+
87156
{% if cookiecutter.is_adk_live %}
88157
## Usage
89158

‎tests/fixtures/makefile_hashes.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"adk_a2a_agent_engine": "7a8754bc3fe2b9c962e3642a4f27f208034ca4aeb7024de98e4035279b75f5c3",
3-
"adk_a2a_cloud_run": "68ce3fea8fc15dfe150cc937cae41297d013a2011169c3d207a4318a1484ab44",
3+
"adk_a2a_cloud_run": "8cc65fe177a0c98b6b2216a7c0ee96b10bc5bf003301fd6718e029b2636bc049",
44
"adk_base_agent_engine_no_data": "ef1024f7fdb57b5f30bff908dff6780113f436614c82c2bee9522d92926fe7d7",
55
"adk_base_cloud_run_no_data": "61aac5d45c3453c4be1e7d6d661679ebbe895a245306a35ebdfb5e1c316e9dec",
66
"adk_live_agent_engine": "ac543991afd7ec8e8f77d37213655bbd7271eed6008a53624153d2610c9de7c6",

‎tests/fixtures/makefile_snapshots/adk_a2a_cloud_run.makefile‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,57 @@ playground:
2929
# Launch local development server with hot-reload
3030
local-backend:
3131
uv run uvicorn test_a2a.server:app --host localhost --port 8000 --reload
32+
# TODO: Remove 'and cookiecutter.deployment_target == 'cloud_run'' condition
33+
# when a2a-inspector adds HTTP-JSON transport support (currently JSON-RPC 2.0 only)
34+
35+
# ==============================================================================
36+
# A2A Protocol Inspector
37+
# ==============================================================================
38+
39+
# Launch A2A Protocol Inspector to test your agent implementation
40+
inspector: setup-inspector-if-needed build-inspector-if-needed
41+
@echo "==============================================================================="
42+
@echo "| 🔍 A2A Protocol Inspector |"
43+
@echo "==============================================================================="
44+
@echo "| 🌐 Inspector UI: http://localhost:5001 |"
45+
@echo "| |"
46+
@echo "| 💡 Testing Locally: |"
47+
@echo "| Connect to: http://localhost:8000 |"
48+
@echo "| |"
49+
@echo "| 💡 Testing Remote Deployment: |"
50+
@echo "| Connect to your deployed Cloud Run URL |"
51+
@echo "| 🔐 See README for authentication setup |"
52+
@echo "==============================================================================="
53+
@echo ""
54+
cd tools/a2a-inspector/backend && uv run app.py
55+
56+
# Internal: Setup inspector if not already present (runs once)
57+
# TODO: Update to --branch v1.0.0 when a2a-inspector publishes releases
58+
setup-inspector-if-needed:
59+
@if [ ! -d "tools/a2a-inspector" ]; then \
60+
echo "" && \
61+
echo "📦 First-time setup: Installing A2A Inspector..." && \
62+
echo "" && \
63+
mkdir -p tools && \
64+
git clone --quiet https://github.com/a2aproject/a2a-inspector.git tools/a2a-inspector && \
65+
(cd tools/a2a-inspector && git -c advice.detachedHead=false checkout --quiet 24086e48b244b503dc6ccc976c9485bd6ec04ec8) && \
66+
echo "📥 Installing Python dependencies..." && \
67+
(cd tools/a2a-inspector && uv sync --quiet) && \
68+
echo "📥 Installing Node.js dependencies..." && \
69+
(cd tools/a2a-inspector/frontend && npm install --silent) && \
70+
echo "🔨 Building frontend..." && \
71+
(cd tools/a2a-inspector/frontend && npm run build --silent) && \
72+
echo "" && \
73+
echo "✅ A2A Inspector setup complete!" && \
74+
echo ""; \
75+
fi
76+
77+
# Internal: Build inspector frontend if needed
78+
build-inspector-if-needed:
79+
@if [ ! -f "tools/a2a-inspector/frontend/public/script.js" ]; then \
80+
echo "🔨 Building inspector frontend..."; \
81+
cd tools/a2a-inspector/frontend && npm run build; \
82+
fi
3283

3384
# ==============================================================================
3485
# Backend Deployment Targets

0 commit comments

Comments
 (0)