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,104 @@
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
+ """Create the `agent_events` table and its `v_*` views, as ADK's plugin does."""
16
+
17
+ from __future__ import annotations
18
+
19
+ import hashlib
20
+ import logging
21
+ import threading
22
+ from typing import Any
23
+
24
+ from app.app_utils.bq_analytics import schema
25
+
26
+ _VIEW_HASH_LABEL = "view_query_sha256"
27
+
28
+
29
+ def ensure_table(client: Any, table_id: str) -> None:
30
+ """Create the events table unless it exists."""
31
+ from google.api_core.exceptions import Conflict, NotFound
32
+ from google.cloud import bigquery
33
+
34
+ try:
35
+ client.get_table(table_id)
36
+ except NotFound:
37
+ table = bigquery.Table(
38
+ table_id,
39
+ schema=[
40
+ bigquery.SchemaField.from_api_repr(f) for f in schema.EVENTS_SCHEMA
41
+ ],
42
+ )
43
+ table.time_partitioning = bigquery.TimePartitioning(
44
+ type_=bigquery.TimePartitioningType.DAY, field="timestamp"
45
+ )
46
+ table.clustering_fields = schema.CLUSTERING_FIELDS
47
+ table.labels = {"adk_schema_version": schema.SCHEMA_VERSION}
48
+ try:
49
+ client.create_table(table)
50
+ except Conflict:
51
+ pass # another instance created it first
52
+
53
+
54
+ def ensure_views(client: Any, project: str, dataset: str, table_id: str) -> None:
55
+ """Create or update the views whose query hash label is out of date."""
56
+ from google.cloud import bigquery
57
+
58
+ labels = {
59
+ item.table_id: (item.labels or {}).get(_VIEW_HASH_LABEL)
60
+ for item in client.list_tables(f"{project}.{dataset}")
61
+ }
62
+ columns = list(schema.VIEW_COMMON_COLUMNS)
63
+ writes = []
64
+ for event_type, extra in schema.EVENT_VIEW_DEFS.items():
65
+ # The tables API, unlike a query job, needs only dataset write.
66
+ view = bigquery.Table(
67
+ f"{project}.{dataset}.{schema.VIEW_PREFIX}_{event_type.lower()}"
68
+ )
69
+ selected = ",\n ".join(columns + extra)
70
+ view.view_query = (
71
+ f"SELECT\n {selected}\nFROM\n `{table_id}`\n"
72
+ f"WHERE\n event_type = '{event_type}'\n"
73
+ )
74
+ digest = hashlib.sha256(view.view_query.encode()).hexdigest()[:16]
75
+ if labels.get(view.table_id, "") == digest:
76
+ continue
77
+ view.labels = {_VIEW_HASH_LABEL: digest}
78
+ writes.append(
79
+ threading.Thread(
80
+ target=_write_view,
81
+ args=(client, view, view.table_id in labels),
82
+ daemon=True,
83
+ )
84
+ )
85
+ # Creating the views one by one takes over 10 s.
86
+ for thread in writes:
87
+ thread.start()
88
+ for thread in writes:
89
+ thread.join()
90
+
91
+
92
+ def _write_view(client: Any, view: Any, exists: bool) -> None:
93
+ from google.api_core.exceptions import Conflict
94
+
95
+ try:
96
+ if not exists:
97
+ try:
98
+ client.create_table(view)
99
+ return
100
+ except Conflict:
101
+ pass # another instance created it first
102
+ client.update_table(view, ["view_query", "labels"])
103
+ except Exception as e:
104
+ logging.warning("BigQuery Agent Analytics view %s: %s", view.table_id, e)
@@ -0,0 +1,188 @@
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
+ """Stream rows to the `agent_events` table from a background thread."""
16
+
17
+ from __future__ import annotations
18
+
19
+ import atexit
20
+ import json
21
+ import logging
22
+ import queue
23
+ import threading
24
+ import time
25
+ from typing import Any
26
+
27
+ from app.app_utils.bq_analytics import schema, tables
28
+
29
+ _BATCH_SECONDS = 0.2
30
+ # BigQuery's recommended maximum rows per insertAll request.
31
+ _BATCH_ROWS = 500
32
+ # Under insertAll's 10 MB request limit, with room for row ids.
33
+ _BATCH_BYTES = 9 * 1024 * 1024
34
+ # Caps a batch's request and retries; the client default retries for 10 minutes.
35
+ _WRITE_SECONDS = 30
36
+ # Newer rows are dropped once this many are queued.
37
+ _MAX_QUEUED_ROWS = 10_000
38
+ _EXIT_FLUSH_SECONDS = 30
39
+
40
+
41
+ class Writer:
42
+ """Batches rows on a daemon thread into `insert_rows_json`."""
43
+
44
+ def __init__(self, project: str, dataset: str) -> None:
45
+ from google.cloud import bigquery
46
+
47
+ self._client = bigquery.Client(project=project)
48
+ # Retrying is safe: the row ids let BigQuery drop duplicates.
49
+ self._retry = bigquery.DEFAULT_RETRY.with_timeout(_WRITE_SECONDS)
50
+ self.project, self.dataset = project, dataset
51
+ self.table_id = f"{project}.{dataset}.{schema.TABLE}"
52
+ self._queue: queue.Queue[dict[str, Any]] = queue.Queue(_MAX_QUEUED_ROWS)
53
+ self._idle = threading.Condition()
54
+ self._pending = 0
55
+ self._dropping = False
56
+ self._views_done = threading.Event()
57
+ threading.Thread(target=self._run, name="bq-analytics", daemon=True).start()
58
+ # A one-off `agents-cli run` exits before the daemon thread writes.
59
+ atexit.register(self.flush, _EXIT_FLUSH_SECONDS)
60
+
61
+ def put(self, row: dict[str, Any]) -> None:
62
+ with self._idle:
63
+ self._pending += 1
64
+ try:
65
+ self._queue.put_nowait(row)
66
+ except queue.Full:
67
+ self._written(1)
68
+ if not self._dropping:
69
+ logging.warning(
70
+ "BigQuery Agent Analytics: %d rows are waiting to be written; "
71
+ "new rows are dropped until writes catch up.",
72
+ _MAX_QUEUED_ROWS,
73
+ )
74
+ self._dropping = True
75
+ return
76
+ self._dropping = False
77
+
78
+ def flush(self, timeout: float) -> bool:
79
+ """Wait up to `timeout` seconds for queued rows and the views setup."""
80
+ deadline = time.monotonic() + timeout
81
+ with self._idle:
82
+ written = self._idle.wait_for(lambda: self._pending == 0, timeout)
83
+ if not written:
84
+ logging.warning(
85
+ "BigQuery Agent Analytics: %d rows weren't written within "
86
+ "%gs of shutdown and are lost.",
87
+ self._pending,
88
+ timeout,
89
+ )
90
+ return self._views_done.wait(max(0, deadline - time.monotonic())) and written
91
+
92
+ def _run(self) -> None:
93
+ failing = not self._set_up()
94
+ while True:
95
+ rows = self._next_rows()
96
+ try:
97
+ for batch in _by_size(rows):
98
+ failing = self._insert(batch, failing)
99
+ except Exception: # a dead thread would make every flush() time out
100
+ logging.warning(
101
+ "BigQuery Agent Analytics dropped %d rows", len(rows), exc_info=True
102
+ )
103
+ self._written(len(rows))
104
+
105
+ def _set_up(self) -> bool:
106
+ """Create the table, then the views in the background; False on failure."""
107
+ try:
108
+ tables.ensure_table(self._client, self.table_id)
109
+ threading.Thread(
110
+ target=self._ensure_views, name="bq-analytics-views", daemon=True
111
+ ).start()
112
+ return True
113
+ except Exception as e:
114
+ self._views_done.set()
115
+ logging.warning(
116
+ "BigQuery Agent Analytics table %s is not ready: %s. Check that "
117
+ "the dataset exists (agents-cli infra single-project creates it) "
118
+ "and that the service account can write to it. Rows that can't "
119
+ "be written are dropped.",
120
+ self.table_id,
121
+ e,
122
+ )
123
+ return False
124
+
125
+ def _ensure_views(self) -> None:
126
+ try:
127
+ tables.ensure_views(self._client, self.project, self.dataset, self.table_id)
128
+ except Exception as e:
129
+ logging.warning("BigQuery Agent Analytics views: %s", e)
130
+ finally:
131
+ self._views_done.set()
132
+
133
+ def _next_rows(self) -> list[dict[str, Any]]:
134
+ """Wait for a row, then take what else arrives within _BATCH_SECONDS."""
135
+ rows = [self._queue.get()]
136
+ deadline = time.monotonic() + _BATCH_SECONDS
137
+ while len(rows) < _BATCH_ROWS:
138
+ try:
139
+ rows.append(
140
+ self._queue.get(timeout=max(0, deadline - time.monotonic()))
141
+ )
142
+ except queue.Empty:
143
+ break
144
+ return rows
145
+
146
+ def _insert(self, batch: list[dict[str, Any]], failing: bool) -> bool:
147
+ """Write one batch; returns whether writes are failing."""
148
+ try:
149
+ errors = self._client.insert_rows_json(
150
+ self.table_id,
151
+ batch,
152
+ row_ids=[r["event_id"] for r in batch],
153
+ retry=self._retry,
154
+ timeout=_WRITE_SECONDS,
155
+ )
156
+ if errors:
157
+ logging.warning(
158
+ "BigQuery Agent Analytics rejected rows: %s", errors[:3]
159
+ )
160
+ return False
161
+ except Exception as e:
162
+ if not failing:
163
+ logging.warning(
164
+ "BigQuery Agent Analytics write failed: %s. Rows are "
165
+ "dropped until writes succeed again.",
166
+ e,
167
+ )
168
+ return True
169
+
170
+ def _written(self, count: int) -> None:
171
+ """Mark `count` rows as no longer pending, written or not."""
172
+ with self._idle:
173
+ self._pending -= count
174
+ self._idle.notify_all()
175
+
176
+
177
+ def _by_size(rows: list[dict[str, Any]]) -> list[list[dict[str, Any]]]:
178
+ """Split rows into batches of at most _BATCH_BYTES of JSON each."""
179
+ batches: list[list[dict[str, Any]]] = [[]]
180
+ size = 0
181
+ for row in rows:
182
+ row_size = len(json.dumps(row, default=str))
183
+ if batches[-1] and size + row_size > _BATCH_BYTES:
184
+ batches.append([])
185
+ size = 0
186
+ batches[-1].append(row)
187
+ size += row_size
188
+ return batches
@@ -0,0 +1,297 @@
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
+ """Run `root_agent` through the Claude Agent SDK.
16
+
17
+ `stream_turn` runs one turn and yields every SDK message; `run_turn` runs one
18
+ to completion. The helpers they use live in:
19
+
20
+ - `turn_options`: the turn's session, workspace and server defaults.
21
+ - `workspaces`: per-conversation working directories and their eviction.
22
+ - `project_settings`: the served agent's CLAUDE.md, .claude/ and .mcp.json,
23
+ from agent_config/.
24
+ - `replies`: reading the reply and tool calls out of the messages.
25
+ - `conversation`: the running turn's conversation and user, for tools to key
26
+ state on.
27
+ - `memory_bank`: the user's memories, recalled into the turn and learned from it.
28
+ - `turn_events`: parsing the turn's messages into events, for the observers below.
29
+ - `bq_analytics`, `completions`, `telemetry`: the turn's BigQuery rows, prompt
30
+ logs, subagent spans and call-count metrics.
31
+ """
32
+
33
+ from __future__ import annotations
34
+
35
+ import dataclasses
36
+ import json
37
+ import logging
38
+ import os
39
+ import shutil
40
+ import weakref
41
+ from collections.abc import AsyncIterator, Iterable, Sequence
42
+ from contextlib import ExitStack, aclosing
43
+ from pathlib import Path
44
+ from typing import Protocol
45
+
46
+ import anyio
47
+ import claude_agent_sdk
48
+ from claude_agent_sdk import ClaudeAgentOptions, Message, MirrorErrorMessage
49
+ from dotenv import load_dotenv
50
+ from opentelemetry import trace
51
+
52
+ from app.app_utils import bq_analytics, completions, memory_bank, project_settings
53
+ from app.app_utils.conversation import current_conversation, current_user
54
+ from app.app_utils.replies import AgentError, TurnReply, record
55
+ from app.app_utils.telemetry.call_counts import CallCounts
56
+ from app.app_utils.telemetry.config import agent_name
57
+ from app.app_utils.telemetry.subagent_spans import (
58
+ SubagentSpans,
59
+ current_subagent_spans,
60
+ )
61
+ from app.app_utils.telemetry.traces import system_prompt_attributes
62
+ from app.app_utils.turn_events import Event, TurnParser
63
+ from app.app_utils.turn_options import turn_options
64
+ from app.app_utils.workspaces import claim_workspace, release_workspace
65
+
66
+ __all__ = [
67
+ "AgentError",
68
+ "TurnReply",
69
+ "configure_model_access",
70
+ "current_conversation",
71
+ "current_user",
72
+ "run_turn",
73
+ "stream_turn",
74
+ ]
75
+
76
+ # Serializes turns of one conversation: two at once would fork its transcript.
77
+ _turn_locks: weakref.WeakValueDictionary[str, anyio.Lock] = (
78
+ weakref.WeakValueDictionary()
79
+ )
80
+
81
+
82
+ async def stream_turn(
83
+ prompt: str,
84
+ options: ClaudeAgentOptions,
85
+ conversation_id: str,
86
+ user_id: str | None = None,
87
+ ) -> AsyncIterator[Message]:
88
+ """Yield every SDK message for one turn of the agent.
89
+
90
+ Args:
91
+ user_id: The caller; scopes the conversation and memories to them.
92
+ """
93
+ configure_model_access()
94
+ if options.cli_path is None:
95
+ # The CLI bundled with the SDK always matches it, so skip the `claude -v`
96
+ # subprocess the SDK otherwise runs before every turn. The SDK reads
97
+ # this from the server's environment, not options.env.
98
+ os.environ.setdefault("CLAUDE_AGENT_SDK_SKIP_VERSION_CHECK", "1")
99
+ _check_mcp_commands(options)
100
+ _check_model(options)
101
+ scoped_key = f"{user_id}\x00{conversation_id}" if user_id else conversation_id
102
+ memory_user = user_id or f"A2A_USER_{conversation_id}"
103
+ # An agent's own cwd is not a workspace: it is never claimed or evicted.
104
+ kept = not options.cwd
105
+ async with _turn_locks.setdefault(scoped_key, anyio.Lock()):
106
+ # Before turn_options: nothing may await between it and claim_workspace.
107
+ system_prompt = await memory_bank.recall(
108
+ options.system_prompt, prompt, memory_user
109
+ )
110
+ options = await turn_options(options, conversation_id, user_id)
111
+ # Observers log the memories too; AGENT_STARTING only the agent's own prompt.
112
+ options_with_memories = dataclasses.replace(
113
+ options, system_prompt=system_prompt
114
+ )
115
+ with ExitStack() as cleanup:
116
+ # Claimed before the next await, as turn_options requires, so the
117
+ # workspace can't be evicted first.
118
+ workspace = Path(options.cwd)
119
+ if kept:
120
+ claim_workspace(workspace)
121
+ cleanup.callback(release_workspace, workspace)
122
+ cleanup.callback(
123
+ current_conversation.reset, current_conversation.set(scoped_key)
124
+ )
125
+ cleanup.callback(current_user.reset, current_user.set(memory_user))
126
+ parser = TurnParser(main_agent=agent_name())
127
+ subagent_spans = SubagentSpans(parser.agent_name)
128
+ cleanup.callback(
129
+ current_subagent_spans.reset, current_subagent_spans.set(subagent_spans)
130
+ )
131
+ session_id = options.resume or options.session_id or conversation_id
132
+ observers: list[_TurnObserver | None] = [
133
+ bq_analytics.start_turn(
134
+ prompt,
135
+ options_with_memories,
136
+ session_id,
137
+ conversation_id,
138
+ user_id,
139
+ parser.agent_name,
140
+ instruction=options.system_prompt,
141
+ ),
142
+ completions.start_turn(
143
+ prompt,
144
+ options_with_memories,
145
+ session_id,
146
+ parser.agent_name,
147
+ subagent_spans,
148
+ ),
149
+ CallCounts(parser.agent_name),
150
+ memory_bank.start_turn(prompt, session_id, memory_user),
151
+ ]
152
+ consumers = [c for c in observers if c is not None]
153
+ error: BaseException | None = None
154
+ store_error: MirrorErrorMessage | None = None
155
+ span_attributes = system_prompt_attributes(
156
+ options_with_memories.system_prompt
157
+ )
158
+ try:
159
+ # Call claude_agent_sdk.query via the module so the OpenTelemetry
160
+ # wrapper applies. aclosing stops the CLI subprocess when a turn
161
+ # ends early.
162
+ async with aclosing(
163
+ claude_agent_sdk.query(prompt=prompt, options=options_with_memories)
164
+ ) as stream:
165
+ async for message in stream:
166
+ if span_attributes:
167
+ # OpenInference's turn span, current once query()
168
+ # starts; its tool spans never are.
169
+ trace.get_current_span().set_attributes(span_attributes)
170
+ span_attributes = {}
171
+ if isinstance(message, MirrorErrorMessage):
172
+ store_error = store_error or message
173
+ continue
174
+ events = parser.feed(message)
175
+ subagent_spans.observe(message)
176
+ _dispatch(events, consumers)
177
+ yield message
178
+ if store_error is not None:
179
+ # The SDK carries on after a failed session store write, but
180
+ # the store is now missing part of this turn, and every
181
+ # later turn resumes from the store. Raised only once the
182
+ # turn ends, so its result still reaches the observers.
183
+ raise AgentError(
184
+ "Claude agent turn failed: couldn't save its "
185
+ f"transcript to the session store: {store_error.error}"
186
+ )
187
+ except BaseException as e:
188
+ error = e
189
+ raise
190
+ finally:
191
+ _dispatch(parser.finish(error), consumers)
192
+
193
+
194
+ async def run_turn(
195
+ prompt: str, options: ClaudeAgentOptions, conversation_id: str
196
+ ) -> TurnReply:
197
+ """Run one turn to completion and return what it produced."""
198
+ reply = TurnReply()
199
+ async with aclosing(stream_turn(prompt, options, conversation_id)) as stream:
200
+ async for message in stream:
201
+ reply = record(reply, message)
202
+ # The caller's process may end next, which would drop the ingest.
203
+ await memory_bank.flush()
204
+ return reply
205
+
206
+
207
+ def configure_model_access() -> None:
208
+ """Point the Claude Code CLI at Claude on Gemini platform using ADC.
209
+
210
+ The region and project in the environment or `.env` win.
211
+ """
212
+ load_dotenv()
213
+ os.environ.setdefault("CLAUDE_CODE_USE_VERTEX", "1")
214
+ os.environ.setdefault("CLOUD_ML_REGION", "global")
215
+ if os.environ.get("ANTHROPIC_VERTEX_PROJECT_ID"):
216
+ return
217
+ project = os.environ.get("GOOGLE_CLOUD_PROJECT")
218
+ if not project:
219
+ import google.auth
220
+
221
+ _, project = google.auth.default()
222
+ if project:
223
+ os.environ["ANTHROPIC_VERTEX_PROJECT_ID"] = project
224
+
225
+
226
+ def _check_mcp_commands(options: ClaudeAgentOptions) -> None:
227
+ """Fail early, and say why, when a stdio MCP server's command is missing."""
228
+ servers = dict(options.mcp_servers) if isinstance(options.mcp_servers, dict) else {}
229
+ mcp_json = project_settings.AGENT_CONFIG_DIR / ".mcp.json"
230
+ sources = options.setting_sources
231
+ if (sources is None or "project" in sources) and mcp_json.is_file():
232
+ try:
233
+ project_servers = json.loads(mcp_json.read_text()).get("mcpServers")
234
+ except (ValueError, AttributeError) as err:
235
+ raise AgentError(
236
+ f"agent_config/.mcp.json is not a JSON object: {err}"
237
+ ) from err
238
+ if isinstance(project_servers, dict):
239
+ servers |= project_servers
240
+ for name, config in servers.items():
241
+ command = config.get("command") if isinstance(config, dict) else None
242
+ # shortcut: a command using ${VAR} expansion is left for the CLI to
243
+ # resolve, unchecked; expand it here if those need checking too.
244
+ if command and "$" not in command and shutil.which(command) is None:
245
+ raise AgentError(
246
+ f"MCP server {name!r} runs {command!r}, which is not installed here. "
247
+ "To deploy it, install it in the Dockerfile (for npx-based "
248
+ "servers: RUN apt-get update && apt-get install -y nodejs npm)."
249
+ )
250
+
251
+
252
+ def _check_model(options: ClaudeAgentOptions) -> None:
253
+ """Fail early when no model is set.
254
+
255
+ The CLI's own default model is rarely enabled in Model Garden.
256
+ """
257
+ env = {**os.environ, **options.env}
258
+ if options.model or env.get("ANTHROPIC_MODEL"):
259
+ return
260
+ # shortcut: settings files and `settings` may name the model too; skip the
261
+ # check whenever the CLI could load them rather than parse them here.
262
+ if options.settings or options.setting_sources:
263
+ return
264
+ if (
265
+ options.setting_sources is None
266
+ and (project_settings.AGENT_CONFIG_DIR / ".claude").is_dir()
267
+ ):
268
+ return
269
+ raise AgentError(
270
+ "No model is set, so the Claude Code CLI would use its own default, which "
271
+ "is usually not enabled in Model Garden. Set model= in root_agent "
272
+ "(app/agent.py) to a Claude model enabled for the project, e.g. "
273
+ 'model="claude-haiku-4-5".'
274
+ )
275
+
276
+
277
+ class _TurnObserver(Protocol):
278
+ def handle(self, event: Event) -> None: ...
279
+
280
+
281
+ def _dispatch(events: Iterable[Event], consumers: Sequence[_TurnObserver]) -> None:
282
+ """Hand each parsed turn event to every consumer, in order.
283
+
284
+ A consumer's failure is logged, never raised: it would fail the turn, or
285
+ replace the turn's own exception when the turn ends with one.
286
+ """
287
+ for event in events:
288
+ for consumer in consumers:
289
+ try:
290
+ consumer.handle(event)
291
+ except Exception:
292
+ logging.warning(
293
+ "%s failed on %s",
294
+ type(consumer).__name__,
295
+ type(event).__name__,
296
+ exc_info=True,
297
+ )