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,825 @@
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
+ """How `app/app_utils/claude.py` drives the SDK, with the SDK's `query` faked."""
16
+
17
+ from __future__ import annotations
18
+
19
+ import json
20
+ import os
21
+ import pathlib
22
+ import shutil
23
+ import sys
24
+ from unittest.mock import AsyncMock, MagicMock, patch
25
+
26
+ import anyio
27
+ import pytest
28
+ from claude_agent_sdk import (
29
+ AssistantMessage,
30
+ ClaudeAgentOptions,
31
+ InMemorySessionStore,
32
+ MirrorErrorMessage,
33
+ ResultMessage,
34
+ StreamEvent,
35
+ TextBlock,
36
+ ToolResultBlock,
37
+ ToolUseBlock,
38
+ UserMessage,
39
+ )
40
+ from openinference.instrumentation import TraceConfig
41
+ from openinference.instrumentation.claude_agent_sdk import ClaudeAgentSDKInstrumentor
42
+ from opentelemetry.sdk.trace import TracerProvider
43
+ from opentelemetry.sdk.trace.export import SimpleSpanProcessor
44
+ from opentelemetry.sdk.trace.export.in_memory_span_exporter import (
45
+ InMemorySpanExporter,
46
+ )
47
+
48
+ from app.app_utils import (
49
+ claude,
50
+ replies,
51
+ settings,
52
+ turn_options,
53
+ workspaces,
54
+ )
55
+ from app.app_utils.telemetry import traces
56
+ from tests.unit.helpers import workspaces_root, write_local_transcript
57
+
58
+ pytestmark = pytest.mark.usefixtures("isolated")
59
+
60
+
61
+ def _result(**overrides) -> ResultMessage:
62
+ fields = {
63
+ "subtype": "success",
64
+ "duration_ms": 1,
65
+ "duration_api_ms": 1,
66
+ "is_error": False,
67
+ "num_turns": 1,
68
+ "session_id": "s-1",
69
+ "result": "It's foggy.",
70
+ }
71
+ return ResultMessage(**{**fields, **overrides})
72
+
73
+
74
+ def _delta(text: str, parent: str | None = None) -> StreamEvent:
75
+ return StreamEvent(
76
+ uuid="u",
77
+ session_id="s-1",
78
+ event={
79
+ "type": "content_block_delta",
80
+ "delta": {"type": "text_delta", "text": text},
81
+ },
82
+ parent_tool_use_id=parent,
83
+ )
84
+
85
+
86
+ _TOOL_TURN = [
87
+ AssistantMessage(
88
+ content=[
89
+ ToolUseBlock(id="t1", name="mcp__w__get_weather", input={"city": "SF"})
90
+ ],
91
+ model="m",
92
+ ),
93
+ UserMessage(
94
+ content=[
95
+ ToolResultBlock(tool_use_id="t1", content=[{"type": "text", "text": "60F"}])
96
+ ]
97
+ ),
98
+ AssistantMessage(content=[TextBlock(text="It's foggy.")], model="m"),
99
+ _result(),
100
+ ]
101
+
102
+
103
+ def _fake_query(messages, seen: list[dict] | None = None):
104
+ async def fake(*, prompt, options):
105
+ if seen is not None:
106
+ seen.append({"prompt": prompt, "options": options})
107
+ for message in messages:
108
+ yield message
109
+
110
+ return fake
111
+
112
+
113
+ class TestRunTurn:
114
+ def test_collects_reply_session_and_tool_calls(self):
115
+ with patch.object(claude.claude_agent_sdk, "query", _fake_query(_TOOL_TURN)):
116
+ reply = anyio.run(claude.run_turn, "weather?", ClaudeAgentOptions(), "c")
117
+
118
+ assert reply.text == "It's foggy."
119
+ assert reply.session_id == "s-1"
120
+ assert reply.tool_calls == [
121
+ {
122
+ "id": "t1",
123
+ "name": "mcp__w__get_weather",
124
+ "args": {"city": "SF"},
125
+ "result": "60F",
126
+ }
127
+ ]
128
+
129
+ def test_a_subagents_tool_calls_are_kept_apart_under_its_name(self):
130
+ delegate = {"subagent_type": "forecaster", "prompt": "Weather in SF?"}
131
+ messages = [
132
+ AssistantMessage(
133
+ content=[ToolUseBlock(id="a1", name="Agent", input=delegate)],
134
+ model="m",
135
+ ),
136
+ AssistantMessage(
137
+ content=[ToolUseBlock(id="t1", name="get_weather", input={})],
138
+ model="m",
139
+ parent_tool_use_id="a1",
140
+ ),
141
+ UserMessage(
142
+ content=[ToolResultBlock(tool_use_id="t1", content="60F")],
143
+ parent_tool_use_id="a1",
144
+ ),
145
+ UserMessage(content=[ToolResultBlock(tool_use_id="a1", content="Foggy")]),
146
+ _result(),
147
+ ]
148
+ with patch.object(claude.claude_agent_sdk, "query", _fake_query(messages)):
149
+ reply = anyio.run(claude.run_turn, "weather?", ClaudeAgentOptions(), "c")
150
+
151
+ assert [call["name"] for call in reply.tool_calls] == ["Agent"]
152
+ assert reply.subagent_calls == [
153
+ {
154
+ "id": "t1",
155
+ "name": "get_weather",
156
+ "args": {},
157
+ "agent": "forecaster",
158
+ "parent": "a1",
159
+ "result": "60F",
160
+ }
161
+ ]
162
+
163
+ def test_error_result_raises(self):
164
+ failing = [_result(is_error=True, result="model not available")]
165
+ with patch.object(claude.claude_agent_sdk, "query", _fake_query(failing)):
166
+ with pytest.raises(claude.AgentError, match="model not available"):
167
+ anyio.run(claude.run_turn, "hi", ClaudeAgentOptions(), "c")
168
+
169
+ # The SDK reports a dropped write mid-turn, or just before the result.
170
+ @pytest.mark.parametrize("at", [0, len(_TOOL_TURN) - 1])
171
+ def test_a_failed_session_store_write_fails_the_turn_once_it_ends(self, at):
172
+ dropped = MirrorErrorMessage(
173
+ subtype="mirror_error", data={}, error="connection refused"
174
+ )
175
+ messages = [*_TOOL_TURN[:at], dropped, *_TOOL_TURN[at:]]
176
+ seen = []
177
+
178
+ async def read() -> None:
179
+ async for message in claude.stream_turn("hi", ClaudeAgentOptions(), "c"):
180
+ seen.append(message)
181
+
182
+ with patch.object(claude.claude_agent_sdk, "query", _fake_query(messages)):
183
+ with pytest.raises(claude.AgentError, match="connection refused"):
184
+ anyio.run(read)
185
+ # Read to the end, so analytics still get the result's cost and turns.
186
+ assert seen == _TOOL_TURN
187
+
188
+ @pytest.mark.parametrize("capture", [None, "true"])
189
+ def test_a_denied_call_is_logged_with_its_arguments_only_on_capture(
190
+ self, monkeypatch, caplog, capture
191
+ ):
192
+ if capture:
193
+ monkeypatch.setenv(
194
+ "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT", capture
195
+ )
196
+ else:
197
+ monkeypatch.delenv(
198
+ "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT", raising=False
199
+ )
200
+ denial = {
201
+ "tool_name": "Bash",
202
+ "tool_use_id": "t1",
203
+ "tool_input": {"cmd": "ls ~"},
204
+ }
205
+ denied = [_result(permission_denials=[denial])]
206
+ with patch.object(claude.claude_agent_sdk, "query", _fake_query(denied)):
207
+ anyio.run(claude.run_turn, "hi", ClaudeAgentOptions(), "c")
208
+
209
+ [warning] = [
210
+ r.getMessage() for r in caplog.records if "denied" in r.getMessage()
211
+ ]
212
+ assert "Bash" in warning
213
+ assert ("ls ~" in warning) == bool(capture)
214
+
215
+ def test_an_error_result_closes_the_sdk_stream(self):
216
+ closed = []
217
+
218
+ async def query(*, prompt, options):
219
+ try:
220
+ yield _result(is_error=True, result="max turns")
221
+ yield _result() # never reached: the turn stops at the error
222
+ finally:
223
+ closed.append(True)
224
+
225
+ async def turn_then_check():
226
+ with pytest.raises(claude.AgentError):
227
+ await claude.run_turn("hi", ClaudeAgentOptions(), "c")
228
+ # Checked while the loop runs: the stream must close when the turn ends.
229
+ return list(closed)
230
+
231
+ with patch.object(claude.claude_agent_sdk, "query", query):
232
+ assert anyio.run(turn_then_check) == [True]
233
+
234
+ @pytest.mark.parametrize(
235
+ ("cli_path", "skipped"), [(None, "1"), ("/usr/local/bin/claude", None)]
236
+ )
237
+ def test_the_cli_version_check_is_skipped_only_for_the_bundled_cli(
238
+ self, monkeypatch, cli_path, skipped
239
+ ):
240
+ # setenv first so monkeypatch removes what the turn sets.
241
+ monkeypatch.setenv("CLAUDE_AGENT_SDK_SKIP_VERSION_CHECK", "")
242
+ monkeypatch.delenv("CLAUDE_AGENT_SDK_SKIP_VERSION_CHECK")
243
+ with patch.object(claude.claude_agent_sdk, "query", _fake_query([_result()])):
244
+ anyio.run(claude.run_turn, "hi", ClaudeAgentOptions(cli_path=cli_path), "c")
245
+ assert os.environ.get("CLAUDE_AGENT_SDK_SKIP_VERSION_CHECK") == skipped
246
+
247
+ def test_least_recently_used_workspaces_are_evicted(self, monkeypatch):
248
+ monkeypatch.setattr(workspaces, "MAX_WORKSPACES", 2)
249
+ # Another process serving the same agent shares its directory.
250
+ (workspaces_root() / "other-service").mkdir(parents=True)
251
+ with patch.object(claude.claude_agent_sdk, "query", _fake_query([_result()])):
252
+ for conversation in ["old", "mid", "new", "old", "newest"]:
253
+ anyio.run(claude.run_turn, "hi", ClaudeAgentOptions(), conversation)
254
+
255
+ kept = {d.name for d in workspaces_root().iterdir()}
256
+ assert kept == {"other-service"} | {
257
+ turn_options.session_id_for(c) for c in ("old", "newest")
258
+ }
259
+
260
+ def test_a_workspace_with_a_turn_running_is_not_evicted(self, monkeypatch):
261
+ monkeypatch.setattr(workspaces, "MAX_WORKSPACES", 1)
262
+ cwd_existed = []
263
+
264
+ async def query(*, prompt, options):
265
+ if prompt == "long":
266
+ events["started"].set()
267
+ await events["finish"].wait()
268
+ cwd_existed.append(pathlib.Path(options.cwd).is_dir())
269
+ yield _result()
270
+
271
+ async def overlapping_turns():
272
+ events.update(started=anyio.Event(), finish=anyio.Event())
273
+ async with anyio.create_task_group() as tg:
274
+ tg.start_soon(claude.run_turn, "long", ClaudeAgentOptions(), "a")
275
+ await events["started"].wait()
276
+ await claude.run_turn("short", ClaudeAgentOptions(), "b")
277
+ events["finish"].set()
278
+
279
+ events: dict[str, anyio.Event] = {}
280
+ with patch.object(claude.claude_agent_sdk, "query", query):
281
+ anyio.run(overlapping_turns)
282
+
283
+ assert cwd_existed == [True]
284
+
285
+ def test_turns_are_recorded_for_bigquery_only_when_it_is_on(self, monkeypatch):
286
+ rows: list[dict] = []
287
+ writer = MagicMock(put=rows.append)
288
+ with patch.object(claude.claude_agent_sdk, "query", _fake_query(_TOOL_TURN)):
289
+ with patch.object(claude.bq_analytics, "writer", return_value=None):
290
+ anyio.run(claude.run_turn, "weather?", ClaudeAgentOptions(), "c")
291
+ assert rows == []
292
+ with patch.object(claude.bq_analytics, "writer", return_value=writer):
293
+ anyio.run(claude.run_turn, "weather?", ClaudeAgentOptions(), "conv-1")
294
+
295
+ assert rows[0]["event_type"] == "USER_MESSAGE_RECEIVED"
296
+ assert rows[-1]["event_type"] == "INVOCATION_COMPLETED"
297
+ assert {r["session_id"] for r in rows} == {
298
+ turn_options.session_id_for("conv-1")
299
+ }
300
+ assert {r["user_id"] for r in rows} == {"A2A_USER_conv-1"}
301
+
302
+ def test_a_failing_observer_never_fails_the_turn_or_hides_its_error(
303
+ self, monkeypatch, caplog
304
+ ):
305
+ class Broken:
306
+ def __init__(self, agent_name):
307
+ pass
308
+
309
+ def handle(self, event):
310
+ raise ValueError("observer bug")
311
+
312
+ async def failing_query(*, prompt, options):
313
+ yield _TOOL_TURN[0]
314
+ raise RuntimeError("CLI exited")
315
+
316
+ monkeypatch.setattr(claude, "CallCounts", Broken)
317
+ with patch.object(claude.claude_agent_sdk, "query", _fake_query(_TOOL_TURN)):
318
+ reply = anyio.run(claude.run_turn, "weather?", ClaudeAgentOptions(), "c")
319
+ with patch.object(claude.claude_agent_sdk, "query", failing_query):
320
+ with pytest.raises(RuntimeError, match="CLI exited"):
321
+ anyio.run(claude.run_turn, "weather?", ClaudeAgentOptions(), "c")
322
+
323
+ assert reply.text == "It's foggy."
324
+ assert "Broken failed on TurnEnded" in caplog.text
325
+
326
+ def test_model_calls_are_logged_when_the_upload_hook_is_on(self, monkeypatch):
327
+ monkeypatch.setenv("OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK", "upload")
328
+ monkeypatch.setenv(
329
+ "OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH", "memory://logs/completions"
330
+ )
331
+ events: list = []
332
+ monkeypatch.setattr(claude.completions.telemetry, "emit_event", events.append)
333
+ with patch.object(claude.claude_agent_sdk, "query", _fake_query(_TOOL_TURN)):
334
+ anyio.run(claude.run_turn, "weather?", ClaudeAgentOptions(), "conv-1")
335
+
336
+ # The tool call and the answer.
337
+ assert len(events) == 2
338
+ assert {e.attributes["gen_ai.conversation.id"] for e in events} == {
339
+ turn_options.session_id_for("conv-1")
340
+ }
341
+
342
+ def test_turns_of_one_conversation_run_one_after_another(self):
343
+ events: list[str] = []
344
+ resumed: dict[str, str | None] = {}
345
+
346
+ async def query(*, prompt, options):
347
+ events.append(f"start {prompt}")
348
+ resumed[prompt] = options.resume
349
+ if prompt != "c":
350
+ write_local_transcript("ctx-1")
351
+ await anyio.sleep(0.01)
352
+ events.append(f"end {prompt}")
353
+ yield _result(result=prompt)
354
+
355
+ async def overlapping_turns():
356
+ async with anyio.create_task_group() as tg:
357
+ for prompt, conversation in [
358
+ ("a", "ctx-1"),
359
+ ("b", "ctx-1"),
360
+ ("c", "ctx-2"),
361
+ ]:
362
+ tg.start_soon(
363
+ claude.run_turn, prompt, ClaudeAgentOptions(), conversation
364
+ )
365
+
366
+ with patch.object(claude.claude_agent_sdk, "query", query):
367
+ anyio.run(overlapping_turns)
368
+
369
+ # The second turn resumes the first's transcript instead of starting a
370
+ # parallel one, and another conversation doesn't wait for either.
371
+ assert events.index("end a") < events.index("start b")
372
+ assert events.index("start c") < events.index("end a")
373
+ assert resumed == {
374
+ "a": None,
375
+ "b": turn_options.session_id_for("ctx-1"),
376
+ "c": None,
377
+ }
378
+ assert not claude._turn_locks
379
+
380
+ # Without its prompt first, the subagent's first message is its tool call.
381
+ @pytest.mark.parametrize("prompt_first", [True, False])
382
+ def test_a_subagents_spans_name_it_and_hold_its_model_calls(
383
+ self, monkeypatch, prompt_first
384
+ ):
385
+ monkeypatch.setenv("OPENINFERENCE_ENABLE_GENAI_SEMCONV", "true")
386
+ monkeypatch.setenv("OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK", "upload")
387
+ monkeypatch.setenv(
388
+ "OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH", "memory://logs/completions"
389
+ )
390
+ monkeypatch.setattr(claude.completions.telemetry, "emit_event", lambda _: None)
391
+ monkeypatch.setattr(settings, "AGENT_NAME", "weather_agent")
392
+ exporter = InMemorySpanExporter()
393
+ provider = TracerProvider()
394
+ provider.add_span_processor(traces.AgentNameProcessor("weather_agent"))
395
+ provider.add_span_processor(SimpleSpanProcessor(exporter))
396
+ delegate = ToolUseBlock(
397
+ id="agent-1",
398
+ name="Agent",
399
+ input={"subagent_type": "weather_researcher", "prompt": "Paris?"},
400
+ )
401
+ lookup = ToolUseBlock(id="t1", name="get_weather", input={"city": "Paris"})
402
+ # The CLI runs the subagent in the background: the Agent call returns
403
+ # before the subagent's messages arrive.
404
+ turn = [
405
+ AssistantMessage(content=[delegate], model="m", message_id="m1"),
406
+ UserMessage(content=[ToolResultBlock(tool_use_id="agent-1", content="")]),
407
+ *(
408
+ [UserMessage(content="Paris?", parent_tool_use_id="agent-1")]
409
+ if prompt_first
410
+ else []
411
+ ),
412
+ AssistantMessage(
413
+ content=[lookup],
414
+ model="m",
415
+ message_id="s1",
416
+ parent_tool_use_id="agent-1",
417
+ ),
418
+ UserMessage(
419
+ content=[ToolResultBlock(tool_use_id="t1", content="Sunny.")],
420
+ parent_tool_use_id="agent-1",
421
+ ),
422
+ AssistantMessage(
423
+ content=[TextBlock(text="Sunny.")],
424
+ model="m",
425
+ message_id="s2",
426
+ parent_tool_use_id="agent-1",
427
+ ),
428
+ AssistantMessage(
429
+ content=[TextBlock(text="It's sunny.")], model="m", message_id="m2"
430
+ ),
431
+ _result(),
432
+ ]
433
+ instrumentor = ClaudeAgentSDKInstrumentor()
434
+ # The instrumentor wraps query() where the SDK defines it, then
435
+ # re-exports the wrapper; uninstrument() re-exports the original.
436
+ query_module = sys.modules["claude_agent_sdk.query"]
437
+ with (
438
+ patch.object(query_module, "query", _fake_query(turn)),
439
+ patch.object(claude.claude_agent_sdk, "query"),
440
+ ):
441
+ instrumentor.instrument(tracer_provider=provider, config=TraceConfig())
442
+ try:
443
+ with patch.object(
444
+ claude.completions.trace, "get_tracer", provider.get_tracer
445
+ ):
446
+ anyio.run(claude.run_turn, "weather?", ClaudeAgentOptions(), "c")
447
+ finally:
448
+ instrumentor.uninstrument()
449
+
450
+ spans = exporter.get_finished_spans()
451
+ [root] = [s for s in spans if s.name == "ClaudeAgentSDK.query"]
452
+ [subagent] = [s for s in spans if s.parent and s.name.startswith("ClaudeAgent")]
453
+ [tool] = [s for s in spans if s.name == "get_weather"]
454
+ [call] = [s for s in spans if s.name == "Agent"]
455
+ chats = [s for s in spans if s.name == "chat m"]
456
+
457
+ def agent_of(span):
458
+ return span.attributes["gen_ai.agent.name"]
459
+
460
+ assert subagent.name == "ClaudeAgentSDK.weather_researcher"
461
+ assert agent_of(subagent) == "weather_researcher"
462
+ assert tool.parent.span_id == subagent.context.span_id
463
+ assert agent_of(tool) == "weather_researcher"
464
+ assert agent_of(call) == "weather_agent"
465
+ nested: dict[int, list[str]] = {}
466
+ for chat in chats:
467
+ nested.setdefault(chat.parent.span_id, []).append(agent_of(chat))
468
+ assert nested == {
469
+ root.context.span_id: ["weather_agent"] * 2,
470
+ subagent.context.span_id: ["weather_researcher"] * 2,
471
+ }
472
+
473
+ def test_missing_mcp_command_fails_with_a_fix(self):
474
+ options = ClaudeAgentOptions(
475
+ mcp_servers={"fs": {"command": "no-such-binary-xyz", "args": []}}
476
+ )
477
+ with pytest.raises(claude.AgentError, match="nodejs"):
478
+ anyio.run(claude.run_turn, "hi", options, "c")
479
+
480
+ def test_no_model_fails_with_a_fix_before_calling_the_model(self, monkeypatch):
481
+ monkeypatch.delenv("ANTHROPIC_MODEL")
482
+ # Turns always go to Gemini platform, so an API key names no model.
483
+ monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-test")
484
+ query = MagicMock()
485
+ with patch.object(claude.claude_agent_sdk, "query", query):
486
+ with pytest.raises(claude.AgentError, match="model="):
487
+ anyio.run(claude.run_turn, "hi", ClaudeAgentOptions(), "c")
488
+ query.assert_not_called()
489
+
490
+ @pytest.mark.parametrize(
491
+ "options",
492
+ [
493
+ ClaudeAgentOptions(model="claude-haiku-4-5"),
494
+ ClaudeAgentOptions(env={"ANTHROPIC_MODEL": "claude-haiku-4-5"}),
495
+ # Settings files may name the model.
496
+ ClaudeAgentOptions(setting_sources=["project"]),
497
+ ],
498
+ )
499
+ def test_a_model_from_elsewhere_runs(self, monkeypatch, options):
500
+ monkeypatch.delenv("ANTHROPIC_MODEL")
501
+ with patch.object(claude.claude_agent_sdk, "query", _fake_query(_TOOL_TURN)):
502
+ reply = anyio.run(claude.run_turn, "hi", options, "c")
503
+ assert reply.text == "It's foggy."
504
+
505
+ def test_project_settings_may_name_the_model(self, monkeypatch, isolated):
506
+ monkeypatch.delenv("ANTHROPIC_MODEL")
507
+ (isolated / ".claude").mkdir()
508
+ (isolated / ".claude" / "settings.json").write_text('{"model": "m"}')
509
+ with patch.object(claude.claude_agent_sdk, "query", _fake_query(_TOOL_TURN)):
510
+ reply = anyio.run(claude.run_turn, "hi", ClaudeAgentOptions(), "c")
511
+ assert reply.text == "It's foggy."
512
+
513
+ @pytest.mark.parametrize("setting_sources", [None, ["project"]])
514
+ def test_missing_project_mcp_command_fails_with_a_fix(
515
+ self, isolated, setting_sources
516
+ ):
517
+ (isolated / ".mcp.json").write_text(
518
+ '{"mcpServers": {"fs": {"command": "no-such-binary-xyz"}}}'
519
+ )
520
+ options = ClaudeAgentOptions(setting_sources=setting_sources)
521
+ with patch.object(claude.claude_agent_sdk, "query", _fake_query(_TOOL_TURN)):
522
+ with pytest.raises(
523
+ claude.AgentError, match="'fs' runs 'no-such-binary-xyz'"
524
+ ):
525
+ anyio.run(claude.run_turn, "hi", options, "c")
526
+
527
+ @pytest.mark.parametrize(
528
+ ("setting_sources", "command"),
529
+ [
530
+ # The CLI doesn't read .mcp.json without the project source.
531
+ (["user"], "no-such-binary-xyz"),
532
+ # The CLI expands variables in commands itself.
533
+ (None, "${NO_SUCH_DIR}/no-such-binary-xyz"),
534
+ ],
535
+ )
536
+ def test_project_mcp_commands_left_to_the_cli_are_not_checked(
537
+ self, isolated, setting_sources, command
538
+ ):
539
+ (isolated / ".mcp.json").write_text(
540
+ json.dumps({"mcpServers": {"fs": {"command": command}}})
541
+ )
542
+ options = ClaudeAgentOptions(setting_sources=setting_sources)
543
+ with patch.object(claude.claude_agent_sdk, "query", _fake_query(_TOOL_TURN)):
544
+ assert anyio.run(claude.run_turn, "hi", options, "c").text == "It's foggy."
545
+
546
+ @pytest.mark.parametrize("content", ["{not json", "[]"])
547
+ def test_malformed_project_mcp_json_fails_with_a_fix(self, isolated, content):
548
+ (isolated / ".mcp.json").write_text(content)
549
+ with patch.object(claude.claude_agent_sdk, "query", _fake_query(_TOOL_TURN)):
550
+ with pytest.raises(claude.AgentError, match=r"\.mcp\.json is not"):
551
+ anyio.run(claude.run_turn, "hi", ClaudeAgentOptions(), "c")
552
+
553
+
554
+ class TestCallerScopedConversations:
555
+ """With an authenticated caller, a conversation is that caller's alone."""
556
+
557
+ CONTEXT_ID = "3e3a0114-1fa0-463c-a119-b599a1beb275"
558
+
559
+ def _turn(self, user_id: str | None, options=None) -> ClaudeAgentOptions:
560
+ """One turn through stream_turn; the fake CLI saves its transcript."""
561
+ seen: list[dict] = []
562
+
563
+ async def query(*, prompt, options):
564
+ seen.append(options)
565
+ session = options.resume or options.session_id
566
+ # Keyed by the CLI's working directory, on disk and in the store.
567
+ project_key = claude.claude_agent_sdk.project_key_for_directory(options.cwd)
568
+ transcripts = (
569
+ pathlib.Path(os.environ["CLAUDE_CONFIG_DIR"]) / "projects" / project_key
570
+ )
571
+ transcripts.mkdir(parents=True, exist_ok=True)
572
+ (transcripts / f"{session}.jsonl").write_text('{"type": "user"}\n')
573
+ if options.session_store is not None:
574
+ key = {"project_key": project_key, "session_id": session}
575
+ await options.session_store.append(key, [{"type": "user"}])
576
+ yield _result(session_id=session)
577
+
578
+ async def run() -> None:
579
+ async for _ in claude.stream_turn(
580
+ "hi", options or ClaudeAgentOptions(), self.CONTEXT_ID, user_id
581
+ ):
582
+ pass
583
+
584
+ with patch.object(claude.claude_agent_sdk, "query", query):
585
+ anyio.run(run)
586
+ return seen[0]
587
+
588
+ def test_another_caller_does_not_resume_the_conversation(self):
589
+ alice = self._turn("alice@example.com")
590
+ bob = self._turn("bob@example.com")
591
+ assert alice.cwd != bob.cwd
592
+ assert (bob.session_id, bob.resume) == (self.CONTEXT_ID, None)
593
+
594
+ def test_the_same_caller_resumes_their_conversation(self):
595
+ first = self._turn("alice@example.com")
596
+ later = self._turn("alice@example.com")
597
+ assert later.cwd == first.cwd
598
+ assert (first.session_id, later.resume) == (self.CONTEXT_ID, self.CONTEXT_ID)
599
+
600
+ def test_callers_are_kept_apart_in_the_session_store(self):
601
+ store = InMemorySessionStore()
602
+ self._turn("alice@example.com", ClaudeAgentOptions(session_store=store))
603
+ # Only the store has the transcript now, as on another instance.
604
+ shutil.rmtree(pathlib.Path(os.environ["CLAUDE_CONFIG_DIR"]) / "projects")
605
+
606
+ bob = self._turn("bob@example.com", ClaudeAgentOptions(session_store=store))
607
+ back = self._turn("alice@example.com", ClaudeAgentOptions(session_store=store))
608
+ assert bob.resume is None
609
+ assert back.resume == self.CONTEXT_ID
610
+
611
+ def test_without_a_caller_the_context_id_alone_keys_it(self):
612
+ anyone = self._turn(None)
613
+ again = self._turn(None)
614
+ assert anyone.cwd == str(workspaces_root() / self.CONTEXT_ID)
615
+ assert (again.cwd, again.resume) == (anyone.cwd, self.CONTEXT_ID)
616
+ # A caller doesn't pick up the unauthenticated conversation either.
617
+ assert self._turn("alice@example.com").resume is None
618
+
619
+
620
+ class TestTextDelta:
621
+ def test_top_level_text_delta(self):
622
+ assert replies.text_delta(_delta("Hello")) == "Hello"
623
+
624
+ def test_subagent_and_non_text_events_are_skipped(self):
625
+ assert replies.text_delta(_delta("x", parent="t1")) == ""
626
+ other = StreamEvent(uuid="u", session_id="s", event={"type": "message_start"})
627
+ assert replies.text_delta(other) == ""
628
+ assert replies.text_delta(_result()) == ""
629
+
630
+
631
+ class TestModelAccess:
632
+ def test_defaults_to_vertex_with_the_given_project(self, monkeypatch):
633
+ monkeypatch.delenv("CLAUDE_CODE_USE_VERTEX", raising=False)
634
+ monkeypatch.delenv("CLOUD_ML_REGION", raising=False)
635
+ monkeypatch.delenv("ANTHROPIC_VERTEX_PROJECT_ID")
636
+ monkeypatch.setenv("GOOGLE_CLOUD_PROJECT", "from-env")
637
+
638
+ claude.configure_model_access()
639
+
640
+ import os
641
+
642
+ assert os.environ["CLAUDE_CODE_USE_VERTEX"] == "1"
643
+ assert os.environ["CLOUD_ML_REGION"] == "global"
644
+ assert os.environ["ANTHROPIC_VERTEX_PROJECT_ID"] == "from-env"
645
+
646
+ def test_an_api_key_does_not_skip_vertex(self, monkeypatch):
647
+ monkeypatch.delenv("CLAUDE_CODE_USE_VERTEX", raising=False)
648
+ monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-test")
649
+ claude.configure_model_access()
650
+
651
+ import os
652
+
653
+ assert os.environ["CLAUDE_CODE_USE_VERTEX"] == "1"
654
+
655
+ def test_existing_values_win(self, monkeypatch):
656
+ monkeypatch.setenv("CLOUD_ML_REGION", "us-east5")
657
+ claude.configure_model_access()
658
+
659
+ import os
660
+
661
+ assert os.environ["CLOUD_ML_REGION"] == "us-east5"
662
+ assert os.environ["ANTHROPIC_VERTEX_PROJECT_ID"] == "test-project"
663
+
664
+
665
+ class TestEvalAgentsMetadata:
666
+ def test_declares_the_agents_mcp_tools(self):
667
+ import importlib.util
668
+ from pathlib import Path
669
+
670
+ script = Path(__file__).resolve().parents[2] / "scripts" / "eval_generate.py"
671
+ spec = importlib.util.spec_from_file_location("eval_generate", script)
672
+ assert spec is not None and spec.loader is not None
673
+ mod = importlib.util.module_from_spec(spec)
674
+ spec.loader.exec_module(mod)
675
+
676
+ from claude_agent_sdk import create_sdk_mcp_server, tool
677
+
678
+ @tool("get_weather", "Get the weather.", {"city": str})
679
+ async def get_weather(args):
680
+ return {"content": []}
681
+
682
+ # Its own agent, so the test holds whatever app/agent.py declares.
683
+ options = ClaudeAgentOptions(
684
+ system_prompt="Be brief.",
685
+ mcp_servers={"w": create_sdk_mcp_server(name="w", tools=[get_weather])},
686
+ tools=["WebFetch"],
687
+ )
688
+
689
+ agents = mod.agents_metadata(options, "weather")
690
+
691
+ declarations = agents["weather"]["tools"][0]["function_declarations"]
692
+ assert [d["name"] for d in declarations] == ["mcp__w__get_weather", "WebFetch"]
693
+ assert declarations[0]["parameters"]["properties"] == {
694
+ "city": {"type": "string"}
695
+ }
696
+ assert agents["weather"]["instruction"] == "Be brief."
697
+
698
+ def test_declares_the_agents_subagents(self):
699
+ import importlib.util
700
+ from pathlib import Path
701
+
702
+ script = Path(__file__).resolve().parents[2] / "scripts" / "eval_generate.py"
703
+ spec = importlib.util.spec_from_file_location("eval_generate", script)
704
+ assert spec is not None and spec.loader is not None
705
+ mod = importlib.util.module_from_spec(spec)
706
+ spec.loader.exec_module(mod)
707
+
708
+ from claude_agent_sdk import AgentDefinition
709
+
710
+ options = ClaudeAgentOptions(
711
+ tools=["Agent", "WebFetch"],
712
+ agents={
713
+ "researcher": AgentDefinition(
714
+ description="Looks things up.", prompt="Search.", tools=["WebFetch"]
715
+ ),
716
+ "writer": AgentDefinition(description="Writes.", prompt="Write."),
717
+ },
718
+ )
719
+
720
+ agents = mod.agents_metadata(options, "root")
721
+
722
+ assert agents["root"]["sub_agents"] == ["researcher", "writer"]
723
+ assert agents["researcher"] == {
724
+ "agent_id": "researcher",
725
+ "agent_type": "ClaudeAgent",
726
+ "description": "Looks things up.",
727
+ "instruction": "Search.",
728
+ "tools": [{"function_declarations": [{"name": "WebFetch"}]}],
729
+ }
730
+ # Without its own tool list, a subagent inherits the agent's tools.
731
+ assert agents["writer"]["tools"] == agents["root"]["tools"]
732
+
733
+
734
+ def _fake_pool() -> MagicMock:
735
+ """An asyncpg pool whose table setup succeeds and whose queries find nothing."""
736
+ conn = MagicMock(execute=AsyncMock())
737
+ conn.transaction.return_value.__aenter__ = AsyncMock()
738
+ conn.transaction.return_value.__aexit__ = AsyncMock(return_value=False)
739
+ pool = MagicMock(fetchval=AsyncMock(return_value=False))
740
+ pool.acquire.return_value.__aenter__ = AsyncMock(return_value=conn)
741
+ pool.acquire.return_value.__aexit__ = AsyncMock(return_value=False)
742
+ return pool
743
+
744
+
745
+ _KEY = {"project_key": "p", "session_id": "s"}
746
+
747
+
748
+ class TestPostgresSessionStoreConnection:
749
+ @patch("asyncpg.create_pool", new_callable=AsyncMock)
750
+ def test_password_connects_over_the_cloudsql_socket(self, create_pool, monkeypatch):
751
+ from app.app_utils.session_store import PostgresSessionStore
752
+
753
+ monkeypatch.setenv("INSTANCE_CONNECTION_NAME", "proj:us-east1:db")
754
+ monkeypatch.setenv("DB_PASS", "secret")
755
+ monkeypatch.setenv("DB_NAME", "sessions")
756
+ create_pool.return_value = _fake_pool()
757
+
758
+ anyio.run(PostgresSessionStore.from_env().exists, _KEY)
759
+
760
+ assert create_pool.call_args.kwargs == {
761
+ "min_size": 1,
762
+ "max_size": 5,
763
+ "host": "/cloudsql/proj:us-east1:db",
764
+ "user": "postgres",
765
+ "password": "secret",
766
+ "database": "sessions",
767
+ }
768
+
769
+ def test_needs_a_password(self, monkeypatch):
770
+ from app.app_utils.session_store import PostgresSessionStore
771
+
772
+ monkeypatch.setenv("INSTANCE_CONNECTION_NAME", "proj:us-east1:db")
773
+ assert PostgresSessionStore.from_env() is None
774
+
775
+
776
+ @pytest.mark.skipif(
777
+ not os.environ.get("SESSION_STORE_POSTGRES_URL"),
778
+ reason="set SESSION_STORE_POSTGRES_URL to a Postgres database to run",
779
+ )
780
+ class TestPostgresSessionStore:
781
+ @pytest.fixture
782
+ def make_store(self):
783
+ """Stores on fresh tables, dropped afterwards."""
784
+ import asyncpg
785
+
786
+ from app.app_utils.session_store import PostgresSessionStore
787
+
788
+ dsn = os.environ["SESSION_STORE_POSTGRES_URL"]
789
+ tables: list[str] = []
790
+
791
+ def make() -> PostgresSessionStore:
792
+ tables.append(f"test_session_store_{os.getpid()}_{len(tables)}")
793
+ return PostgresSessionStore(tables[-1], dsn=dsn)
794
+
795
+ yield make
796
+
797
+ async def drop() -> None:
798
+ conn = await asyncpg.connect(dsn)
799
+ for table in tables:
800
+ await conn.execute(f"DROP TABLE IF EXISTS {table}")
801
+ await conn.close()
802
+
803
+ anyio.run(drop)
804
+
805
+ def test_meets_the_sdk_session_store_contract(self, make_store):
806
+ from claude_agent_sdk.testing.session_store_conformance import (
807
+ run_session_store_conformance,
808
+ )
809
+
810
+ # Each contract gets its own table, so they don't see each other's rows.
811
+ anyio.run(run_session_store_conformance, make_store)
812
+
813
+ def test_exists_without_loading(self, make_store):
814
+ store = make_store()
815
+ main = {"project_key": "p", "session_id": "s"}
816
+ sub = {**main, "subpath": "subagents/agent-1"}
817
+
818
+ async def run() -> list[bool]:
819
+ before = await store.exists(main)
820
+ await store.append(sub, [{"type": "user"}])
821
+ only_sub = await store.exists(main)
822
+ await store.append(main, [{"type": "user"}])
823
+ return [before, only_sub, await store.exists(main)]
824
+
825
+ assert anyio.run(run) == [False, False, True]