google-agents-cli-extensions 1.14.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (107) hide show
  1. core/claude/README.md +35 -0
  2. core/claude/template/.agents/skills/agents-cli-claude/SKILL.md +106 -0
  3. core/claude/template/.agents/skills/agents-cli-claude/references/claude.md +386 -0
  4. core/claude/template/.agents/skills/agents-cli-claude/references/migrate-claude-agent.md +318 -0
  5. core/claude/template/.agents/skills/agents-cli-claude/references/migrate-from-aws.md +132 -0
  6. core/claude/template/.dockerignore +28 -0
  7. core/claude/template/.env +18 -0
  8. core/claude/template/.env.example +17 -0
  9. core/claude/template/.template/templateconfig.yaml +31 -0
  10. core/claude/template/AGENTS.md +33 -0
  11. core/claude/template/Dockerfile +55 -0
  12. core/claude/template/agent_config/README.md +9 -0
  13. core/claude/template/agents-cli-extension.yaml +49 -0
  14. core/claude/template/app/__init__.py +15 -0
  15. core/claude/template/app/agent.py +49 -0
  16. core/claude/template/app/app_utils/a2a.py +245 -0
  17. core/claude/template/app/app_utils/bq_analytics/__init__.py +124 -0
  18. core/claude/template/app/app_utils/bq_analytics/recorder.py +593 -0
  19. core/claude/template/app/app_utils/bq_analytics/redaction.py +209 -0
  20. core/claude/template/app/app_utils/bq_analytics/schema.py +394 -0
  21. core/claude/template/app/app_utils/bq_analytics/tables.py +104 -0
  22. core/claude/template/app/app_utils/bq_analytics/uploader.py +188 -0
  23. core/claude/template/app/app_utils/claude.py +297 -0
  24. core/claude/template/app/app_utils/completions.py +225 -0
  25. core/claude/template/app/app_utils/conversation.py +29 -0
  26. core/claude/template/app/app_utils/memory_bank.py +308 -0
  27. core/claude/template/app/app_utils/project_settings.py +91 -0
  28. core/claude/template/app/app_utils/reasoning_engine.py +237 -0
  29. core/claude/template/app/app_utils/remote_agents.py +349 -0
  30. core/claude/template/app/app_utils/remote_auth.py +159 -0
  31. core/claude/template/app/app_utils/replies.py +143 -0
  32. core/claude/template/app/app_utils/session_store.py +174 -0
  33. core/claude/template/app/app_utils/settings.py +24 -0
  34. core/claude/template/app/app_utils/telemetry/__init__.py +114 -0
  35. core/claude/template/app/app_utils/telemetry/call_counts.py +44 -0
  36. core/claude/template/app/app_utils/telemetry/cli_relay.py +266 -0
  37. core/claude/template/app/app_utils/telemetry/config.py +133 -0
  38. core/claude/template/app/app_utils/telemetry/logs.py +175 -0
  39. core/claude/template/app/app_utils/telemetry/metrics.py +270 -0
  40. core/claude/template/app/app_utils/telemetry/request_flush.py +104 -0
  41. core/claude/template/app/app_utils/telemetry/subagent_spans.py +80 -0
  42. core/claude/template/app/app_utils/telemetry/traces.py +166 -0
  43. core/claude/template/app/app_utils/turn_events.py +463 -0
  44. core/claude/template/app/app_utils/turn_options.py +219 -0
  45. core/claude/template/app/app_utils/workspaces.py +65 -0
  46. core/claude/template/app/fast_api_app.py +71 -0
  47. core/claude/template/app/feature_tools.py +27 -0
  48. core/claude/template/pyproject.toml +100 -0
  49. core/claude/template/scripts/eval_generate.py +340 -0
  50. core/claude/template/scripts/publish.py +66 -0
  51. core/claude/template/scripts/run.py +85 -0
  52. core/claude/template/scripts/unsupported.py +48 -0
  53. core/claude/template/tests/eval/datasets/basic-dataset.json +31 -0
  54. core/claude/template/tests/eval/eval_config.yaml +17 -0
  55. core/claude/template/tests/eval/response_quality.py +60 -0
  56. core/claude/template/tests/integration/test_server_e2e.py +168 -0
  57. core/claude/template/tests/load_test/.results/.placeholder +0 -0
  58. core/claude/template/tests/load_test/README.md +24 -0
  59. core/claude/template/tests/load_test/load_test.py +118 -0
  60. core/claude/template/tests/unit/conftest.py +63 -0
  61. core/claude/template/tests/unit/helpers.py +32 -0
  62. core/claude/template/tests/unit/test_a2a.py +432 -0
  63. core/claude/template/tests/unit/test_bq_analytics.py +928 -0
  64. core/claude/template/tests/unit/test_bq_redaction.py +89 -0
  65. core/claude/template/tests/unit/test_claude.py +825 -0
  66. core/claude/template/tests/unit/test_completions.py +369 -0
  67. core/claude/template/tests/unit/test_fast_api_app.py +59 -0
  68. core/claude/template/tests/unit/test_feature_tools.py +55 -0
  69. core/claude/template/tests/unit/test_memory_bank.py +625 -0
  70. core/claude/template/tests/unit/test_reasoning_engine.py +295 -0
  71. core/claude/template/tests/unit/test_remote_agents.py +517 -0
  72. core/claude/template/tests/unit/test_telemetry.py +991 -0
  73. core/claude/template/tests/unit/test_turn_events.py +309 -0
  74. core/claude/template/tests/unit/test_turn_options.py +394 -0
  75. core/claude/template/uv.lock +3029 -0
  76. core/langchain/README.md +54 -0
  77. core/langchain/template/.agents/skills/agents-cli-langchain/SKILL.md +84 -0
  78. core/langchain/template/.agents/skills/agents-cli-langchain/references/langchain.md +120 -0
  79. core/langchain/template/.agents/skills/agents-cli-langchain/references/samples.md +42 -0
  80. core/langchain/template/.template/templateconfig.yaml +32 -0
  81. core/langchain/template/AGENTS.md +35 -0
  82. core/langchain/template/agents-cli-extension.yaml +54 -0
  83. core/langchain/template/app/__init__.py +19 -0
  84. core/langchain/template/app/agent.py +61 -0
  85. core/langchain/template/app/app_utils/a2a.py +176 -0
  86. core/langchain/template/app/app_utils/content.py +37 -0
  87. core/langchain/template/app/app_utils/telemetry.py +154 -0
  88. core/langchain/template/app/fast_api_app.py +68 -0
  89. core/langchain/template/langgraph.json +7 -0
  90. core/langchain/template/pyproject.toml +102 -0
  91. core/langchain/template/scripts/_content.py +40 -0
  92. core/langchain/template/scripts/eval_generate.py +202 -0
  93. core/langchain/template/scripts/publish.py +59 -0
  94. core/langchain/template/scripts/run.py +59 -0
  95. core/langchain/template/scripts/unsupported.py +48 -0
  96. core/langchain/template/tests/eval/datasets/basic-dataset.json +16 -0
  97. core/langchain/template/tests/eval/eval_config.yaml +32 -0
  98. core/langchain/template/tests/eval/response_quality.py +60 -0
  99. core/langchain/template/tests/integration/test_server_e2e.py +173 -0
  100. core/langchain/template/tests/load_test/.results/.placeholder +0 -0
  101. core/langchain/template/tests/load_test/README.md +20 -0
  102. core/langchain/template/tests/load_test/load_test.py +82 -0
  103. core/langchain/template/uv.lock +3820 -0
  104. google_agents_cli_extensions-1.14.2.dist-info/METADATA +133 -0
  105. google_agents_cli_extensions-1.14.2.dist-info/RECORD +107 -0
  106. google_agents_cli_extensions-1.14.2.dist-info/WHEEL +4 -0
  107. google_agents_cli_extensions-1.14.2.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,432 @@
