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,270 @@
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
+ """ADK's gen_ai.* metrics, exported to Cloud Monitoring.
16
+
17
+ Nothing is recorded until setup_cloud_metrics() runs.
18
+ """
19
+
20
+ from __future__ import annotations
21
+
22
+ import logging
23
+ from collections.abc import Iterable, Mapping
24
+ from dataclasses import dataclass
25
+ from typing import Any
26
+
27
+ from openinference.semconv.trace import SpanAttributes
28
+ from opentelemetry.metrics import Histogram, MeterProvider
29
+ from opentelemetry.sdk.metrics.export import (
30
+ MetricExporter,
31
+ MetricExportResult,
32
+ MetricReader,
33
+ )
34
+ from opentelemetry.sdk.trace import ReadableSpan, SpanProcessor
35
+ from opentelemetry.trace import StatusCode
36
+
37
+ from app.app_utils.telemetry import config
38
+
39
+ _instruments: _Instruments | None = None
40
+ _metrics_failing = False
41
+
42
+
43
+ def setup_cloud_metrics(credentials: Any, resource: Any) -> MetricReader | None:
44
+ """Export the gen_ai.* metrics to Cloud Monitoring.
45
+
46
+ Agent Runtime throttles the CPU between requests, so there metrics are
47
+ collected per request and the reader is returned; elsewhere None.
48
+ """
49
+ from opentelemetry import metrics as otel_metrics
50
+ from opentelemetry.exporter.otlp.proto.http.metric_exporter import (
51
+ OTLPMetricExporter,
52
+ )
53
+ from opentelemetry.sdk.metrics import MeterProvider as SdkMeterProvider
54
+ from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
55
+
56
+ global _instruments
57
+ session, upstream = config.telemetry_session(credentials)
58
+ exporter = _LoggingMetricExporter(
59
+ OTLPMetricExporter(session=session, endpoint=f"{upstream}/v1/metrics")
60
+ )
61
+ on_agent_runtime = config.on_agent_runtime()
62
+ reader = (
63
+ _RequestDrivenReader(exporter)
64
+ if on_agent_runtime
65
+ else PeriodicExportingMetricReader(exporter)
66
+ )
67
+ meter_provider = SdkMeterProvider(metric_readers=[reader], resource=resource)
68
+ otel_metrics.set_meter_provider(meter_provider)
69
+ _instruments = _create_instruments(meter_provider)
70
+ return reader if on_agent_runtime else None
71
+
72
+
73
+ class MetricsProcessor(SpanProcessor):
74
+ """Records agent and tool call durations from their spans."""
75
+
76
+ def on_end(self, span: ReadableSpan) -> None:
77
+ instruments = _instruments
78
+ attributes = span.attributes or {}
79
+ kind = attributes.get(SpanAttributes.OPENINFERENCE_SPAN_KIND)
80
+ if instruments is None or kind not in ("AGENT", "TOOL"):
81
+ return
82
+ try:
83
+ point: dict[str, Any] = {
84
+ "gen_ai.agent.name": attributes.get("gen_ai.agent.name")
85
+ or attributes.get(SpanAttributes.AGENT_NAME)
86
+ or config.agent_name(),
87
+ }
88
+ if span.status.status_code == StatusCode.ERROR:
89
+ point["error.type"] = _error_type(span)
90
+ seconds = ((span.end_time or 0) - (span.start_time or 0)) / 1e9
91
+ if kind == "AGENT":
92
+ point["gen_ai.operation.name"] = "invoke_agent"
93
+ instruments.agent_duration.record(seconds, point)
94
+ else:
95
+ point["gen_ai.operation.name"] = "execute_tool"
96
+ point["gen_ai.tool.name"] = str(
97
+ attributes.get("gen_ai.tool.name")
98
+ or attributes.get(SpanAttributes.TOOL_NAME, "")
99
+ )
100
+ instruments.tool_duration.record(seconds, point)
101
+ except Exception as e: # metrics must never fail a turn
102
+ _warn_metrics_failure(e)
103
+
104
+
105
+ def record_call_counts(counts: Iterable[tuple[str, int, int]]) -> None:
106
+ """Record gen_ai.invoke_agent.inference_calls and .tool_calls.
107
+
108
+ `counts` holds (agent name, inference calls, tool calls) per agent of a turn.
109
+ """
110
+ instruments = _instruments
111
+ if instruments is None:
112
+ return
113
+ try:
114
+ for agent, inference_calls, tool_calls in counts:
115
+ point = {"gen_ai.agent.name": agent}
116
+ instruments.inference_calls.record(inference_calls, point)
117
+ instruments.tool_calls.record(tool_calls, point)
118
+ except Exception as e: # metrics must never fail a turn
119
+ _warn_metrics_failure(e)
120
+
121
+
122
+ def record_token_usage(model: str, usage: Mapping[str, Any]) -> None:
123
+ """Record gen_ai.client.token.usage for one CLI model call.
124
+
125
+ Subagent calls count toward the main agent: the CLI's spans don't name them.
126
+ """
127
+ instruments = _instruments
128
+ if instruments is None:
129
+ return
130
+ try:
131
+ point = {
132
+ "gen_ai.operation.name": "generate_content",
133
+ "gen_ai.agent.name": config.agent_name(),
134
+ }
135
+ if model:
136
+ point["gen_ai.request.model"] = model
137
+ for token_type, key in (
138
+ ("input", "gen_ai.usage.input_tokens"),
139
+ ("output", "gen_ai.usage.output_tokens"),
140
+ ):
141
+ if usage.get(key):
142
+ instruments.token_usage.record(
143
+ usage[key], {**point, "gen_ai.token.type": token_type}
144
+ )
145
+ except Exception as e: # metrics must never drop the relay's response
146
+ _warn_metrics_failure(e)
147
+
148
+
149
+ class _LoggingMetricExporter(MetricExporter):
150
+ """Wraps an exporter: a failed export is logged once, and never raises."""
151
+
152
+ def __init__(self, exporter: MetricExporter) -> None:
153
+ # The OTLP exporter resolves these from OTEL_EXPORTER_OTLP_METRICS_*,
154
+ # and only exposes the result here.
155
+ super().__init__(
156
+ preferred_temporality=exporter._preferred_temporality,
157
+ preferred_aggregation=exporter._preferred_aggregation,
158
+ )
159
+ self._exporter = exporter
160
+
161
+ def export(
162
+ self, metrics_data: Any, timeout_millis: float = 10_000, **kwargs: Any
163
+ ) -> MetricExportResult:
164
+ global _metrics_failing
165
+ try:
166
+ result = self._exporter.export(metrics_data, timeout_millis=timeout_millis)
167
+ except Exception as e:
168
+ _warn_metrics_failure(e)
169
+ return MetricExportResult.FAILURE
170
+ if result == MetricExportResult.SUCCESS:
171
+ _metrics_failing = False
172
+ else:
173
+ _warn_metrics_failure("the Telemetry API rejected the export")
174
+ return result
175
+
176
+ def force_flush(self, timeout_millis: float = 10_000) -> bool:
177
+ return self._exporter.force_flush(timeout_millis)
178
+
179
+ def shutdown(self, timeout_millis: float = 30_000, **kwargs: Any) -> None:
180
+ self._exporter.shutdown(timeout_millis=timeout_millis)
181
+
182
+
183
+ class _RequestDrivenReader(MetricReader):
184
+ """Collects only when collect() is called: see request_flush.py."""
185
+
186
+ def __init__(self, exporter: MetricExporter) -> None:
187
+ super().__init__(
188
+ preferred_temporality=exporter._preferred_temporality,
189
+ preferred_aggregation=exporter._preferred_aggregation,
190
+ )
191
+ self._exporter = exporter
192
+
193
+ def _receive_metrics(
194
+ self, metrics_data: Any, timeout_millis: float = 10_000, **kwargs: Any
195
+ ) -> None:
196
+ self._exporter.export(metrics_data, timeout_millis=timeout_millis)
197
+
198
+ def shutdown(self, timeout_millis: float = 30_000, **kwargs: Any) -> None:
199
+ self.collect(timeout_millis=timeout_millis)
200
+ self._exporter.shutdown(timeout_millis=timeout_millis)
201
+
202
+
203
+ @dataclass(frozen=True)
204
+ class _Instruments:
205
+ agent_duration: Histogram
206
+ tool_duration: Histogram
207
+ inference_calls: Histogram
208
+ tool_calls: Histogram
209
+ token_usage: Histogram
210
+
211
+
212
+ _CALL_COUNT_BUCKETS = [0, 1, 2, 3, 4, 5, 6, 8, 12, 16, 24, 32, 64, 128, 256, 512]
213
+
214
+
215
+ def _create_instruments(meter_provider: MeterProvider) -> _Instruments:
216
+ # Same meter name as ADK, so existing dashboards pick these up.
217
+ meter = meter_provider.get_meter("gcp.vertex.agent")
218
+ return _Instruments(
219
+ agent_duration=meter.create_histogram(
220
+ "gen_ai.invoke_agent.duration",
221
+ unit="s",
222
+ description="Duration of agent invocations.",
223
+ explicit_bucket_boundaries_advisory=[0.1 * 2**i for i in range(13)],
224
+ ),
225
+ tool_duration=meter.create_histogram(
226
+ "gen_ai.execute_tool.duration",
227
+ unit="s",
228
+ description="Duration of tool executions.",
229
+ explicit_bucket_boundaries_advisory=[0.01 * 2**i for i in range(14)],
230
+ ),
231
+ inference_calls=meter.create_histogram(
232
+ "gen_ai.invoke_agent.inference_calls",
233
+ unit="1",
234
+ description="Number of inference (model) calls per agent invocation.",
235
+ explicit_bucket_boundaries_advisory=_CALL_COUNT_BUCKETS,
236
+ ),
237
+ tool_calls=meter.create_histogram(
238
+ "gen_ai.invoke_agent.tool_calls",
239
+ unit="1",
240
+ description="Number of tool calls per agent invocation.",
241
+ explicit_bucket_boundaries_advisory=_CALL_COUNT_BUCKETS,
242
+ ),
243
+ token_usage=meter.create_histogram(
244
+ "gen_ai.client.token.usage",
245
+ unit="{token}",
246
+ description="Number of input and output tokens used.",
247
+ explicit_bucket_boundaries_advisory=[4**i for i in range(14)],
248
+ ),
249
+ )
250
+
251
+
252
+ def _error_type(span: ReadableSpan) -> str:
253
+ """The recorded exception's unqualified class name, else _OTHER."""
254
+ for event in span.events:
255
+ if event.name == "exception" and event.attributes:
256
+ name = str(event.attributes.get("exception.type", "_OTHER"))
257
+ return name.rsplit(".", 1)[-1]
258
+ return "_OTHER"
259
+
260
+
261
+ def _warn_metrics_failure(error: object) -> None:
262
+ global _metrics_failing
263
+ if not _metrics_failing:
264
+ logging.warning(
265
+ "Exporting agent metrics to Cloud Monitoring failed: %s. The next "
266
+ "export sends the totals again; the service account needs "
267
+ "roles/monitoring.metricWriter.",
268
+ error,
269
+ )
270
+ _metrics_failing = True
@@ -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
+ """On Agent Runtime, export each request's telemetry before its response ends.
16
+
17
+ Agent Runtime throttles the CPU once a response ends, starving background
18
+ exports.
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import logging
24
+ import threading
25
+ import time
26
+ from collections.abc import Callable
27
+ from dataclasses import dataclass
28
+ from typing import Any
29
+
30
+ import anyio
31
+ from opentelemetry.sdk.metrics.export import MetricReader
32
+
33
+ from app.app_utils.telemetry.config import FLUSH_TIMEOUT_MILLIS
34
+
35
+ # Cloud Monitoring rejects points on one time series written closer than this.
36
+ _MIN_COLLECT_SECONDS = 5.0
37
+
38
+
39
+ @dataclass(frozen=True)
40
+ class _RequestFlush:
41
+ tracer_provider: Any
42
+ logger_provider: Any
43
+ reader: MetricReader
44
+
45
+
46
+ _request_flush: _RequestFlush | None = None
47
+ _collect_lock = threading.Lock()
48
+ _last_collect = float("-inf")
49
+
50
+
51
+ def enable_request_flush(
52
+ tracer_provider: Any, logger_provider: Any, reader: MetricReader
53
+ ) -> None:
54
+ """Make FlushTelemetryMiddleware flush these before each response ends."""
55
+ global _request_flush
56
+ _request_flush = _RequestFlush(tracer_provider, logger_provider, reader)
57
+
58
+
59
+ class FlushTelemetryMiddleware:
60
+ """Exports each POST request's telemetry before its last body chunk.
61
+
62
+ No-op until enable_request_flush() runs, which only happens on Agent Runtime.
63
+ Agent turns arrive as POSTs; health checks and agent card reads don't wait.
64
+ """
65
+
66
+ def __init__(self, app: Callable[..., Any]) -> None:
67
+ self.app = app
68
+
69
+ async def __call__(self, scope: Any, receive: Any, send: Any) -> None:
70
+ flush = _request_flush
71
+ if flush is None or scope["type"] != "http" or scope.get("method") != "POST":
72
+ await self.app(scope, receive, send)
73
+ return
74
+
75
+ async def send_after_flush(message: Any) -> None:
76
+ if message["type"] == "http.response.body" and not message.get("more_body"):
77
+ await anyio.to_thread.run_sync(_flush_request_telemetry, flush)
78
+ await send(message)
79
+
80
+ await self.app(scope, receive, send_after_flush)
81
+
82
+
83
+ def _flush_request_telemetry(flush: _RequestFlush) -> None:
84
+ """Export the request's spans, log records and, if due, metrics."""
85
+ try:
86
+ flush.tracer_provider.force_flush(FLUSH_TIMEOUT_MILLIS)
87
+ flush.logger_provider.force_flush(FLUSH_TIMEOUT_MILLIS)
88
+ _collect_metrics_if_due(flush.reader)
89
+ except Exception as e: # never fail the request it rides on
90
+ logging.warning("Exporting the request's telemetry failed: %s", e)
91
+
92
+
93
+ def _collect_metrics_if_due(reader: MetricReader) -> None:
94
+ global _last_collect
95
+ # While another request collects, skip rather than wait: this request's
96
+ # points go out with the next collect, as they do within the 5 s window.
97
+ if not _collect_lock.acquire(blocking=False):
98
+ return
99
+ try:
100
+ if time.monotonic() - _last_collect >= _MIN_COLLECT_SECONDS:
101
+ _last_collect = time.monotonic()
102
+ reader.collect(timeout_millis=FLUSH_TIMEOUT_MILLIS)
103
+ finally:
104
+ _collect_lock.release()
@@ -0,0 +1,80 @@
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
+
16
+ """Names one turn's subagent spans, which OpenInference leaves unnamed."""
17
+
18
+ from __future__ import annotations
19
+
20
+ from collections.abc import Callable
21
+ from contextvars import ContextVar
22
+ from typing import Any
23
+
24
+ from openinference.semconv.trace import SpanAttributes
25
+
26
+
27
+ class SubagentSpans:
28
+ """Names one turn's subagent spans, and finds the span of each subagent.
29
+
30
+ OpenInference doesn't say which Agent call a subagent span is for, so the
31
+ first message with a new parent_tool_use_id claims the newest unclaimed span.
32
+ """
33
+
34
+ def __init__(self, agent_name: Callable[[str | None], str]) -> None:
35
+ self._agent_name = agent_name
36
+ self._turn_started = False
37
+ self._unclaimed: dict[int, tuple[Any, list[Any]]] = {}
38
+ self._subagent_spans: dict[str, Any] = {}
39
+ self._span_agents: dict[int, str] = {}
40
+
41
+ def observe(self, message: Any) -> None:
42
+ """Claim a span for the subagent that sent `message`, if it has none yet."""
43
+ parent = getattr(message, "parent_tool_use_id", None)
44
+ if parent and parent not in self._subagent_spans and self._unclaimed:
45
+ self._claim(parent, *self._unclaimed.popitem()[1])
46
+
47
+ def subagent_span(self, parent_tool_use_id: str) -> Any:
48
+ """The span of the subagent whose messages have this parent, if any."""
49
+ return self._subagent_spans.get(parent_tool_use_id)
50
+
51
+ def span_started(self, span: Any) -> str | None:
52
+ """The name for one of the turn's OpenInference spans, if not the agent's."""
53
+ attributes = span.attributes or {}
54
+ if attributes.get(SpanAttributes.OPENINFERENCE_SPAN_KIND) == "AGENT":
55
+ # The first is the turn's own span; later ones are subagents'.
56
+ if self._turn_started:
57
+ self._unclaimed[span.get_span_context().span_id] = (span, [])
58
+ self._turn_started = True
59
+ return None
60
+ parent = span.parent.span_id if span.parent else None
61
+ if parent in self._unclaimed:
62
+ self._unclaimed[parent][1].append(span)
63
+ return self._span_agents.get(parent)
64
+
65
+ def _claim(self, parent_tool_use_id: str, span: Any, children: list[Any]) -> None:
66
+ name = self._agent_name(parent_tool_use_id)
67
+ span.update_name(f"ClaudeAgentSDK.{name}")
68
+ span.set_attributes(
69
+ {SpanAttributes.AGENT_NAME: name, "gen_ai.agent.name": name}
70
+ )
71
+ for child in children:
72
+ child.set_attribute("gen_ai.agent.name", name)
73
+ self._subagent_spans[parent_tool_use_id] = span
74
+ self._span_agents[span.get_span_context().span_id] = name
75
+
76
+
77
+ # The running turn's subagent spans, for naming spans as they start.
78
+ current_subagent_spans: ContextVar[SubagentSpans | None] = ContextVar(
79
+ "current_subagent_spans", default=None
80
+ )
@@ -0,0 +1,166 @@
1
+ # Copyright 2026 Google LLC
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+ """The server's spans: OpenInference instrumentation, and export to Cloud Trace."""
16
+
17
+ from __future__ import annotations
18
+
19
+ import logging
20
+ import os
21
+ from typing import Any
22
+
23
+ from openinference.instrumentation import REDACTED_VALUE, TraceConfig
24
+ from openinference.semconv.trace import SpanAttributes
25
+ from opentelemetry.sdk.trace import SpanProcessor, TracerProvider
26
+ from opentelemetry.sdk.trace.sampling import Decision, Sampler, SamplingResult
27
+ from opentelemetry.trace import NoOpTracer
28
+ from opentelemetry.util.genai.types import TextPart
29
+ from opentelemetry.util.genai.utils import gen_ai_json_dumps
30
+
31
+ from app.app_utils.telemetry import config
32
+ from app.app_utils.telemetry.subagent_spans import current_subagent_spans
33
+ from app.app_utils.turn_events import system_prompt_text
34
+
35
+
36
+ def install_instrumentation() -> None:
37
+ try:
38
+ from openinference.instrumentation.claude_agent_sdk import (
39
+ ClaudeAgentSDKInstrumentor,
40
+ )
41
+
42
+ ClaudeAgentSDKInstrumentor().instrument(config=_trace_config())
43
+ except Exception as e: # pragma: no cover - optional dependency
44
+ logging.warning("Claude Agent SDK instrumentation unavailable: %s", e)
45
+
46
+
47
+ def setup_cloud_tracing(
48
+ credentials: Any, resource: Any, project_id: str
49
+ ) -> TracerProvider:
50
+ """A tracer provider that names the agent's spans and exports them to Cloud Trace."""
51
+ from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
52
+ OTLPSpanExporter,
53
+ )
54
+ from opentelemetry.sdk.resources import OTELResourceDetector, Resource
55
+ from opentelemetry.sdk.trace.export import BatchSpanProcessor
56
+ from opentelemetry.sdk.trace.sampling import ALWAYS_ON
57
+
58
+ # Cloud Run and Agent Runtime front ends usually mark traceparent not
59
+ # sampled, so a parent-based sampler would drop every span.
60
+ sampler = None if os.environ.get("OTEL_TRACES_SAMPLER") else ALWAYS_ON
61
+ # Spans only: logs and metrics need the detected resource to map to their
62
+ # Cloud Logging and Cloud Monitoring resources.
63
+ span_resource = resource.merge(
64
+ Resource(config.agent_runtime_attributes(project_id))
65
+ ).merge(OTELResourceDetector().detect())
66
+ tracer_provider = _TracerProvider(resource=span_resource, sampler=sampler)
67
+ tracer_provider.add_span_processor(AgentNameProcessor(config.agent_name()))
68
+ session, upstream = config.telemetry_session(credentials)
69
+ tracer_provider.add_span_processor(
70
+ BatchSpanProcessor(
71
+ OTLPSpanExporter(session=session, endpoint=f"{upstream}/v1/traces")
72
+ )
73
+ )
74
+ return tracer_provider
75
+
76
+
77
+ class AgentNameProcessor(SpanProcessor):
78
+ """Adds gen_ai.agent.name to the agent's and its tools' spans."""
79
+
80
+ def __init__(self, agent_name: str) -> None:
81
+ self._agent_name = agent_name
82
+
83
+ def on_start(self, span: Any, parent_context: Any = None) -> None:
84
+ attributes = span.attributes or {}
85
+ if SpanAttributes.OPENINFERENCE_SPAN_KIND not in attributes:
86
+ return
87
+ subagent_spans = current_subagent_spans.get()
88
+ name = subagent_spans.span_started(span) if subagent_spans is not None else None
89
+ if name is not None:
90
+ span.set_attribute("gen_ai.agent.name", name)
91
+ elif SpanAttributes.AGENT_NAME not in attributes:
92
+ span.set_attribute("gen_ai.agent.name", self._agent_name)
93
+
94
+
95
+ # NOTE: The OpenTelemetry GenAI conventions are adding memory operations (a
96
+ # search_memory span with gen_ai.memory.records). Once a released version defines
97
+ # them, record recalled memories that way.
98
+ def system_prompt_attributes(system_prompt: Any) -> dict[str, str]:
99
+ """The turn span's record of the system prompt the model got, as ADK's.
100
+
101
+ Empty unless content capture is on: the prompt can hold the user's memories.
102
+ """
103
+ text = system_prompt_text(system_prompt)
104
+ if not text or not config.capture_content():
105
+ return {}
106
+ return {"gen_ai.system_instructions": gen_ai_json_dumps([TextPart(content=text)])}
107
+
108
+
109
+ def _trace_config() -> TraceConfig:
110
+ os.environ.setdefault("OPENINFERENCE_ENABLE_GENAI_SEMCONV", "true")
111
+ if not config.capture_content():
112
+ os.environ.setdefault("OPENINFERENCE_HIDE_INPUTS", "true")
113
+ os.environ.setdefault("OPENINFERENCE_HIDE_OUTPUTS", "true")
114
+ return _TraceConfig()
115
+
116
+
117
+ class _TraceConfig(TraceConfig):
118
+ """Also hides tool.parameters when inputs are hidden; OpenInference doesn't."""
119
+
120
+ def mask(self, key, value, *, externalize: bool = True):
121
+ if self.hide_inputs and key == SpanAttributes.TOOL_PARAMETERS:
122
+ return REDACTED_VALUE
123
+ return super().mask(key, value, externalize=externalize)
124
+
125
+
126
+ # MCP spans duplicate OpenInference's tool spans; BigQuery spans come from
127
+ # BigQuery Agent Analytics' own writes.
128
+ _UNRECORDED_SCOPES = ("mcp-python-sdk", "google.cloud.bigquery")
129
+
130
+
131
+ class _TracerProvider(TracerProvider):
132
+ """Gives _UNRECORDED_SCOPES no-op tracers, and records unsampled spans.
133
+
134
+ No-op tracers rather than export filtering, so child spans keep a parent
135
+ that exists.
136
+ """
137
+
138
+ def __init__(self, *args: Any, **kwargs: Any) -> None:
139
+ super().__init__(*args, **kwargs)
140
+ self.sampler = _RecordUnsampled(self.sampler)
141
+
142
+ def get_tracer(self, instrumenting_module_name: str, *args: Any, **kwargs: Any):
143
+ if instrumenting_module_name.startswith(_UNRECORDED_SCOPES):
144
+ return NoOpTracer()
145
+ return super().get_tracer(instrumenting_module_name, *args, **kwargs)
146
+
147
+
148
+ class _RecordUnsampled(Sampler):
149
+ """Records dropped spans without sampling them.
150
+
151
+ OpenInference fails a turn whose span isn't recording.
152
+ """
153
+
154
+ def __init__(self, sampler: Sampler) -> None:
155
+ self._sampler = sampler
156
+
157
+ def should_sample(self, *args: Any, **kwargs: Any) -> SamplingResult:
158
+ result = self._sampler.should_sample(*args, **kwargs)
159
+ if result.decision is not Decision.DROP:
160
+ return result
161
+ return SamplingResult(
162
+ Decision.RECORD_ONLY, result.attributes, result.trace_state
163
+ )
164
+
165
+ def get_description(self) -> str:
166
+ return self._sampler.get_description()