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.
- core/claude/README.md +35 -0
- core/claude/template/.agents/skills/agents-cli-claude/SKILL.md +106 -0
- core/claude/template/.agents/skills/agents-cli-claude/references/claude.md +386 -0
- core/claude/template/.agents/skills/agents-cli-claude/references/migrate-claude-agent.md +318 -0
- core/claude/template/.agents/skills/agents-cli-claude/references/migrate-from-aws.md +132 -0
- core/claude/template/.dockerignore +28 -0
- core/claude/template/.env +18 -0
- core/claude/template/.env.example +17 -0
- core/claude/template/.template/templateconfig.yaml +31 -0
- core/claude/template/AGENTS.md +33 -0
- core/claude/template/Dockerfile +55 -0
- core/claude/template/agent_config/README.md +9 -0
- core/claude/template/agents-cli-extension.yaml +49 -0
- core/claude/template/app/__init__.py +15 -0
- core/claude/template/app/agent.py +49 -0
- core/claude/template/app/app_utils/a2a.py +245 -0
- core/claude/template/app/app_utils/bq_analytics/__init__.py +124 -0
- core/claude/template/app/app_utils/bq_analytics/recorder.py +593 -0
- core/claude/template/app/app_utils/bq_analytics/redaction.py +209 -0
- core/claude/template/app/app_utils/bq_analytics/schema.py +394 -0
- core/claude/template/app/app_utils/bq_analytics/tables.py +104 -0
- core/claude/template/app/app_utils/bq_analytics/uploader.py +188 -0
- core/claude/template/app/app_utils/claude.py +297 -0
- core/claude/template/app/app_utils/completions.py +225 -0
- core/claude/template/app/app_utils/conversation.py +29 -0
- core/claude/template/app/app_utils/memory_bank.py +308 -0
- core/claude/template/app/app_utils/project_settings.py +91 -0
- core/claude/template/app/app_utils/reasoning_engine.py +237 -0
- core/claude/template/app/app_utils/remote_agents.py +349 -0
- core/claude/template/app/app_utils/remote_auth.py +159 -0
- core/claude/template/app/app_utils/replies.py +143 -0
- core/claude/template/app/app_utils/session_store.py +174 -0
- core/claude/template/app/app_utils/settings.py +24 -0
- core/claude/template/app/app_utils/telemetry/__init__.py +114 -0
- core/claude/template/app/app_utils/telemetry/call_counts.py +44 -0
- core/claude/template/app/app_utils/telemetry/cli_relay.py +266 -0
- core/claude/template/app/app_utils/telemetry/config.py +133 -0
- core/claude/template/app/app_utils/telemetry/logs.py +175 -0
- core/claude/template/app/app_utils/telemetry/metrics.py +270 -0
- core/claude/template/app/app_utils/telemetry/request_flush.py +104 -0
- core/claude/template/app/app_utils/telemetry/subagent_spans.py +80 -0
- core/claude/template/app/app_utils/telemetry/traces.py +166 -0
- core/claude/template/app/app_utils/turn_events.py +463 -0
- core/claude/template/app/app_utils/turn_options.py +219 -0
- core/claude/template/app/app_utils/workspaces.py +65 -0
- core/claude/template/app/fast_api_app.py +71 -0
- core/claude/template/app/feature_tools.py +27 -0
- core/claude/template/pyproject.toml +100 -0
- core/claude/template/scripts/eval_generate.py +340 -0
- core/claude/template/scripts/publish.py +66 -0
- core/claude/template/scripts/run.py +85 -0
- core/claude/template/scripts/unsupported.py +48 -0
- core/claude/template/tests/eval/datasets/basic-dataset.json +31 -0
- core/claude/template/tests/eval/eval_config.yaml +17 -0
- core/claude/template/tests/eval/response_quality.py +60 -0
- core/claude/template/tests/integration/test_server_e2e.py +168 -0
- core/claude/template/tests/load_test/.results/.placeholder +0 -0
- core/claude/template/tests/load_test/README.md +24 -0
- core/claude/template/tests/load_test/load_test.py +118 -0
- core/claude/template/tests/unit/conftest.py +63 -0
- core/claude/template/tests/unit/helpers.py +32 -0
- core/claude/template/tests/unit/test_a2a.py +432 -0
- core/claude/template/tests/unit/test_bq_analytics.py +928 -0
- core/claude/template/tests/unit/test_bq_redaction.py +89 -0
- core/claude/template/tests/unit/test_claude.py +825 -0
- core/claude/template/tests/unit/test_completions.py +369 -0
- core/claude/template/tests/unit/test_fast_api_app.py +59 -0
- core/claude/template/tests/unit/test_feature_tools.py +55 -0
- core/claude/template/tests/unit/test_memory_bank.py +625 -0
- core/claude/template/tests/unit/test_reasoning_engine.py +295 -0
- core/claude/template/tests/unit/test_remote_agents.py +517 -0
- core/claude/template/tests/unit/test_telemetry.py +991 -0
- core/claude/template/tests/unit/test_turn_events.py +309 -0
- core/claude/template/tests/unit/test_turn_options.py +394 -0
- core/claude/template/uv.lock +3029 -0
- core/langchain/README.md +54 -0
- core/langchain/template/.agents/skills/agents-cli-langchain/SKILL.md +84 -0
- core/langchain/template/.agents/skills/agents-cli-langchain/references/langchain.md +120 -0
- core/langchain/template/.agents/skills/agents-cli-langchain/references/samples.md +42 -0
- core/langchain/template/.template/templateconfig.yaml +32 -0
- core/langchain/template/AGENTS.md +35 -0
- core/langchain/template/agents-cli-extension.yaml +54 -0
- core/langchain/template/app/__init__.py +19 -0
- core/langchain/template/app/agent.py +61 -0
- core/langchain/template/app/app_utils/a2a.py +176 -0
- core/langchain/template/app/app_utils/content.py +37 -0
- core/langchain/template/app/app_utils/telemetry.py +154 -0
- core/langchain/template/app/fast_api_app.py +68 -0
- core/langchain/template/langgraph.json +7 -0
- core/langchain/template/pyproject.toml +102 -0
- core/langchain/template/scripts/_content.py +40 -0
- core/langchain/template/scripts/eval_generate.py +202 -0
- core/langchain/template/scripts/publish.py +59 -0
- core/langchain/template/scripts/run.py +59 -0
- core/langchain/template/scripts/unsupported.py +48 -0
- core/langchain/template/tests/eval/datasets/basic-dataset.json +16 -0
- core/langchain/template/tests/eval/eval_config.yaml +32 -0
- core/langchain/template/tests/eval/response_quality.py +60 -0
- core/langchain/template/tests/integration/test_server_e2e.py +173 -0
- core/langchain/template/tests/load_test/.results/.placeholder +0 -0
- core/langchain/template/tests/load_test/README.md +20 -0
- core/langchain/template/tests/load_test/load_test.py +82 -0
- core/langchain/template/uv.lock +3820 -0
- google_agents_cli_extensions-1.14.2.dist-info/METADATA +133 -0
- google_agents_cli_extensions-1.14.2.dist-info/RECORD +107 -0
- google_agents_cli_extensions-1.14.2.dist-info/WHEEL +4 -0
- 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
|
+
)
|