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,266 @@
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 Claude Code CLI's spans: a local relay to Cloud Trace, and the CLI's env.
16
+
17
+ The relay also adds ADK's gen_ai.usage.* attributes to the CLI's model-call
18
+ spans, and records their token usage.
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import gzip
24
+ import logging
25
+ import os
26
+ import queue
27
+ import threading
28
+ from collections.abc import Callable
29
+ from dataclasses import dataclass
30
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
31
+ from typing import Any
32
+
33
+ from app.app_utils.telemetry import config, metrics
34
+
35
+ # If you set any of these, the Claude Code CLI's telemetry is left to you.
36
+ _USER_CLI_TELEMETRY_VARS = (
37
+ "CLAUDE_CODE_ENABLE_TELEMETRY",
38
+ "OTEL_TRACES_EXPORTER",
39
+ "OTEL_EXPORTER_OTLP_ENDPOINT",
40
+ "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
41
+ )
42
+
43
+ # Statuses the CLI's OTLP exporter retries on.
44
+ _RETRIED_STATUSES = (429, 502, 503, 504)
45
+
46
+ # gen_ai.usage.input_tokens includes the cache tokens.
47
+ _CLI_LLM_SPAN = "claude_code.llm_request"
48
+ _CLI_CACHE_TOKENS = ("cache_read_tokens", "cache_creation_tokens")
49
+
50
+
51
+ @dataclass(frozen=True)
52
+ class _CliExport:
53
+ endpoint: str
54
+ project_id: str
55
+
56
+
57
+ _cli_export: _CliExport | None = None
58
+
59
+
60
+ def enable_cli_export(credentials: Any, project_id: str) -> None:
61
+ """Relay the CLI's spans to Cloud Trace, unless you configured its telemetry."""
62
+ global _cli_export
63
+ if any(os.environ.get(v) for v in _USER_CLI_TELEMETRY_VARS):
64
+ return
65
+ endpoint = start_trace_forwarder(lambda: config.telemetry_session(credentials))
66
+ _cli_export = _CliExport(endpoint, project_id)
67
+
68
+
69
+ def cli_telemetry_env() -> dict[str, str]:
70
+ """Environment that makes the Claude Code CLI export its spans, if enabled."""
71
+ if _cli_export is None:
72
+ return {}
73
+ runtime = config.agent_runtime_attributes(_cli_export.project_id)
74
+ engine_id = runtime.pop("service.name", None)
75
+ service_name = (
76
+ os.environ.get("OTEL_SERVICE_NAME") or engine_id or config.service_name()
77
+ )
78
+ env = {
79
+ "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
80
+ "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1",
81
+ "OTEL_TRACES_EXPORTER": "otlp",
82
+ # Never "console": the CLI's stdout carries the SDK's messages.
83
+ "OTEL_METRICS_EXPORTER": "none",
84
+ "OTEL_LOGS_EXPORTER": "none",
85
+ "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
86
+ "OTEL_EXPORTER_OTLP_ENDPOINT": _cli_export.endpoint,
87
+ "OTEL_RESOURCE_ATTRIBUTES": _resource_attributes(
88
+ runtime, _cli_export.project_id
89
+ ),
90
+ "OTEL_SERVICE_NAME": service_name,
91
+ }
92
+ if config.capture_content():
93
+ for var in (
94
+ "OTEL_LOG_USER_PROMPTS",
95
+ "OTEL_LOG_TOOL_DETAILS",
96
+ "OTEL_LOG_TOOL_CONTENT",
97
+ ):
98
+ env[var] = os.environ.get(var, "1")
99
+ return env
100
+
101
+
102
+ def start_trace_forwarder(new_session: Callable[[], tuple[Any, str]]) -> str:
103
+ """Relay the CLI's OTLP trace exports from 127.0.0.1 to the Telemetry API.
104
+
105
+ The CLI can't mint Google credentials, so the sessions `new_session` makes
106
+ add them; it returns a session and the upstream it sends to. Returns the
107
+ endpoint for the CLI's OTEL_EXPORTER_OTLP_ENDPOINT.
108
+ """
109
+ # Each request runs on its own thread and takes a session no other request
110
+ # holds: sessions aren't thread-safe. The first is made now, so a bad
111
+ # credential setup fails at startup.
112
+ idle: queue.SimpleQueue[tuple[Any, str]] = queue.SimpleQueue()
113
+ idle.put(new_session())
114
+
115
+ class Handler(BaseHTTPRequestHandler):
116
+ def do_POST(self) -> None:
117
+ if self.path != "/v1/traces":
118
+ self.send_error(404)
119
+ return
120
+ body = self.rfile.read(int(self.headers.get("Content-Length") or 0))
121
+ headers = {
122
+ k: self.headers[k]
123
+ for k in ("Content-Type", "Content-Encoding")
124
+ if self.headers.get(k)
125
+ }
126
+ body, calls = _with_genai_usage(body, headers)
127
+ try:
128
+ session, upstream = idle.get_nowait()
129
+ except queue.Empty:
130
+ session, upstream = new_session()
131
+ try:
132
+ response = session.post(
133
+ f"{upstream}/v1/traces", data=body, headers=headers, timeout=10
134
+ )
135
+ except Exception as e:
136
+ logging.warning("Forwarding Claude Code CLI spans failed: %s", e)
137
+ self.send_error(502)
138
+ return
139
+ finally:
140
+ idle.put((session, upstream))
141
+ # The CLI retries these, so count tokens only on the final attempt.
142
+ if response.status_code not in _RETRIED_STATUSES:
143
+ for model, usage in calls:
144
+ metrics.record_token_usage(model, usage)
145
+ if response.status_code >= 400:
146
+ logging.warning(
147
+ "Cloud Trace rejected Claude Code CLI spans (%s): %s",
148
+ response.status_code,
149
+ response.text[:500],
150
+ )
151
+ self.send_response(response.status_code)
152
+ self.send_header(
153
+ "Content-Type",
154
+ response.headers.get("Content-Type", "application/x-protobuf"),
155
+ )
156
+ self.send_header("Content-Length", str(len(response.content)))
157
+ self.end_headers()
158
+ self.wfile.write(response.content)
159
+
160
+ def log_message(self, format: str, *args: Any) -> None:
161
+ pass
162
+
163
+ server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
164
+ server.daemon_threads = True
165
+ threading.Thread(
166
+ target=server.serve_forever, name="otlp-forwarder", daemon=True
167
+ ).start()
168
+ return f"http://127.0.0.1:{server.server_port}"
169
+
170
+
171
+ def _resource_attributes(runtime: dict[str, str], project_id: str) -> str:
172
+ """OTEL_RESOURCE_ATTRIBUTES for the CLI: Agent Runtime's, then the user's."""
173
+ # The Telemetry API rejects spans whose resource lacks gcp.project_id.
174
+ user_attributes = os.environ.get("OTEL_RESOURCE_ATTRIBUTES", "")
175
+ if "gcp.project_id=" not in user_attributes:
176
+ user_attributes = ",".join(
177
+ filter(None, [user_attributes, f"gcp.project_id={project_id}"])
178
+ )
179
+ # User attributes come last so they override.
180
+ return ",".join(
181
+ [*(f"{key}={value}" for key, value in runtime.items()), user_attributes]
182
+ )
183
+
184
+
185
+ def _with_genai_usage(
186
+ body: bytes, headers: dict[str, str]
187
+ ) -> tuple[bytes, list[tuple[str, dict[str, Any]]]]:
188
+ """The export with gen_ai.usage.* added, if it's protobuf; else unchanged.
189
+
190
+ Decompresses a gzipped body, and drops its Content-Encoding from `headers`.
191
+ """
192
+ if headers.get("Content-Type") != "application/x-protobuf":
193
+ return body, []
194
+ try:
195
+ if headers.get("Content-Encoding") == "gzip":
196
+ body = gzip.decompress(body)
197
+ headers.pop("Content-Encoding")
198
+ return _add_genai_usage(body)
199
+ except Exception as e: # never lose spans over the extra attributes
200
+ logging.debug("Could not add GenAI usage to CLI spans: %s", e)
201
+ return body, []
202
+
203
+
204
+ def _add_genai_usage(body: bytes) -> tuple[bytes, list[tuple[str, dict[str, Any]]]]:
205
+ """Add gen_ai.usage.* to the CLI's model-call spans in an OTLP export.
206
+
207
+ Also returns each call's model and usage.
208
+ """
209
+ if _CLI_LLM_SPAN.encode() not in body:
210
+ return body, []
211
+ from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import (
212
+ ExportTraceServiceRequest,
213
+ )
214
+ from opentelemetry.proto.common.v1.common_pb2 import AnyValue, KeyValue
215
+
216
+ request = ExportTraceServiceRequest.FromString(body)
217
+ calls = []
218
+ for resource_spans in request.resource_spans:
219
+ for scope_spans in resource_spans.scope_spans:
220
+ for span in scope_spans.spans:
221
+ if span.name != _CLI_LLM_SPAN:
222
+ continue
223
+ present = {kv.key: kv.value for kv in span.attributes}
224
+ usage = _genai_usage(_token_counts(present))
225
+ model = present.get("model")
226
+ calls.append((model.string_value if model else "", usage))
227
+ for key, value in usage.items():
228
+ if key in present:
229
+ continue
230
+ any_value = (
231
+ AnyValue(int_value=value)
232
+ if isinstance(value, int)
233
+ else AnyValue(string_value=value)
234
+ )
235
+ span.attributes.append(KeyValue(key=key, value=any_value))
236
+ return request.SerializeToString(), calls
237
+
238
+
239
+ def _token_counts(attributes: dict[str, Any]) -> dict[str, int]:
240
+ """The CLI's token counts among a span's attributes, sent as int or string."""
241
+ counts = {}
242
+ for key in ("input_tokens", "output_tokens", *_CLI_CACHE_TOKENS):
243
+ value = attributes.get(key)
244
+ if value is None:
245
+ continue
246
+ raw = value.int_value if value.HasField("int_value") else value.string_value
247
+ if str(raw).isdigit():
248
+ counts[key] = int(raw)
249
+ return counts
250
+
251
+
252
+ def _genai_usage(counts: dict[str, int]) -> dict[str, Any]:
253
+ usage: dict[str, Any] = {"gen_ai.operation.name": "generate_content"}
254
+ if "input_tokens" in counts:
255
+ usage["gen_ai.usage.input_tokens"] = counts["input_tokens"] + sum(
256
+ counts.get(key, 0) for key in _CLI_CACHE_TOKENS
257
+ )
258
+ if "output_tokens" in counts:
259
+ usage["gen_ai.usage.output_tokens"] = counts["output_tokens"]
260
+ if "cache_read_tokens" in counts:
261
+ usage["gen_ai.usage.cache_read.input_tokens"] = counts["cache_read_tokens"]
262
+ if "cache_creation_tokens" in counts:
263
+ usage["gen_ai.usage.cache_creation.input_tokens"] = counts[
264
+ "cache_creation_tokens"
265
+ ]
266
+ return usage
@@ -0,0 +1,133 @@
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
+ """Settings every telemetry signal shares: names, resource, Telemetry API access."""
16
+
17
+ from __future__ import annotations
18
+
19
+ import logging
20
+ import os
21
+ import uuid
22
+ from typing import Any
23
+
24
+ from app.app_utils import settings
25
+
26
+ _TELEMETRY_ENDPOINT = "https://telemetry.googleapis.com"
27
+ _MTLS_TELEMETRY_ENDPOINT = "https://telemetry.mtls.googleapis.com"
28
+
29
+ FLUSH_TIMEOUT_MILLIS = 5_000
30
+
31
+
32
+ def cloud_export_enabled() -> bool:
33
+ value = os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY")
34
+ return value is None or value.lower() in ("true", "1")
35
+
36
+
37
+ def capture_content() -> bool:
38
+ """Whether prompts, replies and tool arguments and results go into spans."""
39
+ capture = os.environ.get("OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT", "")
40
+ return capture.lower() not in ("", "false", "no_content")
41
+
42
+
43
+ def on_agent_runtime() -> bool:
44
+ return bool(os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ID"))
45
+
46
+
47
+ def agent_runtime_location() -> str:
48
+ return os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_LOCATION") or os.environ.get(
49
+ "GOOGLE_CLOUD_LOCATION", ""
50
+ )
51
+
52
+
53
+ def service_name() -> str:
54
+ return os.environ.get("OTEL_SERVICE_NAME") or os.environ.get(
55
+ "K_SERVICE", "claude-agent"
56
+ )
57
+
58
+
59
+ def agent_name() -> str:
60
+ name = settings.AGENT_NAME
61
+ return service_name() if not name or "{{" in name else name
62
+
63
+
64
+ def build_resource(project_id: str) -> Any:
65
+ """Build the Resource; OTEL_* env vars, then GCP detection, override defaults."""
66
+ from opentelemetry.sdk.resources import OTELResourceDetector, Resource
67
+
68
+ resource = Resource.create(
69
+ {
70
+ "service.name": service_name(),
71
+ "service.version": os.environ.get("COMMIT_SHA", "dev"),
72
+ "service.instance.id": f"{uuid.uuid4().hex}-{os.getpid()}",
73
+ # The Telemetry API rejects spans whose resource lacks gcp.project_id.
74
+ "gcp.project_id": project_id,
75
+ "cloud.account.id": project_id,
76
+ }
77
+ )
78
+ resource = resource.merge(OTELResourceDetector().detect())
79
+ try:
80
+ from opentelemetry.resourcedetector.gcp_resource_detector import (
81
+ GoogleCloudResourceDetector,
82
+ )
83
+
84
+ resource = resource.merge(
85
+ GoogleCloudResourceDetector(raise_on_error=False).detect()
86
+ )
87
+ except Exception as e: # best-effort; unavailable off-GCP
88
+ logging.debug("GCP resource detection skipped: %s", e)
89
+ return resource
90
+
91
+
92
+ def agent_runtime_attributes(project_id: str) -> dict[str, str]:
93
+ """Span resource attributes for this Agent Runtime engine; empty elsewhere.
94
+
95
+ The Agent Runtime console finds an engine's traces by cloud.resource_id.
96
+ """
97
+ engine_id = os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ID")
98
+ if not engine_id:
99
+ return {}
100
+ location = agent_runtime_location()
101
+ attributes = {
102
+ "cloud.provider": "gcp",
103
+ "cloud.platform": "gcp.agent_engine",
104
+ "service.name": engine_id,
105
+ "service.version": os.environ.get(
106
+ "GOOGLE_CLOUD_AGENT_ENGINE_RUNTIME_REVISION_ID", ""
107
+ ),
108
+ "cloud.region": location,
109
+ }
110
+ if location:
111
+ attributes["cloud.resource_id"] = (
112
+ f"//aiplatform.googleapis.com/projects/{project_id}"
113
+ f"/locations/{location}/reasoningEngines/{engine_id}"
114
+ )
115
+ return {key: value for key, value in attributes.items() if value}
116
+
117
+
118
+ def telemetry_session(credentials: Any) -> tuple[Any, str]:
119
+ """An authorized session for the Telemetry API, and the endpoint to use.
120
+
121
+ With a client certificate (Agent Identity on Agent Runtime), tokens are
122
+ bound to it and only accepted over mTLS. Make one session per exporter:
123
+ requests sessions aren't thread-safe.
124
+ """
125
+ from google.auth.transport import mtls
126
+ from google.auth.transport.requests import AuthorizedSession
127
+
128
+ session = AuthorizedSession(credentials)
129
+ if mtls.should_use_client_cert():
130
+ session.configure_mtls_channel()
131
+ if session.is_mtls:
132
+ return session, _MTLS_TELEMETRY_ENDPOINT
133
+ return session, _TELEMETRY_ENDPOINT
@@ -0,0 +1,175 @@
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
+ """Python log records and GenAI events, exported to Cloud Logging.
16
+
17
+ Nothing is sent until setup_cloud_logging() runs.
18
+ """
19
+
20
+ from __future__ import annotations
21
+
22
+ import logging
23
+ import os
24
+ from collections.abc import Mapping
25
+ from typing import Any
26
+
27
+ from opentelemetry import context as otel_context
28
+ from opentelemetry._logs import LogRecord, SeverityNumber
29
+
30
+ from app.app_utils.telemetry import config
31
+
32
+ # Cloud Logging log names; GCP_DEFAULT_LOG_NAME overrides both.
33
+ _AGENT_RUNTIME_LOG_NAME = "aiplatform.googleapis.com/reasoning_engine_stdout"
34
+ _LOG_NAME = "adk-otel"
35
+
36
+ # GenAI events are emitted under the telemetry package's name.
37
+ _EVENT_LOGGER_NAME = __name__.rpartition(".")[0]
38
+
39
+ _logger_provider: Any = None
40
+
41
+
42
+ def setup_cloud_logging(credentials: Any, resource: Any, project_id: str) -> Any:
43
+ """Send Python log records to Cloud Logging too; return the LoggerProvider."""
44
+ from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
45
+ from opentelemetry.sdk._logs import LoggerProvider
46
+ from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
47
+
48
+ global _logger_provider
49
+ resource = _log_resource(resource, project_id)
50
+ session, upstream = config.telemetry_session(credentials)
51
+ logger_provider = LoggerProvider(resource=resource)
52
+ logger_provider.add_log_record_processor(
53
+ BatchLogRecordProcessor(
54
+ OTLPLogExporter(session=session, endpoint=f"{upstream}/v1/logs")
55
+ )
56
+ )
57
+ _install_handler(
58
+ _CloudLoggingHandler(
59
+ logger_provider,
60
+ {
61
+ "gcp.log_name": _log_name(),
62
+ # Cloud Logging drops resource attributes, so send it as a label.
63
+ "service.version": str(resource.attributes.get("service.version", "")),
64
+ },
65
+ )
66
+ )
67
+ _logger_provider = logger_provider
68
+ return logger_provider
69
+
70
+
71
+ def emit_event(record: LogRecord) -> None:
72
+ """Send a GenAI event to Cloud Logging, in a log named after `event.name`."""
73
+ if _logger_provider is None:
74
+ return
75
+ attributes = dict(record.attributes or {})
76
+ attributes["gcp.log_name"] = (
77
+ _AGENT_RUNTIME_LOG_NAME
78
+ if config.on_agent_runtime()
79
+ else attributes["event.name"]
80
+ )
81
+ record.attributes = attributes
82
+ _logger_provider.get_logger(_EVENT_LOGGER_NAME).emit(record)
83
+
84
+
85
+ def _log_resource(resource: Any, project_id: str) -> Any:
86
+ """On Agent Runtime, the resource that files logs under the engine."""
87
+ from opentelemetry.sdk.resources import Resource
88
+
89
+ engine_id = os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ID")
90
+ if not engine_id:
91
+ return resource
92
+ # Logs only: on the metrics' resource, gcp.resource_type would move them
93
+ # off their monitored resource.
94
+ return resource.merge(
95
+ Resource(
96
+ {
97
+ "gcp.resource_type": "aiplatform.googleapis.com/ReasoningEngine",
98
+ "location": config.agent_runtime_location(),
99
+ "reasoning_engine_id": engine_id,
100
+ # Without "projects/" the Telemetry API rejects the records.
101
+ "resource_container": f"projects/{project_id}",
102
+ }
103
+ )
104
+ )
105
+
106
+
107
+ def _log_name() -> str:
108
+ return os.environ.get("GCP_DEFAULT_LOG_NAME") or (
109
+ _AGENT_RUNTIME_LOG_NAME if config.on_agent_runtime() else _LOG_NAME
110
+ )
111
+
112
+
113
+ def _install_handler(handler: logging.Handler) -> None:
114
+ root = logging.getLogger()
115
+ if not root.handlers:
116
+ # Keep stderr output, which Python drops once the root logger has a handler.
117
+ root.addHandler(logging.StreamHandler())
118
+ root.addHandler(handler)
119
+ # uvicorn's logger doesn't propagate; its access log is left out.
120
+ uvicorn = logging.getLogger("uvicorn")
121
+ if not uvicorn.propagate:
122
+ uvicorn.addHandler(handler)
123
+
124
+
125
+ _SEVERITIES = (
126
+ (logging.CRITICAL, SeverityNumber.FATAL, "FATAL"),
127
+ (logging.ERROR, SeverityNumber.ERROR, "ERROR"),
128
+ (logging.WARNING, SeverityNumber.WARN, "WARN"),
129
+ (logging.INFO, SeverityNumber.INFO, "INFO"),
130
+ (logging.NOTSET, SeverityNumber.DEBUG, "DEBUG"),
131
+ )
132
+
133
+
134
+ class _CloudLoggingHandler(logging.Handler):
135
+ """Hands Python log records to `logger_provider`, under the active span.
136
+
137
+ `extra=` fields are not copied into attributes.
138
+ """
139
+
140
+ def __init__(self, logger_provider: Any, attributes: Mapping[str, str]) -> None:
141
+ super().__init__()
142
+ self._logger_provider = logger_provider
143
+ self._attributes = dict(attributes)
144
+
145
+ def emit(self, record: logging.LogRecord) -> None:
146
+ # The OTel SDK's own records would feed back into the export.
147
+ if record.name.startswith("opentelemetry"):
148
+ return
149
+ try:
150
+ _, severity, severity_text = next(
151
+ s for s in _SEVERITIES if record.levelno >= s[0]
152
+ )
153
+ attributes: dict[str, Any] = {
154
+ **self._attributes,
155
+ "code.file.path": record.pathname,
156
+ "code.function.name": record.funcName,
157
+ "code.line.number": record.lineno,
158
+ }
159
+ if record.exc_info and record.exc_info[0]:
160
+ attributes["exception.type"] = record.exc_info[0].__name__
161
+ self._logger_provider.get_logger(record.name).emit(
162
+ LogRecord(
163
+ timestamp=int(record.created * 1e9),
164
+ context=otel_context.get_current(),
165
+ severity_number=severity,
166
+ severity_text=severity_text,
167
+ body=self.format(record),
168
+ attributes=attributes,
169
+ )
170
+ )
171
+ except Exception:
172
+ self.handleError(record)
173
+
174
+ def flush(self) -> None:
175
+ self._logger_provider.force_flush(config.FLUSH_TIMEOUT_MILLIS)