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.
- otelzero/__init__.py +62 -0
- otelzero/__main__.py +140 -0
- otelzero/context.py +86 -0
- otelzero/detection.py +58 -0
- otelzero/hooks/__init__.py +96 -0
- otelzero/hooks/_content.py +865 -0
- otelzero/hooks/_langsmith.py +504 -0
- otelzero/hooks/_native.py +517 -0
- otelzero/hooks/_usage.py +166 -0
- otelzero/hooks/adk.py +128 -0
- otelzero/hooks/base.py +546 -0
- otelzero/hooks/claude_sdk.py +267 -0
- otelzero/hooks/crewai.py +338 -0
- otelzero/hooks/databricks.py +260 -0
- otelzero/hooks/langchain.py +56 -0
- otelzero/hooks/langgraph.py +57 -0
- otelzero/hooks/llama_index.py +724 -0
- otelzero/hooks/microsoft.py +160 -0
- otelzero/hooks/openai_agents.py +313 -0
- otelzero/hooks/pydantic_ai.py +173 -0
- otelzero/hooks/smolagents.py +331 -0
- otelzero/hooks/snowflake.py +271 -0
- otelzero/hooks/strands.py +173 -0
- otelzero/otel.py +372 -0
- otelzero/semconv.py +327 -0
- otelzero/telemetry.py +238 -0
- otelzero/translate/__init__.py +214 -0
- otelzero/translate/langsmith.py +401 -0
- otelzero-0.2.0.dist-info/METADATA +1345 -0
- otelzero-0.2.0.dist-info/RECORD +33 -0
- otelzero-0.2.0.dist-info/WHEEL +5 -0
- otelzero-0.2.0.dist-info/licenses/LICENSE +202 -0
- otelzero-0.2.0.dist-info/top_level.txt +1 -0
|
@@ -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
|
+
)
|