1
+ # Copyright 2026 Google LLC
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+ """The A2A layer in `app/app_utils/a2a.py`: its agent card and executor."""
16
+
17
+ from __future__ import annotations
18
+
19
+ import asyncio
20
+ import json
21
+ import logging
22
+ import threading
23
+ import uuid
24
+ from unittest.mock import AsyncMock, patch
25
+
26
+ import pytest
27
+ from claude_agent_sdk.types import (
28
+ AssistantMessage,
29
+ ClaudeAgentOptions,
30
+ ResultMessage,
31
+ StreamEvent,
32
+ TextBlock,
33
+ )
34
+ from fastapi import FastAPI
35
+ from fastapi.testclient import TestClient
36
+ from opentelemetry import trace
37
+ from opentelemetry.sdk.trace import TracerProvider
38
+
39
+ from app.app_utils import a2a
40
+ from app.app_utils.a2a import advertised_base_url
41
+ from app.app_utils.telemetry import FASTAPI_TELEMETRY
42
+
43
+
44
+ def test_agent_runtime_card_points_at_the_passthrough(monkeypatch):
45
+ """A first deploy without Agent Identity gets no APP_URL from agents-cli."""
46
+ monkeypatch.delenv("APP_URL", raising=False)
47
+ monkeypatch.setenv("GOOGLE_CLOUD_AGENT_ENGINE_ID", "123")
48
+ monkeypatch.setenv("GOOGLE_CLOUD_AGENT_ENGINE_LOCATION", "us-central1")
49
+ monkeypatch.setenv("GOOGLE_CLOUD_PROJECT", "my-project")
50
+
51
+ assert advertised_base_url() == (
52
+ "https://us-central1-aiplatform.googleapis.com/reasoningEngines/v1"
53
+ "/projects/my-project/locations/us-central1/reasoningEngines/123/api"
54
+ )
55
+
56
+
57
+ _CALLER_TRACE_ID = "4bf92f3577b34da6a3ce929d0e0e4736"
58
+
59
+
60
+ def _trace_id_seen_by_a_turn(telemetry: dict) -> str | None:
61
+ """Send one A2A message with a caller's traceparent; the turn's trace id."""
62
+ seen = []
63
+
64
+ async def fake_stream_turn(prompt, options, conversation_id, user_id=None):
65
+ context = trace.get_current_span().get_span_context()
66
+ seen.append(format(context.trace_id, "032x") if context.is_valid else None)
67
+ return
68
+ yield
69
+
70
+ with patch.object(a2a, "stream_turn", fake_stream_turn):
71
+ app = FastAPI(telemetry={**telemetry, "tracer_provider": TracerProvider()})
72
+ a2a.add_a2a_routes(app)
73
+ response = TestClient(app).post(
74
+ "/a2a/app",
75
+ json={
76
+ "jsonrpc": "2.0",
77
+ "id": "1",
78
+ "method": "message/send",
79
+ "params": {
80
+ "message": {
81
+ "messageId": uuid.uuid4().hex,
82
+ "role": "user",
83
+ "parts": [{"kind": "text", "text": "hi"}],
84
+ }
85
+ },
86
+ },
87
+ headers={"traceparent": f"00-{_CALLER_TRACE_ID}-00f067aa0ba902b7-01"},
88
+ )
89
+ assert response.status_code == 200
90
+ [trace_id] = seen
91
+ return trace_id
92
+
93
+
94
+ def test_a_turn_ignores_the_callers_trace_context():
95
+ assert _trace_id_seen_by_a_turn(FASTAPI_TELEMETRY) != _CALLER_TRACE_ID
96
+ # FastAPI's default would continue the caller's trace.
97
+ assert _trace_id_seen_by_a_turn({}) == _CALLER_TRACE_ID
98
+
99
+
100
+ def _block_start(kind: str) -> StreamEvent:
101
+ return StreamEvent(
102
+ uuid="u",
103
+ session_id="s-1",
104
+ event={"type": "content_block_start", "content_block": {"type": kind}},
105
+ )
106
+
107
+
108
+ def _text(text: str) -> StreamEvent:
109
+ return StreamEvent(
110
+ uuid="u",
111
+ session_id="s-1",
112
+ event={
113
+ "type": "content_block_delta",
114
+ "delta": {"type": "text_delta", "text": text},
115
+ },
116
+ )
117
+
118
+
119
+ def test_the_reply_holds_only_the_text_after_the_last_tool_call():
120
+ stream = [
121
+ _block_start("text"),
122
+ _text("Asking the remote agent:"),
123
+ _block_start("tool_use"),
124
+ _block_start("text"),
125
+ _text("Reykjavik is "),
126
+ _text("cold."),
127
+ ]
128
+
129
+ async def fake_stream_turn(prompt, options, conversation_id, user_id=None):
130
+ for message in stream:
131
+ yield message
132
+
133
+ with patch.object(a2a, "stream_turn", fake_stream_turn):
134
+ app = FastAPI(telemetry=FASTAPI_TELEMETRY)
135
+ a2a.add_a2a_routes(app)
136
+ response = TestClient(app).post(
137
+ "/a2a/app",
138
+ json={
139
+ "jsonrpc": "2.0",
140
+ "id": "1",
141
+ "method": "message/stream",
142
+ "params": {
143
+ "message": {
144
+ "messageId": uuid.uuid4().hex,
145
+ "role": "user",
146
+ "parts": [{"kind": "text", "text": "weather?"}],
147
+ }
148
+ },
149
+ },
150
+ )
151
+
152
+ updates = [
153
+ "".join(p["text"] for p in event["artifact"]["parts"])
154
+ for line in response.text.splitlines()
155
+ if line.startswith("data:")
156
+ and (event := json.loads(line.removeprefix("data:"))["result"])["kind"]
157
+ == "artifact-update"
158
+ ]
159
+ *chunks, last = updates
160
+ assert "".join(chunks) == "Asking the remote agent:\n\nReykjavik is cold."
161
+ assert last == "Reykjavik is cold."
162
+
163
+
164
+ @pytest.mark.parametrize(
165
+ "stream",
166
+ [
167
+ [_block_start("text"), _text("The fact is "), _text("**77**")],
168
+ # A turn that streamed no deltas still gets its reply.
169
+ [AssistantMessage(content=[TextBlock(text="The fact is **77**")], model="m")],
170
+ ],
171
+ ids=["streamed", "not_streamed"],
172
+ )
173
+ def test_the_last_artifact_chunk_carries_the_whole_reply(stream):
174
+ """ADK's RemoteA2aAgent keeps only the last chunk's parts."""
175
+
176
+ async def fake_stream_turn(prompt, options, conversation_id, user_id=None):
177
+ for message in stream:
178
+ yield message
179
+
180
+ with patch.object(a2a, "stream_turn", fake_stream_turn):
181
+ app = FastAPI(telemetry=FASTAPI_TELEMETRY)
182
+ a2a.add_a2a_routes(app)
183
+ response = TestClient(app).post(
184
+ "/a2a/app",
185
+ json={
186
+ "jsonrpc": "2.0",
187
+ "id": "1",
188
+ "method": "message/stream",
189
+ "params": {
190
+ "message": {
191
+ "messageId": uuid.uuid4().hex,
192
+ "role": "user",
193
+ "parts": [{"kind": "text", "text": "fact?"}],
194
+ }
195
+ },
196
+ },
197
+ )
198
+
199
+ updates = [
200
+ event
201
+ for line in response.text.splitlines()
202
+ if line.startswith("data:")
203
+ and (event := json.loads(line.removeprefix("data:"))["result"])["kind"]
204
+ == "artifact-update"
205
+ ]
206
+ *chunks, last = updates
207
+ assert not any(chunk.get("lastChunk") for chunk in chunks)
208
+ assert last["lastChunk"] is True
209
+ assert not last.get("append")
210
+ assert "".join(p["text"] for p in last["artifact"]["parts"]) == (
211
+ "The fact is **77**"
212
+ )
213
+
214
+
215
+ def test_a_structured_output_turn_replies_with_only_the_json():
216
+ """With output_format, callers get the JSON without the model's preceding text."""
217
+ weather = {"city": "San Francisco", "temperature_f": 60, "conditions": "foggy"}
218
+ stream = [
219
+ _block_start("text"),
220
+ _text("Now let me provide the structured output:"),
221
+ _block_start("tool_use"),
222
+ ResultMessage(
223
+ subtype="success",
224
+ duration_ms=1,
225
+ duration_api_ms=1,
226
+ is_error=False,
227
+ num_turns=1,
228
+ session_id="s-1",
229
+ result=json.dumps(weather),
230
+ structured_output=weather,
231
+ ),
232
+ ]
233
+
234
+ async def fake_stream_turn(prompt, options, conversation_id, user_id=None):
235
+ for message in stream:
236
+ yield message
237
+
238
+ options = ClaudeAgentOptions(
239
+ output_format={"type": "json_schema", "schema": {"type": "object"}}
240
+ )
241
+ with (
242
+ patch.object(a2a, "stream_turn", fake_stream_turn),
243
+ patch.object(a2a, "root_agent", options),
244
+ ):
245
+ app = FastAPI(telemetry=FASTAPI_TELEMETRY)
246
+ a2a.add_a2a_routes(app)
247
+ response = TestClient(app).post(
248
+ "/a2a/app",
249
+ json={
250
+ "jsonrpc": "2.0",
251
+ "id": "1",
252
+ "method": "message/stream",
253
+ "params": {
254
+ "message": {
255
+ "messageId": uuid.uuid4().hex,
256
+ "role": "user",
257
+ "parts": [{"kind": "text", "text": "weather?"}],
258
+ }
259
+ },
260
+ },
261
+ )
262
+
263
+ [update] = [
264
+ event
265
+ for line in response.text.splitlines()
266
+ if line.startswith("data:")
267
+ and (event := json.loads(line.removeprefix("data:"))["result"])["kind"]
268
+ == "artifact-update"
269
+ ]
270
+ assert update["lastChunk"] is True
271
+ [part] = update["artifact"]["parts"]
272
+ assert json.loads(part["text"]) == weather
273
+
274
+
275
+ def test_cancel_ends_the_task_canceled_and_stops_the_turn():
276
+ """Stopping the turn closes the SDK stream and its CLI subprocess."""
277
+ started = threading.Event()
278
+ closed = []
279
+
280
+ async def fake_stream_turn(prompt, options, conversation_id, user_id=None):
281
+ try:
282
+ yield _text("Once upon a time")
283
+ started.set()
284
+ await asyncio.Event().wait()
285
+ finally:
286
+ closed.append(True)
287
+
288
+ def rpc(client: TestClient, method: str, params: dict) -> dict:
289
+ response = client.post(
290
+ "/a2a/app",
291
+ json={"jsonrpc": "2.0", "id": "1", "method": method, "params": params},
292
+ )
293
+ return response.json()
294
+
295
+ with patch.object(a2a, "stream_turn", fake_stream_turn):
296
+ app = FastAPI(telemetry=FASTAPI_TELEMETRY)
297
+ a2a.add_a2a_routes(app)
298
+ with TestClient(app) as client:
299
+ sent = rpc(
300
+ client,
301
+ "message/send",
302
+ {
303
+ "message": {
304
+ "messageId": uuid.uuid4().hex,
305
+ "role": "user",
306
+ "parts": [{"kind": "text", "text": "a long story"}],
307
+ },
308
+ "configuration": {"blocking": False},
309
+ },
310
+ )
311
+ task_id = sent["result"]["id"]
312
+ assert started.wait(timeout=10)
313
+
314
+ canceled = rpc(client, "tasks/cancel", {"id": task_id})
315
+ task = rpc(client, "tasks/get", {"id": task_id})
316
+
317
+ assert "error" not in canceled
318
+ assert canceled["result"]["status"]["state"] == "canceled"
319
+ assert task["result"]["status"]["state"] == "canceled"
320
+ assert closed == [True]
321
+
322
+
323
+ def test_a_failed_turn_is_logged_under_its_trace():
324
+ """The turn's span has ended when the failure is logged; the log keeps its trace."""
325
+ tracer = TracerProvider().get_tracer(__name__)
326
+ turn_trace = []
327
+
328
+ async def fake_stream_turn(prompt, options, conversation_id, user_id=None):
329
+ span = tracer.start_span("turn")
330
+ turn_trace.append(span.get_span_context().trace_id)
331
+ with trace.use_span(span, end_on_exit=True):
332
+ yield _text("partial")
333
+ raise RuntimeError("model not available")
334
+
335
+ traces = _TraceOfRecords()
336
+ logging.getLogger().addHandler(traces)
337
+ with patch.object(a2a, "stream_turn", fake_stream_turn):
338
+ app = FastAPI(telemetry=FASTAPI_TELEMETRY)
339
+ a2a.add_a2a_routes(app)
340
+ TestClient(app).post(
341
+ "/a2a/app",
342
+ json={
343
+ "jsonrpc": "2.0",
344
+ "id": "1",
345
+ "method": "message/send",
346
+ "params": {
347
+ "message": {
348
+ "messageId": uuid.uuid4().hex,
349
+ "role": "user",
350
+ "parts": [{"kind": "text", "text": "hi"}],
351
+ }
352
+ },
353
+ },
354
+ )
355
+
356
+ logging.getLogger().removeHandler(traces)
357
+
358
+ assert traces.trace_ids["Claude agent turn failed"] == turn_trace[0]
359
+
360
+
361
+ class _TraceOfRecords(logging.Handler):
362
+ """The trace each record was logged under, by message."""
363
+
364
+ def __init__(self):
365
+ super().__init__()
366
+ self.trace_ids: dict[str, int] = {}
367
+
368
+ def emit(self, record):
369
+ context = trace.get_current_span().get_span_context()
370
+ self.trace_ids[record.getMessage()] = context.trace_id
371
+
372
+
373
+ def _send_message(app: FastAPI) -> None:
374
+ response = TestClient(app).post(
375
+ "/a2a/app",
376
+ json={
377
+ "jsonrpc": "2.0",
378
+ "id": "1",
379
+ "method": "message/send",
380
+ "params": {
381
+ "message": {
382
+ "messageId": uuid.uuid4().hex,
383
+ "role": "user",
384
+ "parts": [{"kind": "text", "text": "hi"}],
385
+ }
386
+ },
387
+ },
388
+ )
389
+ assert response.status_code == 200
390
+
391
+
392
+ def test_an_unauthenticated_caller_is_named_after_the_conversation():
393
+ """As ADK names them, so sessions and memories have a user."""
394
+ seen = []
395
+
396
+ async def fake_stream_turn(prompt, options, conversation_id, user_id=None):
397
+ seen.append((conversation_id, user_id))
398
+ return
399
+ yield
400
+
401
+ with patch.object(a2a, "stream_turn", fake_stream_turn):
402
+ app = FastAPI(telemetry=FASTAPI_TELEMETRY)
403
+ a2a.add_a2a_routes(app)
404
+ _send_message(app)
405
+
406
+ [(conversation_id, user_id)] = seen
407
+ assert user_id == f"A2A_USER_{conversation_id}"
408
+
409
+
410
+ @pytest.mark.parametrize("engine_id, waits", [("123", True), (None, False)])
411
+ def test_on_agent_runtime_a_turn_waits_for_its_memory_ingest(
412
+ monkeypatch, engine_id, waits
413
+ ):
414
+ """Agent Runtime throttles the CPU once the response ends."""
415
+ if engine_id:
416
+ monkeypatch.setenv("GOOGLE_CLOUD_AGENT_ENGINE_ID", engine_id)
417
+ else:
418
+ monkeypatch.delenv("GOOGLE_CLOUD_AGENT_ENGINE_ID", raising=False)
419
+
420
+ async def fake_stream_turn(prompt, options, conversation_id, user_id=None):
421
+ yield _text("Hello.")
422
+
423
+ flush = AsyncMock()
424
+ with (
425
+ patch.object(a2a, "stream_turn", fake_stream_turn),
426
+ patch.object(a2a.memory_bank, "flush", flush),
427
+ ):
428
+ app = FastAPI(telemetry=FASTAPI_TELEMETRY)
429
+ a2a.add_a2a_routes(app)
430
+ _send_message(app)
431
+
432
+ assert flush.await_count == (1 if waits else 0)