otelzero 0.2.0__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.
@@ -0,0 +1,331 @@
1
+ """smolagents instrumentation: wrap the shared multi-step run chokepoint.
2
+
3
+ Hugging Face's `smolagents <https://github.com/huggingface/smolagents>`_ builds
4
+ both of its agent flavours -- ``CodeAgent``, which writes its actions as Python,
5
+ and ``ToolCallingAgent``, which emits structured tool calls -- on one
6
+ ``MultiStepAgent`` base, and neither overrides ``run``. So a single wrap on
7
+ ``MultiStepAgent.run`` captures every agent in the library.
8
+
9
+ ``run`` is a *synchronous dispatcher* whose ``stream`` argument decides its
10
+ return shape: the final answer when it is false, and a generator of steps when it
11
+ is true. Unlike a framework that hands back an awaitable, the non-streaming call
12
+ does the whole run before returning -- so the span has to open *before* the call,
13
+ which means the streaming decision is read off the argument rather than the
14
+ returned object.
15
+
16
+ Token counts come from the agent's own monitor, which totals them across the
17
+ runs it has seen. otelzero reports the difference across each run, so a
18
+ continuation (``reset=False``) is charged only for what it actually spent rather
19
+ than for the conversation so far.
20
+ """
21
+
22
+ from typing import Any, Optional
23
+
24
+ import wrapt
25
+
26
+ from otelzero import semconv
27
+ from otelzero.hooks import _content
28
+ from otelzero.hooks._usage import extract_usage
29
+ from otelzero.hooks.base import _ImportInstrumenter, install_hook, trace_agent_run
30
+
31
+ # otelzero's own marker so a chokepoint is never wrapped twice.
32
+ _MARKER = "_otelzero_wrapped"
33
+
34
+
35
+ def _smolagents_model_id(model: Any) -> Optional[str]:
36
+ """Best-effort model identifier for a smolagents model object.
37
+
38
+ Every model in the library carries a ``model_id`` (``InferenceClientModel``,
39
+ ``LiteLLMModel``, ``TransformersModel``, ...); a hand-written callable model
40
+ has none, so fall back to the class name.
41
+ """
42
+ if model is None:
43
+ return None
44
+ if isinstance(model, str):
45
+ return model
46
+ for attr in ("model_id", "model_name"):
47
+ value = getattr(model, attr, None)
48
+ if isinstance(value, str) and value:
49
+ return value
50
+ return type(model).__name__
51
+
52
+
53
+ def _tool_names(agent: Any) -> list:
54
+ """Names of the tools available to the agent."""
55
+ tools = getattr(agent, "tools", None)
56
+ if isinstance(tools, dict):
57
+ return sorted(str(name) for name in tools)
58
+ return [str(getattr(t, "name", t)) for t in tools or []]
59
+
60
+
61
+ def _is_stream(args, kwargs) -> bool:
62
+ """Whether this call asked for the streaming shape.
63
+
64
+ Read off the argument, not the return value: ``run(stream=False)`` performs
65
+ the whole run before returning, so by the time there is a value to inspect
66
+ the run is over and the start event would be too late. ``stream`` is the
67
+ second positional parameter of ``run(task, stream=False, ...)``.
68
+ """
69
+ return bool(kwargs.get("stream", args[1] if len(args) > 1 else False))
70
+
71
+
72
+ def _monitor_usage(agent: Any) -> Optional[dict]:
73
+ """Cumulative token counts from the agent's monitor, normalized."""
74
+ monitor = getattr(agent, "monitor", None)
75
+ getter = getattr(monitor, "get_total_token_counts", None)
76
+ if not callable(getter):
77
+ return None
78
+ try:
79
+ raw = getter()
80
+ except Exception: # pragma: no cover - defensive
81
+ return None
82
+ usage = extract_usage(raw)
83
+ if usage is not None:
84
+ return usage
85
+ # Older smolagents returned ``{"input": n, "output": n}``. Those spellings are
86
+ # too generic to add to the shared alias table -- plenty of unrelated dicts
87
+ # have an "input" key -- so they are translated here instead.
88
+ if isinstance(raw, dict) and ("input" in raw or "output" in raw):
89
+ return extract_usage(
90
+ {"input_tokens": raw.get("input"), "output_tokens": raw.get("output")}
91
+ )
92
+ return None
93
+
94
+
95
+ def _usage_delta(before: Optional[dict], after: Optional[dict]) -> Optional[dict]:
96
+ """What this run spent, given the monitor's totals either side of it.
97
+
98
+ The monitor counts across runs, and ``run(reset=False)`` deliberately keeps
99
+ that history, so the totals alone would charge a continuation for the whole
100
+ conversation. Clamped at zero in case an agent resets its monitor mid-run.
101
+ """
102
+ if after is None:
103
+ return None
104
+ if before is None:
105
+ return after
106
+ delta = {
107
+ key: max((after.get(key) or 0) - (before.get(key) or 0), 0)
108
+ for key in ("input_tokens", "output_tokens", "total_tokens")
109
+ }
110
+ for key in ("reasoning_tokens", "cache_read_tokens"):
111
+ value = after.get(key)
112
+ delta[key] = None if value is None else max(value - (before.get(key) or 0), 0)
113
+ return delta
114
+
115
+
116
+ def _task(args, kwargs) -> Any:
117
+ """The run's task -- the first argument of ``run(task, ...)``.
118
+
119
+ Both wrappers need it: one to name the session, the other to record the
120
+ prompt, and the streaming shape reads it before the generator starts.
121
+ """
122
+ return kwargs.get("task", args[0] if args else None)
123
+
124
+
125
+ def _system_prompt(agent: Any) -> Optional[str]:
126
+ """The agent's system prompt, which smolagents keeps on its memory.
127
+
128
+ ``MultiStepAgent`` renders the prompt into a ``SystemPromptStep`` at
129
+ construction; an agent that was handed one directly keeps it on itself.
130
+ """
131
+ step = getattr(getattr(agent, "memory", None), "system_prompt", None)
132
+ text = getattr(step, "system_prompt", None)
133
+ if isinstance(text, str) and text:
134
+ return text
135
+ fallback = getattr(agent, "system_prompt", None)
136
+ return fallback if isinstance(fallback, str) else None
137
+
138
+
139
+ def _steps(agent: Any) -> list:
140
+ memory = getattr(getattr(agent, "memory", None), "steps", None)
141
+ return list(memory) if isinstance(memory, (list, tuple)) else []
142
+
143
+
144
+ def _step_count(agent: Any) -> int:
145
+ """How many memory steps the agent holds right now -- the run's watermark."""
146
+ return len(_steps(agent))
147
+
148
+
149
+ def _final_answer(step: Any) -> Any:
150
+ """A streamed ``FinalAnswerStep``'s answer; ``None`` for any other step.
151
+
152
+ ``stream=True`` yields every step, and only the last one carries the answer
153
+ ``stream=False`` would have returned. The intermediate steps are recorded
154
+ from memory instead, so passing one here would dump its repr as the
155
+ response.
156
+ """
157
+ return getattr(step, "output", None)
158
+
159
+
160
+ def _memory_messages(agent: Any, before: int) -> list:
161
+ """This run's slice of ``agent.memory.steps`` as semconv messages.
162
+
163
+ An ``ActionStep`` holds what the model asked a tool to do and what came
164
+ back, so without them a tool-using run reads as though the answer appeared
165
+ from nowhere. Walked only when content capture is opted in: the memory of a
166
+ long run is large, and the walk is pure cost otherwise.
167
+
168
+ ``run(reset=True)`` -- the default -- *clears* the memory before starting,
169
+ so the count taken before the call can exceed what is there afterwards. The
170
+ slice start is clamped for the same reason :func:`_usage_delta` clamps its
171
+ deltas.
172
+ """
173
+ if not _content.enabled():
174
+ return []
175
+ steps = _steps(agent)
176
+ messages = []
177
+ for step in steps[min(before, len(steps)) :]:
178
+ calls = getattr(step, "tool_calls", None) or []
179
+ parts = [
180
+ _content.tool_call_part(
181
+ getattr(call, "id", None),
182
+ getattr(call, "name", None),
183
+ getattr(call, "arguments", None),
184
+ )
185
+ for call in calls
186
+ ]
187
+ messages.append(_content.message("assistant", parts))
188
+ observations = getattr(step, "observations", None)
189
+ if observations is not None:
190
+ # One step runs one tool in practice; where it ran several there is
191
+ # still a single observation, which no single call id identifies.
192
+ call_id = getattr(calls[0], "id", None) if len(calls) == 1 else None
193
+ messages.append(
194
+ _content.message(
195
+ "tool", [_content.tool_call_response_part(call_id, observations)]
196
+ )
197
+ )
198
+ return [m for m in messages if m]
199
+
200
+
201
+ def _output_messages(agent: Any, before: int, result: Any) -> Optional[list]:
202
+ """The run's response: its tool hops, then the final answer."""
203
+ final = _content.messages_from(_content.text_of(result), default_role="assistant")
204
+ steps = _memory_messages(agent, before)
205
+ if steps:
206
+ return _content.cap_messages(steps + (final or []))
207
+ return final
208
+
209
+
210
+ class SmolagentsImportHook(_ImportInstrumenter):
211
+ """Intercept smolagents imports and instrument ``MultiStepAgent``.
212
+
213
+ Wraps ``smolagents.agents.MultiStepAgent.run`` -- the single entry point both
214
+ ``CodeAgent`` and ``ToolCallingAgent`` inherit -- so every agent run is
215
+ captured exactly once, in both the direct and the streaming shape.
216
+ """
217
+
218
+ WATCHED = {"smolagents.agents": "_wrap_agent_class"}
219
+
220
+ def _wrap_agent_class(self, module):
221
+ agent_cls = getattr(module, "MultiStepAgent", None)
222
+ if agent_cls is None:
223
+ return
224
+ original_run = getattr(agent_cls, "run", None)
225
+ if original_run is None or getattr(original_run, _MARKER, False):
226
+ return
227
+
228
+ telemetry = self.telemetry
229
+
230
+ def _traced(instance, args, kwargs):
231
+ """Build the trace context manager for one run."""
232
+ agent_name = getattr(instance, "name", None) or type(instance).__name__
233
+ model = _smolagents_model_id(getattr(instance, "model", None))
234
+ tools = _tool_names(instance)
235
+ task = _task(args, kwargs)
236
+ details = {"model": model, "tools": tools}
237
+ return trace_agent_run(
238
+ telemetry,
239
+ semconv.span_name(semconv.OP_INVOKE_AGENT, agent_name),
240
+ {
241
+ semconv.GEN_AI_OPERATION_NAME: semconv.OP_INVOKE_AGENT,
242
+ semconv.GEN_AI_AGENT_NAME: agent_name,
243
+ semconv.GEN_AI_REQUEST_MODEL: model,
244
+ semconv.GEN_AI_TOOL_DEFINITIONS: semconv.tool_definitions(tools),
245
+ },
246
+ start_event="agent_start",
247
+ end_event="agent_end",
248
+ error_event="agent_error",
249
+ log_fields={
250
+ "agent_name": agent_name,
251
+ "agent_role": agent_name,
252
+ "model": model,
253
+ },
254
+ start_details=details,
255
+ session_name_hint=task if isinstance(task, str) else None,
256
+ )
257
+
258
+ def _traced_steps(wrapped, instance, args, kwargs):
259
+ """Trace the streaming shape: a span around the step generator."""
260
+ before = _monitor_usage(instance)
261
+ steps_before = _step_count(instance)
262
+ with _traced(instance, args, kwargs) as run:
263
+ run.set_input(_content.messages_from(_task(args, kwargs)))
264
+ run.set_system(_system_prompt(instance))
265
+ final = None
266
+ try:
267
+ for step in wrapped(*args, **kwargs):
268
+ answer = _final_answer(step)
269
+ if answer is not None:
270
+ final = answer
271
+ yield step
272
+ finally:
273
+ # In the ``finally``: a consumer that breaks out early still
274
+ # reports the hops it did see, with no final answer.
275
+ run.set_usage(_usage_delta(before, _monitor_usage(instance)))
276
+ run.set_output(_output_messages(instance, steps_before, final))
277
+
278
+ @wrapt.decorator
279
+ def run_wrapper(wrapped, instance, args, kwargs):
280
+ if _is_stream(args, kwargs):
281
+ # A generator: the run happens as the caller iterates it, so the
282
+ # span belongs around the iteration rather than around this call.
283
+ return _traced_steps(wrapped, instance, args, kwargs)
284
+ before = _monitor_usage(instance)
285
+ steps_before = _step_count(instance)
286
+ with _traced(instance, args, kwargs) as run:
287
+ run.set_input(_content.messages_from(_task(args, kwargs)))
288
+ run.set_system(_system_prompt(instance))
289
+ result = wrapped(*args, **kwargs)
290
+ run.set_usage(_usage_delta(before, _monitor_usage(instance)))
291
+ run.set_output(_output_messages(instance, steps_before, result))
292
+ return result
293
+
294
+ wrapped_run = run_wrapper(original_run)
295
+ setattr(wrapped_run, _MARKER, True)
296
+ agent_cls.run = wrapped_run
297
+
298
+
299
+ def install_smolagents_monitoring(
300
+ server_url: str = "http://localhost:8000",
301
+ user: Optional[str] = None,
302
+ api_key: Optional[str] = None,
303
+ session: Optional[str] = None,
304
+ name: Optional[str] = None,
305
+ ):
306
+ """
307
+ Install smolagents monitoring instrumentation.
308
+
309
+ Instruments ``smolagents.agents.MultiStepAgent.run`` -- the entry point both
310
+ ``CodeAgent`` and ``ToolCallingAgent`` inherit -- so every agent run streams
311
+ start/end/error telemetry with zero changes to the agent code, in both the
312
+ direct and the ``stream=True`` shape. Call this *before* ``smolagents`` is
313
+ imported.
314
+
315
+ Args:
316
+ server_url: URL of the monitoring server
317
+ user: Name of the executing user
318
+ api_key: Ingest key tying events to an owner (for the iOS app)
319
+ session: Per-run id used to group events in the app
320
+ name: Explicit session title (else derived from the run's task)
321
+ """
322
+ return install_hook(
323
+ SmolagentsImportHook,
324
+ framework="smolagents",
325
+ label="smolagents",
326
+ server_url=server_url,
327
+ user=user,
328
+ api_key=api_key,
329
+ session=session,
330
+ name=name,
331
+ )
@@ -0,0 +1,271 @@
1
+ """Snowflake Cortex Agent SDK instrumentation: wrap the async-generator chokepoints.
2
+
3
+ Snowflake's `Cortex Code Agent SDK
4
+ <https://docs.snowflake.com/en/user-guide/cortex-code-agent-sdk/cortex-code-agent-sdk>`_
5
+ (the ``cortex_code_agent_sdk`` package) is shaped almost identically to the
6
+ Claude Agent SDK: a module-level ``query(prompt, options=...)`` async-generator
7
+ function and an interactive ``CortexCodeSDKClient`` whose ``receive_response()``
8
+ is an async generator, both configured by a ``CortexCodeAgentOptions`` dataclass
9
+ (``model`` / ``allowed_tools`` / ``mcp_servers`` / ...). This hook wraps both run
10
+ chokepoints so a run is captured exactly once whichever style the caller uses.
11
+ """
12
+
13
+ from typing import Any, Optional
14
+
15
+ import wrapt
16
+
17
+ from otelzero import semconv
18
+ from otelzero.hooks import _content
19
+ from otelzero.hooks._usage import UsageAccumulator, extract_usage
20
+ from otelzero.hooks.base import _ImportInstrumenter, install_hook, trace_agent_run
21
+
22
+
23
+ def _snowflake_model_id(options: Any) -> Optional[str]:
24
+ """Best-effort model identifier for a ``CortexCodeAgentOptions`` object.
25
+
26
+ ``CortexCodeAgentOptions.model`` is an optional model string (``None`` selects
27
+ the SDK/CLI default). Returns the string when set, else ``None``.
28
+ """
29
+ if options is None:
30
+ return None
31
+ model = getattr(options, "model", None)
32
+ if isinstance(model, str) and model:
33
+ return model
34
+ return None
35
+
36
+
37
+ def _options_details(options: Any) -> dict:
38
+ """Summarise a ``CortexCodeAgentOptions`` for a telemetry ``details`` payload.
39
+
40
+ Every field read degrades to a benign default so a run with no options (or
41
+ an SDK whose options shape has drifted) never breaks instrumentation.
42
+ """
43
+ allowed = getattr(options, "allowed_tools", None)
44
+ mcp = getattr(options, "mcp_servers", None)
45
+ return {
46
+ "model": _snowflake_model_id(options),
47
+ "allowed_tools": list(allowed) if allowed else [],
48
+ # CortexCodeAgentOptions.mcp_servers is a name -> config dict; surface just
49
+ # the server names (configs can hold secrets and are large).
50
+ "mcp_servers": sorted(mcp.keys()) if isinstance(mcp, dict) else None,
51
+ }
52
+
53
+
54
+ class SnowflakeCortexImportHook(_ImportInstrumenter):
55
+ """Intercept Cortex Code Agent SDK imports and instrument both run chokepoints.
56
+
57
+ The SDK exposes two entry points, both async generators, and this hook wraps
58
+ each so a run is captured exactly once whichever style the caller uses:
59
+
60
+ * ``cortex_code_agent_sdk.query(prompt, options)`` -- the one-shot path, a
61
+ module-level async-generator *function* (so the wrapper's ``instance`` is
62
+ ``None`` and options come from ``kwargs``).
63
+ * ``CortexCodeSDKClient.receive_response()`` -- the interactive path, an
64
+ async-generator *method* that yields one response turn's messages (options
65
+ live on the client instance).
66
+
67
+ ``CortexCodeSDKClient.query()`` is wrapped as well, though it is not a run:
68
+ it is where the interactive path's prompt goes out, so the prompt is
69
+ recorded there and attached to the ``receive_response()`` run that follows.
70
+
71
+ All are re-exported from the ``cortex_code_agent_sdk`` package ``__init__``,
72
+ so a single watched module covers them.
73
+ """
74
+
75
+ WATCHED = {"cortex_code_agent_sdk": "_wrap_module"}
76
+
77
+ # otelzero's own marker so we never double-wrap a chokepoint.
78
+ _MARKER = "_otelzero_wrapped"
79
+
80
+ def _wrap_module(self, module):
81
+ self._wrap_query(module)
82
+ self._wrap_client(module)
83
+
84
+ def _wrap_query(self, module):
85
+ """Wrap the module-level ``query`` async-generator function."""
86
+ query = getattr(module, "query", None)
87
+ if query is None or getattr(query, self._MARKER, False):
88
+ return
89
+
90
+ telemetry = self.telemetry
91
+
92
+ @wrapt.decorator
93
+ async def query_wrapper(wrapped, instance, args, kwargs):
94
+ # ``query`` takes options by keyword (``query(prompt, options=...)``).
95
+ options = kwargs.get("options")
96
+ details = _options_details(options)
97
+ # As input, a string or a materialised list is recorded up front;
98
+ # a streamed prompt is the SDK's to read, so the SDK gets a tee of
99
+ # the caller's iterable and the messages are recorded as they flow
100
+ # past (see ``_content.PromptTee``).
101
+ prompt = kwargs.get("prompt", args[0] if args else None)
102
+ tee = _content.PromptTee.wrap(prompt)
103
+ if tee is not None:
104
+ args, kwargs = _content.replace_prompt(args, kwargs, tee)
105
+
106
+ with trace_agent_run(
107
+ telemetry,
108
+ semconv.span_name(semconv.OP_INVOKE_AGENT, "Snowflake Cortex Agent"),
109
+ {
110
+ semconv.GEN_AI_OPERATION_NAME: semconv.OP_INVOKE_AGENT,
111
+ semconv.GEN_AI_AGENT_NAME: "Snowflake Cortex Agent",
112
+ semconv.GEN_AI_REQUEST_MODEL: details["model"],
113
+ semconv.GEN_AI_TOOL_DEFINITIONS: semconv.tool_definitions(
114
+ details["allowed_tools"]
115
+ ),
116
+ },
117
+ start_event="agent_start",
118
+ end_event="agent_end",
119
+ error_event="agent_error",
120
+ log_fields={
121
+ "agent_name": "Snowflake Cortex Agent",
122
+ "agent_role": "Snowflake Cortex Agent",
123
+ "model": details["model"],
124
+ },
125
+ start_details=details,
126
+ ) as run:
127
+ run.set_input(_content.prompt_messages(prompt))
128
+ # Mirrors the Claude SDK shape: the result message is expected
129
+ # to carry ``.usage`` and content blocks; degrades to no
130
+ # usage/content if the SDK differs.
131
+ acc = UsageAccumulator()
132
+ out = _content.OutputAccumulator()
133
+ try:
134
+ async for message in wrapped(*args, **kwargs):
135
+ acc.add(extract_usage(getattr(message, "usage", None)))
136
+ out.add(message)
137
+ yield message
138
+ finally:
139
+ if tee is not None:
140
+ run.set_input(tee.result())
141
+ run.set_usage(acc.result())
142
+ run.set_output(out.result(), finish_reasons=out.finish_reasons)
143
+
144
+ wrapped = query_wrapper(query)
145
+ setattr(wrapped, self._MARKER, True)
146
+ module.query = wrapped
147
+
148
+ def _wrap_client_query(self, client):
149
+ """Wrap ``CortexCodeSDKClient.query``: not a run, but where a run's prompt goes out.
150
+
151
+ The interactive client sends a prompt with ``query()`` and reads the
152
+ reply with ``receive_response()``. The prompt is queued on the client
153
+ here and taken, oldest first, as a response's input there; a streamed
154
+ prompt is teed the same way as on the one-shot path.
155
+ """
156
+ query = getattr(client, "query", None)
157
+ if query is None or getattr(query, self._MARKER, False):
158
+ return
159
+
160
+ @wrapt.decorator
161
+ async def query_wrapper(wrapped, instance, args, kwargs):
162
+ prompt = kwargs.get("prompt", args[0] if args else None)
163
+ tee = _content.PromptTee.wrap(prompt)
164
+ if tee is not None:
165
+ args, kwargs = _content.replace_prompt(args, kwargs, tee)
166
+ result = await wrapped(*args, **kwargs)
167
+ # Queued only once the SDK accepted it: a prompt that never went
168
+ # out is not part of any response's input.
169
+ _content.queue_prompt(
170
+ instance,
171
+ tee.result() if tee is not None else _content.prompt_messages(prompt),
172
+ )
173
+ return result
174
+
175
+ wrapped = query_wrapper(query)
176
+ setattr(wrapped, self._MARKER, True)
177
+ client.query = wrapped
178
+
179
+ def _wrap_client(self, module):
180
+ """Wrap ``CortexCodeSDKClient.receive_response`` (the interactive chokepoint)."""
181
+ client = getattr(module, "CortexCodeSDKClient", None)
182
+ if client is None:
183
+ return
184
+ self._wrap_client_query(client)
185
+ receive_response = getattr(client, "receive_response", None)
186
+ if receive_response is None or getattr(receive_response, self._MARKER, False):
187
+ return
188
+
189
+ telemetry = self.telemetry
190
+
191
+ @wrapt.decorator
192
+ async def receive_response_wrapper(wrapped, instance, args, kwargs):
193
+ # The client keeps its CortexCodeAgentOptions on the instance.
194
+ options = getattr(instance, "options", None)
195
+ details = _options_details(options)
196
+
197
+ with trace_agent_run(
198
+ telemetry,
199
+ semconv.span_name(semconv.OP_INVOKE_AGENT, "Snowflake Cortex Agent"),
200
+ {
201
+ semconv.GEN_AI_OPERATION_NAME: semconv.OP_INVOKE_AGENT,
202
+ semconv.GEN_AI_AGENT_NAME: "Snowflake Cortex Agent",
203
+ semconv.GEN_AI_REQUEST_MODEL: details["model"],
204
+ semconv.GEN_AI_TOOL_DEFINITIONS: semconv.tool_definitions(
205
+ details["allowed_tools"]
206
+ ),
207
+ },
208
+ start_event="agent_start",
209
+ end_event="agent_end",
210
+ error_event="agent_error",
211
+ log_fields={
212
+ "agent_name": "Snowflake Cortex Agent",
213
+ "agent_role": "Snowflake Cortex Agent",
214
+ "model": details["model"],
215
+ },
216
+ start_details=details,
217
+ ) as run:
218
+ # The prompt went out earlier through ``client.query()``, which
219
+ # queued it on the client; the oldest prompt still unanswered
220
+ # is this response's input (one turn per prompt, see
221
+ # ``_content.take_prompt``).
222
+ run.set_input(_content.take_prompt(instance))
223
+ acc = UsageAccumulator()
224
+ out = _content.OutputAccumulator()
225
+ try:
226
+ async for message in wrapped(*args, **kwargs):
227
+ acc.add(extract_usage(getattr(message, "usage", None)))
228
+ out.add(message)
229
+ yield message
230
+ finally:
231
+ run.set_usage(acc.result())
232
+ run.set_output(out.result(), finish_reasons=out.finish_reasons)
233
+
234
+ wrapped = receive_response_wrapper(receive_response)
235
+ setattr(wrapped, self._MARKER, True)
236
+ client.receive_response = wrapped
237
+
238
+
239
+ def install_snowflake_monitoring(
240
+ server_url: str = "http://localhost:8000",
241
+ user: Optional[str] = None,
242
+ api_key: Optional[str] = None,
243
+ session: Optional[str] = None,
244
+ name: Optional[str] = None,
245
+ ):
246
+ """
247
+ Install Snowflake Cortex Agent SDK monitoring instrumentation.
248
+
249
+ Instruments the Cortex Code Agent SDK's two async-generator entry points --
250
+ ``cortex_code_agent_sdk.query(...)`` (one-shot) and
251
+ ``CortexCodeSDKClient.receive_response()`` (interactive) -- so every agent run
252
+ streams start/end/error telemetry with zero changes to the agent code. Call
253
+ this *before* ``cortex_code_agent_sdk`` is imported.
254
+
255
+ Args:
256
+ server_url: URL of the monitoring server
257
+ user: Name of the executing user
258
+ api_key: Ingest key tying events to an owner (for the iOS app)
259
+ session: Per-run id used to group events in the app
260
+ name: Explicit session title (else falls back to a codename)
261
+ """
262
+ return install_hook(
263
+ SnowflakeCortexImportHook,
264
+ framework="Snowflake Cortex",
265
+ label="Snowflake Cortex Agent SDK",
266
+ server_url=server_url,
267
+ user=user,
268
+ api_key=api_key,
269
+ session=session,
270
+ name=name,
271
+ )