Same agent Smaller bill. The tools and infrastructure to get more work from your AI. Fewer tokens. Less compute. Lower cost.
TypeScript agent-harnessagent-harness-engineeringai-engineeringai-observabilityamd-gpuclaude-codeclickhousecodexcoding-agentcoding-agentscursorgenaigpu-monitoringllm-observabilityllmopsnvidia-smiobservabilityopen-sourceopenaiopentelemetry
fix: agents spans in Microsoft Agent framework (#1085)
Ishan Jain7d0cb9424124
diff --git a/contributors/STREAMING_SPAN_FIX.md b/contributors/STREAMING_SPAN_FIX.mdnew file mode 100644index 00000000..3feecd26--- /dev/null+++ b/contributors/STREAMING_SPAN_FIX.md@@ -0,0 +1,388 @@+# Fix: Streaming Span Ordering Across All LLM Providers++## Problem++When OpenLIT instruments streaming LLM calls, the HTTP `POST` span (created by `opentelemetry-instrumentation-httpx` / `opentelemetry-instrumentation-requests` / etc.) should be a **child** of the OpenLIT `chat` span. This works correctly for **non-streaming** calls because the `chat` span is created via `tracer.start_as_current_span(...)` inside a `with` block — meaning it's the active span when `wrapped()` fires the HTTP request.++However, for **streaming** calls, the current code does:++```python+# BUG: wrapped() fires the HTTP POST *before* the span exists+awaited_wrapped = wrapped(*args, **kwargs) # <-- HTTP POST happens here+span = tracer.start_span(span_name, kind=SpanKind.CLIENT) # <-- span created after++return TracedSyncStream(awaited_wrapped, span, ...)+```++Because the `chat` span doesn't exist yet when `wrapped()` executes, the HTTP `POST` span has **no parent** and appears as a root span in a separate trace — breaking the span hierarchy.++### Non-streaming (correct)++```+invoke_agent+ └── chat gpt-4o-mini ← start_as_current_span, then wrapped()+ └── POST https://... ← correctly parented+```++### Streaming (buggy)++```+invoke_agent+ └── chat gpt-4o-mini ← span created AFTER wrapped()++POST https://... ← orphaned root span, different trace+```++## Solution++Create the `chat` span **first**, attach it to the OTel context, **then** call `wrapped()`. Detach the context token immediately after `wrapped()` returns (the stream object is just initialized, the actual iteration happens later).++### Fixed pattern++```python+from opentelemetry import trace as trace_api, context as context_api++# ...++if streaming:+ # 1. Create span FIRST+ span = tracer.start_span(span_name, kind=SpanKind.CLIENT)+ # 2. Make it the active span so HTTP instrumentation picks it up+ ctx = trace_api.set_span_in_context(span)+ token = context_api.attach(ctx)+ try:+ # 3. NOW call wrapped — HTTP POST will be a child of our span+ awaited_wrapped = wrapped(*args, **kwargs)+ except Exception as e:+ handle_exception(span, e)+ context_api.detach(token)+ span.end()+ raise+ # 4. Detach — the span stays open, TracedStream will end it later+ context_api.detach(token)++ return TracedSyncStream(awaited_wrapped, span, ...)+```++### Streaming (fixed)++```+invoke_agent+ └── chat gpt-4o-mini ← span created BEFORE wrapped()+ └── POST https://... ← correctly parented+```++## Reference Implementation++The fix has already been applied to **OpenAI** (both sync and async). Use these as the canonical reference:++- `sdk/python/src/openlit/instrumentation/openai/openai.py` — sync: `chat_completions` and `responses` wrappers+- `sdk/python/src/openlit/instrumentation/openai/async_openai.py` — async: same two wrappers++---++## Files That Need the Fix++All files below follow the same buggy pattern: `wrapped()` is called before `tracer.start_span()`. Each entry documents the exact location and any provider-specific nuances.++### Batch 1: Anthropic & VertexAI++| File | Function | Notes |+|------|----------|-------|+| `instrumentation/anthropic/anthropic.py` | `messages()` → `wrapper()` | Standard pattern. Add `trace_api`, `context_api` imports. |+| `instrumentation/anthropic/async_anthropic.py` | `messages()` → `async_wrapper()` | Same, but `await wrapped(...)`. |+| `instrumentation/vertexai/vertexai.py` | `generate_content()` → `wrapper()` | Standard pattern. |+| `instrumentation/vertexai/async_vertexai.py` | `generate_content()` → `async_wrapper()` | Async variant. |++**Current buggy code** (Anthropic sync example):++```python+if streaming:+ awaited_wrapped = wrapped(*args, **kwargs)+ span = tracer.start_span(span_name, kind=SpanKind.CLIENT)++ return TracedSyncStream(awaited_wrapped, span, ...)+```++**Fixed code**:++```python+if streaming:+ span = tracer.start_span(span_name, kind=SpanKind.CLIENT)+ ctx = trace_api.set_span_in_context(span)+ token = context_api.attach(ctx)+ try:+ awaited_wrapped = wrapped(*args, **kwargs)+ except Exception as e:+ handle_exception(span, e)+ context_api.detach(token)+ span.end()+ raise+ context_api.detach(token)++ return TracedSyncStream(awaited_wrapped, span, ...)+```++### Batch 2: Together & Groq++| File | Function | Notes |+|------|----------|-------|+| `instrumentation/together/together.py` | `chat_completions()` → `wrapper()` | Standard pattern. |+| `instrumentation/together/async_together.py` | `chat_completions()` → `async_wrapper()` | Async variant. |+| `instrumentation/groq/groq.py` | `chat_completions()` → `wrapper()` | Standard pattern. |+| `instrumentation/groq/async_groq.py` | `chat_completions()` → `async_wrapper()` | Async variant. |++Same fix pattern as Batch 1.++### Batch 3: AI21, Azure AI Inference & PremAI++| File | Function | Notes |+|------|----------|-------|+| `instrumentation/ai21/ai21.py` | `chat()` → `wrapper()` | Standard pattern. |+| `instrumentation/ai21/async_ai21.py` | `chat()` → `async_wrapper()` | Async variant. |+| `instrumentation/azure_ai_inference/azure_ai_inference.py` | `complete()` → `wrapper()` | Standard pattern. |+| `instrumentation/azure_ai_inference/async_azure_ai_inference.py` | `complete()` → `async_wrapper()` | Async variant. |+| `instrumentation/premai/premai.py` | `chat_completions()` → `wrapper()` | Standard pattern (sync only, no async file). |++Same fix pattern as Batch 1.++### Batch 4: Sarvam & GPT4All++| File | Function | Notes |+|------|----------|-------|+| `instrumentation/sarvam/sarvam.py` | `translate()` → `wrapper()` | **Already imports `context_api`** — only add `trace_api` import. |+| `instrumentation/sarvam/async_sarvam.py` | `translate()` → `async_wrapper()` | Same — `context_api` already present. |+| `instrumentation/gpt4all/gpt4all.py` | `chat_completions()` → `wrapper()` | Standard pattern. |++### Batch 5: Ollama (2 streaming paths per file)++| File | Functions | Notes |+|------|-----------|-------|+| `instrumentation/ollama/ollama.py` | `chat()` → `wrapper()` AND `generate()` → `wrapper()` | **Two** streaming blocks to fix per file. |+| `instrumentation/ollama/async_ollama.py` | `chat()` → `async_wrapper()` AND `generate()` → `async_wrapper()` | Same — two async streaming blocks. |++Each of the two wrapper functions (`chat` and `generate`) has its own `if streaming:` block that needs the fix.++### Batch 6: Mistral & Cohere (dedicated stream functions)++| File | Function | Notes |+|------|----------|-------|+| `instrumentation/mistral/mistral.py` | `stream()` → `wrapper()` | This is a **dedicated streaming function** — no `if streaming:` check, the entire wrapper always streams. Apply the same span-first pattern. |+| `instrumentation/mistral/async_mistral.py` | `stream()` → `async_wrapper()` | Async variant of above. |+| `instrumentation/cohere/cohere.py` | `chat_stream()` → `wrapper()` | Dedicated streaming function, same approach. |+| `instrumentation/cohere/async_cohere.py` | `chat_stream()` → `async_wrapper()` | Async variant. |++**Current buggy code** (Mistral sync example):++```python+def wrapper(wrapped, instance, args, kwargs):+ # ...+ awaited_wrapped = wrapped(*args, **kwargs)+ span = tracer.start_span(span_name, kind=SpanKind.CLIENT)++ return TracedSyncStream(awaited_wrapped, span, ...)+```++**Fixed code**:++```python+def wrapper(wrapped, instance, args, kwargs):+ # ...+ span = tracer.start_span(span_name, kind=SpanKind.CLIENT)+ ctx = trace_api.set_span_in_context(span)+ token = context_api.attach(ctx)+ try:+ awaited_wrapped = wrapped(*args, **kwargs)+ except Exception as e:+ handle_exception(span, e)+ context_api.detach(token)+ span.end()+ raise+ context_api.detach(token)++ return TracedSyncStream(awaited_wrapped, span, ...)+```++### Batch 7: LiteLLM, Bedrock & Google AI Studio (special patterns)++These providers have unique code structures requiring slightly different application of the fix.++#### LiteLLM++| File | Function | Notes |+|------|----------|-------|+| `instrumentation/litellm/litellm.py` | `completion()` → `wrapper()` | Has `set_framework_llm_active()` / `reset_framework_llm_active()` calls around `wrapped()`. |+| `instrumentation/litellm/async_litellm.py` | `completion()` → `async_wrapper()` | Async variant with same pattern. |++**Current buggy code**:++```python+if streaming:+ fw_token = set_framework_llm_active()+ try:+ awaited_wrapped = wrapped(*args, **kwargs)+ finally:+ reset_framework_llm_active(fw_token)+ span = tracer.start_span(span_name, kind=SpanKind.CLIENT)+ return TracedSyncStream(awaited_wrapped, span, ...)+```++**Fixed code** — create span first, keep the `fw_token` logic intact:++```python+if streaming:+ span = tracer.start_span(span_name, kind=SpanKind.CLIENT)+ ctx = trace_api.set_span_in_context(span)+ otel_token = context_api.attach(ctx)+ fw_token = set_framework_llm_active()+ try:+ awaited_wrapped = wrapped(*args, **kwargs)+ except Exception as e:+ handle_exception(span, e)+ context_api.detach(otel_token)+ span.end()+ raise+ finally:+ reset_framework_llm_active(fw_token)+ context_api.detach(otel_token)+ return TracedSyncStream(awaited_wrapped, span, ...)+```++**Important**: The original code also has `reset_framework_llm_active(fw_token)` in both `except` and `finally` blocks elsewhere, causing a double-call on errors. When applying this fix, ensure `reset_framework_llm_active` is only in `finally` — never duplicated in `except`.++#### Bedrock++| File | Function | Notes |+|------|----------|-------|+| `instrumentation/bedrock/bedrock.py` | `converse_stream()` → `converse_stream_wrapper()` | Uses `original_method(...)` instead of `wrapped(...)`. The wrapper is nested inside the main `wrapper()` function. |++**Current buggy code**:++```python+def converse_stream_wrapper(original_method, *method_args, **method_kwargs):+ # ...+ stream_response = original_method(*method_args, **method_kwargs)+ span = tracer.start_span(span_name, kind=SpanKind.CLIENT)++ return TracedSyncStream(stream_response, span, ...)+```++**Fixed code**:++```python+def converse_stream_wrapper(original_method, *method_args, **method_kwargs):+ # ...+ span = tracer.start_span(span_name, kind=SpanKind.CLIENT)+ ctx = trace_api.set_span_in_context(span)+ token = context_api.attach(ctx)+ try:+ stream_response = original_method(*method_args, **method_kwargs)+ except Exception as e:+ handle_exception(span, e)+ context_api.detach(token)+ span.end()+ raise+ context_api.detach(token)++ return TracedSyncStream(stream_response, span, ...)+```++#### Google AI Studio++| File | Function | Notes |+|------|----------|-------|+| `instrumentation/google_ai_studio/google_ai_studio.py` | `generate_stream()` → `wrapper()` | Uses `tracer.start_as_current_span(...)` without a `with` block — needs to be changed to `tracer.start_span(...)` + explicit `attach/detach`. |+| `instrumentation/google_ai_studio/async_google_ai_studio.py` | `generate_stream()` → `async_wrapper()` | Async variant with same issue. |++**Current buggy code**:++```python+awaited_wrapped = wrapped(*args, **kwargs)+span = tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT)++return TracedSyncStream(awaited_wrapped, span, ...)+```++**Fixed code**:++```python+span = tracer.start_span(span_name, kind=SpanKind.CLIENT)+ctx = trace_api.set_span_in_context(span)+token = context_api.attach(ctx)+try:+ awaited_wrapped = wrapped(*args, **kwargs)+except Exception as e:+ handle_exception(span, e)+ context_api.detach(token)+ span.end()+ raise+context_api.detach(token)++return TracedSyncStream(awaited_wrapped, span, ...)+```++**Note**: `start_as_current_span` without `with` returns a context manager, not a span — so `TracedSyncStream` would receive the wrong type. The fix switches to `start_span` which correctly returns a `Span` object.++---++## Import Changes Required++For every file that gets this fix, ensure these imports are present at the top:++```python+from opentelemetry import trace as trace_api, context as context_api+```++**Exceptions**:+- `sarvam/sarvam.py` and `sarvam/async_sarvam.py` already import `context as context_api` — only add `trace as trace_api`+- `openai/openai.py` and `openai/async_openai.py` already have both imports (fix is already applied)++---++## Complete File List (27 call sites across 25 files)++All paths are relative to `sdk/python/src/openlit/`:++| # | File | Streaming call sites |+|---|------|---------------------|+| 1 | `instrumentation/anthropic/anthropic.py` | 1 |+| 2 | `instrumentation/anthropic/async_anthropic.py` | 1 |+| 3 | `instrumentation/vertexai/vertexai.py` | 1 |+| 4 | `instrumentation/vertexai/async_vertexai.py` | 1 |+| 5 | `instrumentation/together/together.py` | 1 |+| 6 | `instrumentation/together/async_together.py` | 1 |+| 7 | `instrumentation/groq/groq.py` | 1 |+| 8 | `instrumentation/groq/async_groq.py` | 1 |+| 9 | `instrumentation/ai21/ai21.py` | 1 |+| 10 | `instrumentation/ai21/async_ai21.py` | 1 |+| 11 | `instrumentation/azure_ai_inference/azure_ai_inference.py` | 1 |+| 12 | `instrumentation/azure_ai_inference/async_azure_ai_inference.py` | 1 |+| 13 | `instrumentation/premai/premai.py` | 1 |+| 14 | `instrumentation/sarvam/sarvam.py` | 1 |+| 15 | `instrumentation/sarvam/async_sarvam.py` | 1 |+| 16 | `instrumentation/gpt4all/gpt4all.py` | 1 |+| 17 | `instrumentation/ollama/ollama.py` | 2 (chat + generate) |+| 18 | `instrumentation/ollama/async_ollama.py` | 2 (chat + generate) |+| 19 | `instrumentation/mistral/mistral.py` | 1 (dedicated `stream()`) |+| 20 | `instrumentation/mistral/async_mistral.py` | 1 (dedicated `stream()`) |+| 21 | `instrumentation/cohere/cohere.py` | 1 (dedicated `chat_stream()`) |+| 22 | `instrumentation/cohere/async_cohere.py` | 1 (dedicated `chat_stream()`) |+| 23 | `instrumentation/litellm/litellm.py` | 1 (has `fw_token` logic) |+| 24 | `instrumentation/litellm/async_litellm.py` | 1 (has `fw_token` logic) |+| 25 | `instrumentation/bedrock/bedrock.py` | 1 (`converse_stream_wrapper`) |+| 26 | `instrumentation/google_ai_studio/google_ai_studio.py` | 1 (`start_as_current_span` → `start_span`) |+| 27 | `instrumentation/google_ai_studio/async_google_ai_studio.py` | 1 (`start_as_current_span` → `start_span`) |++**Total: 27 call sites across 25 files** (Ollama has 2 per file).++---++## Verification++After applying the fix to each provider, verify with a streaming call:++1. Enable HTTP instrumentation (e.g., `opentelemetry-instrumentation-httpx` for httpx-based SDKs, or `opentelemetry-instrumentation-requests` for requests-based SDKs)+2. Make a streaming API call through the provider+3. Check that the `POST` span is a **child** of the `chat` span, not a root span+4. Confirm the `chat` span has correct attributes (model, tokens, finish_reason, etc.)+5. Confirm non-streaming calls still work correctly (they should be unaffected)diff --git a/contributors/otel-span-events-and-attributes.md b/contributors/otel-span-events-and-attributes.mddeleted file mode 100644index faacaead..00000000--- a/contributors/otel-span-events-and-attributes.md+++ /dev/null@@ -1,292 +0,0 @@-# OTel Span Events and Attributes: Implementation Guide--This document describes how OpenLIT implements OpenTelemetry (OTel) semantic conventions for GenAI spans and events, and how to adopt the same structure and style when adding or updating instrumentations (e.g., OpenAI → Anthropic, LiteLLM, etc.).--**Official OTel GenAI spec references:**--- [Semantic conventions for Generative AI events](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-events.md) — event `gen_ai.client.inference.operation.details`, attribute requirement levels, well-known values.-- [Semantic conventions for generative client AI spans](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-spans.md) — inference/embeddings/retrieval spans, span name/kind, attributes, content recording.-- [GenAI docs (overview)](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/gen-ai) — input/output message schemas, system instructions, tool definitions.-------## 1. How Span Attributes Look--Spans carry OTel-aligned attributes in a consistent order. Use **constants from `openlit.semcov.SemanticConvention`** so attribute names stay in sync with the official semconv and fallbacks.--### 1.1 Common attributes (set once per span)--Set these via **`common_span_attributes()`** from `openlit.__helpers` so all instrumentations behave the same:--| Attribute (constant) | Meaning |-|-----------------------|---------|-| `GEN_AI_OPERATION` | Operation type (e.g. `chat`, `embeddings`) |-| `GEN_AI_PROVIDER_NAME` | Provider name (e.g. `openai`, `anthropic`) |-| `SERVER_ADDRESS` / `SERVER_PORT` | Server connection |-| `GEN_AI_REQUEST_MODEL` / `GEN_AI_RESPONSE_MODEL` | Request and response model |-| `GEN_AI_REQUEST_IS_STREAM` | Whether the call was streaming |-| `GEN_AI_SERVER_TBT` / `GEN_AI_SERVER_TTFT` | Time-between-token / time-to-first-token |-| `GEN_AI_SDK_VERSION` | OpenLIT/instrumentation version |-| Plus: `DEPLOYMENT_ENVIRONMENT`, `SERVICE_NAME` (from helpers) |--**Usage:** Call `common_span_attributes(scope, gen_ai_operation, GEN_AI_SYSTEM_*, server_address, server_port, request_model, response_model, environment, application_name, is_stream, tbt, ttft, version)` at the start of your common logic.--### 1.2 Request and response attributes (on span)--Set these on `scope._span` after the common attributes:--- **Request:** `GEN_AI_REQUEST_TEMPERATURE`, `GEN_AI_REQUEST_TOP_P`, `GEN_AI_REQUEST_MAX_TOKENS`, `GEN_AI_REQUEST_FREQUENCY_PENALTY`, `GEN_AI_REQUEST_PRESENCE_PENALTY`, `GEN_AI_REQUEST_STOP_SEQUENCES`, `GEN_AI_REQUEST_SEED`, `GEN_AI_REQUEST_CHOICE_COUNT` (only when ≠ 1), `GEN_AI_REQUEST_USER`, etc.-- **Response:** `GEN_AI_RESPONSE_ID`, `GEN_AI_RESPONSE_FINISH_REASON` (array), `GEN_AI_OUTPUT_TYPE` (`text` or `json`).-- **Provider-specific (TIER 2):** e.g. OpenAI: `OPENAI_REQUEST_SERVICE_TIER`, `OPENAI_RESPONSE_SERVICE_TIER`, `GEN_AI_RESPONSE_SYSTEM_FINGERPRINT`.--Use helpers (e.g. `handle_not_given()` for OpenAI) so unset request fields get consistent defaults.--### 1.3 Usage and cost attributes (on span)--Always set these when you have the data (including when 0):--- `GEN_AI_USAGE_INPUT_TOKENS`-- `GEN_AI_USAGE_OUTPUT_TOKENS`-- `GEN_AI_CLIENT_TOKEN_USAGE` (input + output)-- `GEN_AI_USAGE_COST`-- **Cached tokens (set even when 0):**- - `GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS`- - `GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS`--Optional extensions (e.g. reasoning) can use spec-aligned or documented custom keys (e.g. `gen_ai.usage.reasoning_tokens`).--### 1.4 Message attributes (on span)--Per OTel, input/output messages on the **span** use the same **array structure** as on events:--- **`GEN_AI_INPUT_MESSAGES`** – JSON string of an array of input messages (role + parts).-- **`GEN_AI_OUTPUT_MESSAGES`** – JSON string of an array of output messages (role + parts + finish_reason).--Do **not** set these as ad-hoc strings. Use a single helper that takes structured message lists and sets both attributes so span and event stay consistent.--**Helper (per instrumentation):**--```python-def _set_span_messages_as_array(span, input_messages, output_messages):- """Set gen_ai.input.messages and gen_ai.output.messages on span as JSON array strings (OTel)."""- if input_messages is not None:- span.set_attribute(- SemanticConvention.GEN_AI_INPUT_MESSAGES,- json.dumps(input_messages) if isinstance(input_messages, list) else input_messages,- )- if output_messages is not None:- span.set_attribute(- SemanticConvention.GEN_AI_OUTPUT_MESSAGES,- json.dumps(output_messages) if isinstance(output_messages, list) else output_messages,- )-```--Input/output message structures must follow the OTel gen-ai message schemas (e.g. `gen-ai-input-messages.json` / `gen-ai-output-messages.json`). Each provider implements **`build_input_messages(...)`** and **`build_output_messages(...)`** that return these structures; the same lists are then used for both span attributes and the inference event.--### 1.5 System instructions (on span)--When present, set **`GEN_AI_SYSTEM_INSTRUCTIONS`** (e.g. JSON string of instruction content). Source can be request system messages or a response field (e.g. Responses API `instructions`).--### 1.6 Tools (on span)--When the call involves tools, set:--- `GEN_AI_TOOL_NAME` (e.g. comma-separated names)-- `GEN_AI_TOOL_CALL_ID`-- `GEN_AI_TOOL_ARGS` (e.g. comma-separated string representation)-------## 2. How Span Events Look--We emit a **single OTel GenAI inference-details event** per successful (or handled) invocation:--- **Event name:** `gen_ai.client.inference.operation.details`- Constant: **`SemanticConvention.GEN_AI_CLIENT_INFERENCE_OPERATION_DETAILS`**--- **Event attributes:** All inference details go in **attributes**; keep **body** empty (`""`) per spec.--### 2.1 Event attribute set--The event should carry the same semantic information as the span where applicable:--- **Operation / models:** `GEN_AI_OPERATION`, `GEN_AI_REQUEST_MODEL`, `GEN_AI_RESPONSE_MODEL`-- **Server:** `SERVER_ADDRESS`, `SERVER_PORT`-- **Messages:** `GEN_AI_INPUT_MESSAGES`, `GEN_AI_OUTPUT_MESSAGES` (same array structure as on span)-- **Tools:** `GEN_AI_TOOL_DEFINITIONS` when applicable-- **Request:** temperature, max_tokens, top_p, frequency_penalty, presence_penalty, stop_sequences, seed, choice_count-- **Response:** `GEN_AI_RESPONSE_ID`, `GEN_AI_RESPONSE_FINISH_REASON`, `GEN_AI_OUTPUT_TYPE`-- **Usage:** `GEN_AI_USAGE_INPUT_TOKENS`, `GEN_AI_USAGE_OUTPUT_TOKENS`, **`GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS`**, **`GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS`** (set even when 0)-- **Other:** `GEN_AI_SYSTEM_INSTRUCTIONS`, `ERROR_TYPE` (on error)--Use the **same attribute constants** as on the span so naming stays aligned with OTel.--### 2.2 Emitting the event--- Use a **single** helper (e.g. **`emit_inference_event()`**) that:- - Takes `event_provider`, operation name, request/response model, input/output messages, tool definitions, server address/port, and **`**extra_attrs`** for the rest.- - Maps **extra_attrs** keys to semantic convention attribute names (e.g. `cache_read_input_tokens` → `GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS`, `system_instructions` → `GEN_AI_SYSTEM_INSTRUCTIONS`, `error_type` → `ERROR_TYPE`).- - Builds an OTel Event via **`otel_event(name, attributes, body="")`** from `openlit.__helpers` and calls **`event_provider.emit(event)`**.--- **Extra dict keys** (so call sites stay consistent across instrumentations):- - `response_id`, `finish_reasons`, `output_type`, `temperature`, `max_tokens`, `top_p`, `frequency_penalty`, `presence_penalty`, `stop_sequences`, `seed`, `choice_count` / `n`- - `input_tokens`, `output_tokens`, **`cache_read_input_tokens`**, **`cache_creation_input_tokens`** (pass even when 0)- - `system_instructions`, `error_type`--This keeps event payloads aligned with the span and makes it easy to add new instrumentations by filling the same `extra` shape and reusing the same emitter.-------## 3. Official Spec Attribute Reference--The following tables align with the [GenAI events](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-events.md) and [GenAI spans](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-spans.md) docs. Use these requirement levels and value types when implementing.--### 3.1 Event: `gen_ai.client.inference.operation.details`--| OTel attribute (key) | Requirement | Value type | Notes |-|----------------------|-------------|------------|--------|-| `gen_ai.operation.name` | **Required** | string | Well-known: `chat`, `embeddings`, `text_completion`, `generate_content`, etc. |-| `gen_ai.request.model` | Conditionally required if available | string | |-| `gen_ai.response.model` | Recommended | string | |-| `server.address` | Recommended | string | |-| `server.port` | Conditionally required if `server.address` set | int | |-| `gen_ai.request.temperature` | Recommended | double | |-| `gen_ai.request.top_p` | Recommended | double | |-| `gen_ai.request.max_tokens` | Recommended | int | |-| `gen_ai.request.frequency_penalty` | Recommended | double | |-| `gen_ai.request.presence_penalty` | Recommended | double | |-| `gen_ai.request.stop_sequences` | Recommended | string[] | |-| `gen_ai.request.seed` | Conditionally required if in request | int | |-| `gen_ai.request.choice.count` | Conditionally required if in request and ≠1 | int | |-| `gen_ai.response.id` | Recommended | string | |-| `gen_ai.response.finish_reasons` | Recommended | string[] | |-| `gen_ai.output.type` | Conditionally required when applicable | string | Well-known: `text`, `json`, `image`, `speech` |-| `gen_ai.usage.input_tokens` | Recommended | int | Should include cached tokens |-| `gen_ai.usage.output_tokens` | Recommended | int | |-| `gen_ai.usage.cache_creation.input_tokens` | Recommended | int | Set even when 0 |-| `gen_ai.usage.cache_read.input_tokens` | Recommended | int | Set even when 0 |-| `gen_ai.input.messages` | Opt-in | any | Structured on events; follow input-messages schema |-| `gen_ai.output.messages` | Opt-in | any | Structured on events; follow output-messages schema |-| `gen_ai.system_instructions` | Opt-in | any | Follow system-instructions schema |-| `gen_ai.tool.definitions` | Opt-in | any | Array of tool definitions |-| `gen_ai.conversation.id` | Conditionally required when available | string | |-| `error.type` | Conditionally required on error | string | Well-known: `_OTHER`; use exception type or provider error code |--### 3.2 Inference span (same attributes as above)--- **Span name:** `{gen_ai.operation.name} {gen_ai.request.model}` (e.g. `chat gpt-4o`).-- **Span kind:** `CLIENT` (or `INTERNAL` for in-process).-- **Span status:** Follow [Recording errors](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-spans.md).-- **Messages on span:** Per spec, `gen_ai.input.messages` / `gen_ai.output.messages` on spans MAY be a JSON string if structured format is not supported; on events they MUST be structured. OpenLIT uses JSON string on spans for compatibility.-- **Sampling:** Provide `gen_ai.operation.name`, `gen_ai.provider.name`, `gen_ai.request.model`, `server.address`, `server.port` at span creation time when possible.--### 3.3 Embeddings span--- `gen_ai.operation.name` = `embeddings`; span name = `embeddings {gen_ai.request.model}`.-- Attributes: `gen_ai.embeddings.dimension.count` (Recommended), `gen_ai.request.encoding_formats`, `gen_ai.usage.input_tokens`, plus common server/model/error attributes.--### 3.4 Well-known values (use these when applicable)--- **`error.type`:** `_OTHER` as fallback when no custom value.-- **`gen_ai.operation.name`:** `chat`, `embeddings`, `text_completion`, `generate_content`, `execute_tool`, `invoke_agent`, `create_agent`, `retrieval`.-- **`gen_ai.output.type`:** `text`, `json`, `image`, `speech`.-- **`gen_ai.provider.name`:** `openai`, `anthropic`, `aws.bedrock`, `gcp.gemini`, `azure.ai.openai`, etc. (see spans doc for full list).-------## 4. Code and File Structure Reference--Keep **function names**, **argument order**, **comment headings**, and **sequence of operations** consistent across instrumentations so one pattern can be copied and maintained. The **reference implementation** is the OpenAI instrumentation: `sdk/python/src/openlit/instrumentation/openai/` (`utils.py`, `openai.py`, `async_openai.py`). New or updated instrumentations should mirror its structure, signatures, and comment style.--### 4.1 File layout (per provider)--- **`instrumentation/<provider>/`**- - **`__init__.py`** – Instrumentor; wraps SDK entrypoints and passes `event_provider`, `capture_message_content`, etc., into the handler factory.- - **`<provider>.py`** (e.g. `openai.py`) – Sync entrypoints that create span, extract request context, call into utils, and invoke **common_*_logic** with a **scope** object.- - **`async_<provider>.py`** – Async counterparts.- - **`utils.py`** – Shared helpers:- - Provider-specific: `format_content`, `build_input_messages`, `build_output_messages`, `handle_not_given` (or equivalent), and any response/usage parsers.- - Shared pattern: **`_set_span_messages_as_array(span, input_messages, output_messages)`**.- - **`emit_inference_event(event_provider, operation_name, request_model, response_model, input_messages, output_messages, tool_definitions, server_address, server_port, **extra_attrs)`** – builds and emits the inference event with the key→OTel mapping above.--### 4.2 Function names and signatures (use exactly these names and argument order)--**In `openlit.__helpers` (reuse, do not redefine):** `common_span_attributes(scope, gen_ai_operation, GEN_AI_PROVIDER_NAME, server_address, server_port, request_model, response_model, environment, application_name, is_stream, tbt, ttft, version)` — docstring: "Set common span attributes for both chat and RAG operations."--**In each provider's `utils.py`:** `format_content(messages)`; `build_input_messages(messages)` (docstring: "Convert <Provider> request messages to OTel input message structure. Follows gen-ai-input-messages schema."); `build_output_messages(response_text, finish_reason, tool_calls=None)` (docstring: "Convert <Provider> response to OTel output message structure. Follows gen-ai-output-messages schema."); `_set_span_messages_as_array(span, input_messages, output_messages)` (docstring: "Set gen_ai.input.messages and gen_ai.output.messages on span as JSON array strings (OTel)."); `emit_inference_event(event_provider, operation_name, request_model, response_model, input_messages=None, output_messages=None, tool_definitions=None, server_address=None, server_port=None, **extra_attrs)` (docstring: "Emit gen_ai.client.inference.operation.details event.").--**Common logic names:** `common_chat_logic`, `common_response_logic`, `common_embedding_logic`. Signature: `(scope, pricing_info, environment, application_name, metrics, capture_message_content, disable_metrics, version, is_stream, event_provider=None)`. Docstring: "Process <op> request and generate Telemetry."--### 4.3 Scope attributes (naming: leading underscore)--Use a **scope** object (e.g. a simple type or namespace) to carry everything from “raw response + request” to “span + event”:--- **Request/context:** `_kwargs`, `_start_time`, `_end_time`, `_server_address`, `_server_port`, etc.-- **Parsed response:** `_response_id`, `_response_model`, `_llmresponse`, `_finish_reason`, `_tools` / `_response_tools`, `_operation_type` (if you have multiple APIs).-- **Usage:** `_input_tokens`, `_output_tokens`, **`_cache_read_input_tokens`**, **`_cache_creation_input_tokens`** (set in response parser even when 0).-- **Optional:** `_reasoning_tokens`, `_instructions`, `_system_fingerprint`, `_service_tier`, etc.-- **Span:** `_span` (set by the entrypoint).--Naming: **leading underscore** for scope attributes so it’s clear they are internal to the instrumentation flow.--### 4.4 Sequence of operations inside common_*_logic (exact order and comment style)--1. **Compute cost** — `cost = get_chat_model_cost(...)`.-2. **Common Span Attributes** — `common_span_attributes(scope, ...)`.-3. **Provider-specific API type** (if any) — e.g. comment: `# OpenAI-specific API type attribute`.-4. **Span Attributes for Request parameters** — temperature, top_p, max_tokens, frequency_penalty, presence_penalty, stop_sequences, seed, user, choice_count (only when ≠1).-5. **Span Attributes for Response parameters** — response_id, finish_reason (as array), output_type.-6. **Span Attributes for Tools** (if tools) — GEN_AI_TOOL_NAME, GEN_AI_TOOL_CALL_ID, GEN_AI_TOOL_ARGS.-7. **Span Attributes for Cost and Tokens** — GEN_AI_USAGE_INPUT_TOKENS, GEN_AI_USAGE_OUTPUT_TOKENS, GEN_AI_CLIENT_TOKEN_USAGE, GEN_AI_USAGE_COST.-8. **Reasoning tokens** (optional).-9. **OTel cached token attributes (set even when 0)** — GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS, GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS when scope has them.-10. **Span Attributes for Content** (only if `capture_message_content`) — build_input_messages, build_output_messages, _set_span_messages_as_array, GEN_AI_SYSTEM_INSTRUCTIONS; then **Emit inference event** with extra containing cache_read_input_tokens, cache_creation_input_tokens (even when 0), plus response_id, finish_reasons, output_type, temperature, max_tokens, top_p, input_tokens, output_tokens, system_instructions.-11. **Span status and metrics** — `scope._span.set_status(Status(StatusCode.OK))`, then `record_completion_metrics(...)` if not disable_metrics.--### 4.5 Response parsing (before calling common_*_logic)--Use comment: `# Handle token usage including reasoning tokens and cached tokens`. Parse usage dict; set `scope._input_tokens`, `scope._output_tokens`; from `output_tokens_details` set `scope._reasoning_tokens`; from `input_tokens_details` or `prompt_tokens_details` set `scope._cache_read_input_tokens = ... .get("cached_tokens", 0)`. Set `scope._cache_creation_input_tokens` if the API exposes it.--### 4.6 extra_attrs keys for emit_inference_event--Same keys across instrumentations: `response_id`, `finish_reasons`, `output_type`; `temperature`, `max_tokens`, `top_p`, `frequency_penalty`, `presence_penalty`, `stop_sequences`, `seed`, `choice_count` or `n`; `input_tokens`, `output_tokens`, `cache_read_input_tokens`, `cache_creation_input_tokens` (always pass, even when 0); `system_instructions`, `error_type`, `conversation_id` (when available).--**Flow summary:** Entrypoint → create span, call SDK → normalize response to dict → build scope, parse usage/cache/messages → call common_*_logic → (cost → common_span_attributes → request/response/tools/usage/cache → content + emit_inference_event if capture_message_content → status + metrics). Streaming: accumulate then call common_*_logic once at the end.-------## 5. Reusing and Sharing Code--### 5.1 From `openlit.__helpers`--- **`common_span_attributes(...)`** – Use for all instrumentations so common span attributes are identical.-- **`response_as_dict(response)`** – Use when the SDK returns an object; keeps parsing in utils dict-based.-- **`otel_event(name, attributes, body)`** – Use inside your `emit_inference_event`-style helper.-- **`calculate_ttft` / `calculate_tbt`** – For streaming metrics.-- **`get_chat_model_cost` / `get_embed_model_cost`** – For cost; provider-specific pricing can live in helpers or in the provider’s utils.-- **`record_completion_metrics`** – For metrics.-- **`handle_exception(span, e)`** – Set `error.type` and span status; use when you catch exceptions in the instrumentation.--### 5.2 From `openlit.semcov`--- **`SemanticConvention`** – Use for every attribute and event name (e.g. `GEN_AI_OPERATION`, `GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS`, `GEN_AI_CLIENT_INFERENCE_OPERATION_DETAILS`). Do not hardcode OTel strings in instrumentation code.--### 5.3 Provider-specific utils--- **`build_input_messages`** / **`build_output_messages`** – Provider-specific request/response shape → OTel message array. Same return shape across providers so **`_set_span_messages_as_array`** and **`emit_inference_event`** can stay shared or easily copied.-- **`emit_inference_event`** – Can live in the provider’s `utils.py` (as in OpenAI) with the **extra_attrs** key→OTel mapping documented above. New instrumentations should reuse the same **extra** keys and the same OTel attribute mapping so events look the same everywhere.-- **Cached tokens:** In the **response parsing** step, always set **`scope._cache_read_input_tokens`** (and **`scope._cache_creation_input_tokens`** if the API exposes it), defaulting to 0. Then in common_*_logic, set the span attributes when the scope has them (even when 0), and pass the same values in **extra** so the event gets them too.-------## 6. Summary Checklist for New Instrumentations--- [ ] Use **`common_span_attributes()`** for base span attributes.-- [ ] Set **usage attributes** on the span (input/output tokens, cost, **cache_read** and **cache_creation** even when 0).-- [ ] Use **`_set_span_messages_as_array(span, input_messages, output_messages)`** with provider-specific **`build_input_messages`** / **`build_output_messages`** so **`gen_ai.input.messages`** and **`gen_ai.output.messages`** are JSON arrays on both span and event.-- [ ] Emit one **`gen_ai.client.inference.operation.details`** event per invocation via an **`emit_inference_event`**-style helper, with **extra** including **`cache_read_input_tokens`** and **`cache_creation_input_tokens`** (even when 0).-- [ ] Map **extra** keys to **`SemanticConvention`** constants inside the event helper (no raw OTel strings in call sites).-- [ ] Parse **cached token** fields from the provider’s usage object into **scope** and pass them through to both span and event.-- [ ] Use a **scope** object with underscored attributes and a single **common_*_logic** path so streaming and non-streaming share the same attribute and event logic.--This keeps span attributes and span events consistent across providers and aligned with OTel GenAI semantic conventions while preserving a clear, reusable code structure.diff --git a/sdk/python/src/openlit/_instrumentors.py b/sdk/python/src/openlit/_instrumentors.pyindex da07111f..c57d8d54 100644--- a/sdk/python/src/openlit/_instrumentors.py+++ b/sdk/python/src/openlit/_instrumentors.py@@ -55,6 +55,8 @@ MODULE_NAME_MAP = {"browser-use": "browser_use","mcp": "mcp","google-adk": "google.adk",+ "claude-agent-sdk": "claude_agent_sdk",+ "agent-framework": "agent_framework",# Database instrumentations"psycopg": "psycopg","psycopg-pool": "psycopg_pool",@@ -126,6 +128,8 @@ INSTRUMENTOR_MAP = {"browser-use": "openlit.instrumentation.browser_use.BrowserUseInstrumentor","mcp": "openlit.instrumentation.mcp.MCPInstrumentor","google-adk": "openlit.instrumentation.google_adk.GoogleADKInstrumentor",+ "claude-agent-sdk": "openlit.instrumentation.claude_agent_sdk.ClaudeAgentSDKInstrumentor",+ "agent-framework": "openlit.instrumentation.agent_framework.AgentFrameworkInstrumentor",# Database instrumentations"psycopg": "openlit.instrumentation.psycopg.PsycopgInstrumentor","psycopg-pool": "openlit.instrumentation.psycopg.PsycopgInstrumentor",diff --git a/sdk/python/src/openlit/instrumentation/agent_framework/__init__.py b/sdk/python/src/openlit/instrumentation/agent_framework/__init__.pynew file mode 100644index 00000000..19781c96--- /dev/null+++ b/sdk/python/src/openlit/instrumentation/agent_framework/__init__.py@@ -0,0 +1,305 @@+"""+OpenLIT Microsoft Agent Framework Instrumentation — OTel GenAI semantic+convention compliant.++Provides auto-instrumentation for Microsoft Agent Framework including:+- Agent execution (Agent.run -> invoke_agent spans)+- Tool execution (FunctionTool.invoke -> execute_tool spans)+- Agent construction (Agent.__init__ -> create_agent spans, detailed_tracing only)+- Workflow execution (Workflow.run -> invoke_workflow spans, detailed_tracing only)++Disables AF's built-in telemetry (AgentTelemetryLayer / ChatTelemetryLayer)+via the global OBSERVABILITY_SETTINGS singleton to avoid duplicate spans, then+replaces them with OpenLIT-enriched OTel GenAI semconv-compliant spans.+"""++import json+import threading+from typing import Collection+import importlib.metadata++from opentelemetry.instrumentation.instrumentor import BaseInstrumentor+from opentelemetry.trace import SpanKind, Status, StatusCode+from wrapt import wrap_function_wrapper++from openlit.__helpers import handle_exception, truncate_content+from openlit.semcov import SemanticConvention++_instruments = ("agent-framework >= 1.0.0rc1",)++WORKFLOW_OPERATIONS = [+ ("agent_framework", "Agent.run", "agent_run", "agent_run"),+ ("agent_framework._tools", "FunctionTool.invoke", "tool_execute", "async"),+]++DETAILED_OPERATIONS = [+ ("agent_framework", "Agent.__init__", "agent_init", "sync"),+ ("agent_framework._workflows._workflow", "Workflow.run", "workflow_run", "async"),+]+++class _AgentCreationRegistry:+ """Thread-safe registry mapping agent name -> SpanContext from create_agent spans.++ Used to provide span links from invoke_agent back to create_agent,+ matching the pattern used in CrewAI, Google ADK, and OpenAI Agents+ instrumentations.+ """++ def __init__(self):+ self._lock = threading.Lock()+ self._contexts: dict = {}++ def register(self, agent_name, span_context):+ """Store the span context for a given agent name."""+ with self._lock:+ self._contexts[agent_name] = span_context++ def get(self, agent_name):+ """Retrieve the span context for a given agent name, or ``None``."""+ with self._lock:+ return self._contexts.get(agent_name)++ def get_all(self):+ """Return all registered span contexts."""+ with self._lock:+ return list(self._contexts.values())+++def _wrap_agent_init(+ tracer, environment, application_name, capture_message_content, registry+):+ """Return a wrapt wrapper for ``Agent.__init__`` that emits a+ ``create_agent`` span per agent construction."""++ def wrapper(wrapped, instance, args, kwargs):+ result = wrapped(*args, **kwargs)++ try:+ name = (+ getattr(instance, "name", None)+ or getattr(instance, "id", None)+ or "agent"+ )+ span_name = f"create_agent {name}"++ with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:+ span.set_attribute(+ SemanticConvention.GEN_AI_OPERATION,+ SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT,+ )+ span.set_attribute(+ SemanticConvention.GEN_AI_PROVIDER_NAME,+ SemanticConvention.GEN_AI_SYSTEM_AGENT_FRAMEWORK,+ )+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_NAME, str(name))++ agent_id = getattr(instance, "id", None)+ if agent_id:+ span.set_attribute(+ SemanticConvention.GEN_AI_AGENT_ID, str(agent_id)+ )++ description = getattr(instance, "description", None)+ if description:+ span.set_attribute(+ SemanticConvention.GEN_AI_AGENT_DESCRIPTION,+ str(description),+ )++ model_id = getattr(instance, "model_id", None)+ if not model_id:+ chat_client = getattr(instance, "chat_client", None)+ if chat_client:+ model_id = getattr(chat_client, "model_id", None)+ if model_id:+ span.set_attribute(+ SemanticConvention.GEN_AI_REQUEST_MODEL, str(model_id)+ )++ instructions = getattr(instance, "instructions", None)+ if instructions and capture_message_content:+ span.set_attribute(+ SemanticConvention.GEN_AI_SYSTEM_INSTRUCTIONS,+ json.dumps(+ [+ {+ "type": "text",+ "content": truncate_content(str(instructions)),+ }+ ]+ ),+ )++ tools = getattr(instance, "tools", None)+ if tools:+ tool_defs = []+ for t in (tools if not hasattr(tools, "__iter__") else list(tools))[+ :20+ ]:+ t_name = (+ getattr(t, "name", None)+ or getattr(t, "__name__", None)+ or type(t).__name__+ )+ entry = {"type": "function", "name": str(t_name)}+ t_desc = getattr(t, "description", None)+ if t_desc:+ entry["description"] = truncate_content(str(t_desc))+ tool_defs.append(entry)+ if tool_defs:+ span.set_attribute(+ SemanticConvention.GEN_AI_TOOL_DEFINITIONS,+ json.dumps(tool_defs),+ )++ span.set_attribute(SemanticConvention.GEN_AI_ENVIRONMENT, environment)+ span.set_attribute(+ SemanticConvention.GEN_AI_APPLICATION_NAME, application_name+ )+ span.set_status(Status(StatusCode.OK))++ creation_ctx = span.get_span_context()+ instance._openlit_creation_context = creation_ctx+ registry.register(str(name), creation_ctx)+ except Exception as e:+ handle_exception(span, e)++ return result++ return wrapper+++def _disable_af_telemetry():+ """Disable Agent Framework's built-in OpenTelemetry instrumentation.++ AF uses a global ``OBSERVABILITY_SETTINGS`` singleton that gates all+ telemetry. Setting ``enable_instrumentation = False`` causes+ ``AgentTelemetryLayer.run()`` and ``ChatTelemetryLayer.get_response()``+ to pass through directly to the underlying methods with zero overhead.++ Returns the previous value so it can be restored in _uninstrument().+ """+ try:+ from agent_framework.observability import OBSERVABILITY_SETTINGS++ previous = OBSERVABILITY_SETTINGS.enable_instrumentation+ OBSERVABILITY_SETTINGS.enable_instrumentation = False+ return previous+ except Exception:+ return None+++def _restore_af_telemetry(previous_value):+ """Restore AF's built-in telemetry setting."""+ if previous_value is None:+ return+ try:+ from agent_framework.observability import OBSERVABILITY_SETTINGS++ OBSERVABILITY_SETTINGS.enable_instrumentation = previous_value+ except Exception:+ pass+++class AgentFrameworkInstrumentor(BaseInstrumentor):+ """OTel GenAI semantic convention compliant instrumentor for+ Microsoft Agent Framework."""++ def __init__(self):+ super().__init__()+ self._previous_af_telemetry = None++ def instrumentation_dependencies(self) -> Collection[str]:+ return _instruments++ def _instrument(self, **kwargs):+ version = importlib.metadata.version("agent-framework")+ environment = kwargs.get("environment", "default")+ application_name = kwargs.get("application_name", "default")+ tracer = kwargs.get("tracer")+ pricing_info = kwargs.get("pricing_info", {})+ capture_message_content = kwargs.get("capture_message_content", False)+ metrics = kwargs.get("metrics_dict")+ disable_metrics = kwargs.get("disable_metrics")+ detailed_tracing = kwargs.get("detailed_tracing", False)++ agent_registry = _AgentCreationRegistry()++ self._previous_af_telemetry = _disable_af_telemetry()++ from openlit.instrumentation.agent_framework.async_agent_framework import (+ agent_run_wrap,+ tool_execute_wrap,+ workflow_run_wrap,+ )++ for module, method, op_key, _sync_type in WORKFLOW_OPERATIONS:+ try:+ if op_key == "agent_run":+ wrapper = agent_run_wrap(+ op_key,+ version,+ environment,+ application_name,+ tracer,+ pricing_info,+ capture_message_content,+ metrics,+ disable_metrics,+ agent_registry,+ )+ elif op_key == "tool_execute":+ wrapper = tool_execute_wrap(+ op_key,+ version,+ environment,+ application_name,+ tracer,+ pricing_info,+ capture_message_content,+ metrics,+ disable_metrics,+ agent_registry,+ )+ else:+ continue++ wrap_function_wrapper(module, method, wrapper)+ except Exception:+ pass++ if detailed_tracing:+ for module, method, op_key, _sync_type in DETAILED_OPERATIONS:+ try:+ if op_key == "agent_init":+ wrapper = _wrap_agent_init(+ tracer,+ environment,+ application_name,+ capture_message_content,+ agent_registry,+ )+ elif op_key == "workflow_run":+ wrapper = workflow_run_wrap(+ op_key,+ version,+ environment,+ application_name,+ tracer,+ pricing_info,+ capture_message_content,+ metrics,+ disable_metrics,+ agent_registry,+ )+ else:+ continue++ wrap_function_wrapper(module, method, wrapper)+ except Exception:+ pass++ def _uninstrument(self, **kwargs):+ """Restore AF's built-in telemetry."""+ _restore_af_telemetry(self._previous_af_telemetry)diff --git a/sdk/python/src/openlit/instrumentation/agent_framework/async_agent_framework.py b/sdk/python/src/openlit/instrumentation/agent_framework/async_agent_framework.pynew file mode 100644index 00000000..20251166--- /dev/null+++ b/sdk/python/src/openlit/instrumentation/agent_framework/async_agent_framework.py@@ -0,0 +1,452 @@+"""+Microsoft Agent Framework async wrappers — OTel GenAI semantic convention+compliant.++Handles AF's ``Agent.run()`` which is a sync method returning either+``Awaitable[AgentResponse]`` (stream=False) or ``ResponseStream``+(stream=True). Also handles ``Workflow.run`` for invoke_workflow spans+and ``FunctionTool.invoke`` for execute_tool spans.+"""++import time+from opentelemetry import context as context_api+from opentelemetry import trace as trace_api+from opentelemetry.trace import Link, Status, StatusCode++from openlit.__helpers import handle_exception+from openlit.instrumentation.agent_framework.utils import (+ OPERATION_MAP,+ get_span_kind,+ generate_span_name,+ process_agent_framework_response,+ _capture_input_messages,+ _capture_output_messages,+ _extract_response_attributes,+ _set_tool_attributes,+ _record_metrics,+ SemanticConvention,+)+++def _serialize_content_list(result):+ """Serialize AF ``list[Content]`` to a human-readable string.++ ``Content.__str__`` already returns the text for text-type items, a+ formatted error string for error items, etc. We join multiple items+ with newlines so the attribute stays readable.+ """+ if result is None:+ return None+ if isinstance(result, list):+ parts = [str(item) for item in result if item is not None]+ return "\n".join(parts) if parts else None+ return str(result)+++def agent_run_wrap(+ gen_ai_endpoint,+ version,+ environment,+ application_name,+ tracer,+ pricing_info,+ capture_message_content,+ metrics,+ disable_metrics,+ agent_registry,+):+ """Create a wrapper for ``Agent.run()``.++ Agent.run() is a sync method that returns either:+ - Awaitable[AgentResponse] when stream=False+ - ResponseStream when stream=True++ We wrap it to intercept both paths.+ """++ def wrapper(wrapped, instance, args, kwargs):+ if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):+ return wrapped(*args, **kwargs)++ operation_type = OPERATION_MAP.get(+ gen_ai_endpoint, SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT+ )+ span_kind = get_span_kind(operation_type)+ span_name = generate_span_name(gen_ai_endpoint, instance, args, kwargs)++ links = []+ agent_name = getattr(instance, "name", None) or getattr(instance, "id", None)+ if agent_name:+ creation_ctx = agent_registry.get(str(agent_name))+ if creation_ctx:+ links = [Link(creation_ctx)]++ is_stream = kwargs.get("stream", False)++ if is_stream:+ return _wrap_stream(+ wrapped,+ instance,+ args,+ kwargs,+ tracer,+ span_name,+ span_kind,+ links,+ gen_ai_endpoint,+ version,+ environment,+ application_name,+ capture_message_content,+ metrics,+ disable_metrics,+ )++ return _wrap_awaitable(+ wrapped,+ instance,+ args,+ kwargs,+ tracer,+ span_name,+ span_kind,+ links,+ gen_ai_endpoint,+ version,+ environment,+ application_name,+ capture_message_content,+ metrics,+ disable_metrics,+ )++ return wrapper+++def _wrap_awaitable(+ wrapped,+ instance,+ args,+ kwargs,+ tracer,+ span_name,+ span_kind,+ links,+ gen_ai_endpoint,+ version,+ environment,+ application_name,+ capture_message_content,+ metrics,+ disable_metrics,+):+ """Wrap the non-streaming path: Agent.run(stream=False) -> Awaitable[AgentResponse]."""++ result_awaitable = wrapped(*args, **kwargs)++ async def _instrumented():+ with tracer.start_as_current_span(+ span_name, kind=span_kind, links=links+ ) as span:+ start_time = time.time()++ session = kwargs.get("session")+ if session:+ session_id = getattr(session, "service_session_id", None)+ if session_id:+ span.set_attribute(+ SemanticConvention.GEN_AI_CONVERSATION_ID,+ str(session_id),+ )++ messages = kwargs.get("messages") or (args[0] if args else None)+ if capture_message_content and messages:+ _capture_input_messages(span, messages)++ try:+ response = await result_awaitable++ process_agent_framework_response(+ span,+ gen_ai_endpoint,+ instance,+ start_time,+ version,+ environment,+ application_name,+ capture_message_content,+ metrics,+ disable_metrics,+ response=response,+ )++ return response++ except Exception as e:+ handle_exception(span, e)+ raise++ return _instrumented()+++def _wrap_stream(+ wrapped,+ instance,+ args,+ kwargs,+ tracer,+ span_name,+ span_kind,+ links,+ gen_ai_endpoint,+ version,+ environment,+ application_name,+ capture_message_content,+ metrics,+ disable_metrics,+):+ """Wrap the streaming path: Agent.run(stream=True) -> ResponseStream.++ We activate the span in the OTel context *before* calling the original so+ that any child operations (e.g. OpenAI chat completions) created during+ stream iteration inherit this span as their parent. The context token is+ detached when the stream finalizes or is garbage-collected.+ """++ span = tracer.start_span(span_name, kind=span_kind, links=links)+ ctx = trace_api.set_span_in_context(span)+ token = context_api.attach(ctx)+ start_time = time.time()++ try:+ result_stream = wrapped(*args, **kwargs)+ except Exception as e:+ handle_exception(span, e)+ context_api.detach(token)+ span.end()+ raise++ session = kwargs.get("session")+ if session:+ session_id = getattr(session, "service_session_id", None)+ if session_id:+ span.set_attribute(+ SemanticConvention.GEN_AI_CONVERSATION_ID,+ str(session_id),+ )++ messages = kwargs.get("messages") or (args[0] if args else None)+ if capture_message_content and messages:+ _capture_input_messages(span, messages)++ span_state = {"closed": False}++ def _close_span():+ if span_state["closed"]:+ return+ span_state["closed"] = True+ try:+ context_api.detach(token)+ except Exception:+ pass+ span.end()++ async def _finalize_stream():+ try:+ response = await result_stream.get_final_response()+ _extract_response_attributes(span, response)+ if capture_message_content:+ _capture_output_messages(span, response)++ process_agent_framework_response(+ span,+ gen_ai_endpoint,+ instance,+ start_time,+ version,+ environment,+ application_name,+ capture_message_content,+ metrics,+ disable_metrics,+ response=response,+ )+ except Exception as e:+ handle_exception(span, e)+ finally:+ _close_span()++ try:+ wrapped_stream = result_stream.with_cleanup_hook(_finalize_stream)+ except (AttributeError, TypeError):+ _close_span()+ return result_stream++ import weakref++ weakref.finalize(wrapped_stream, _close_span)++ return wrapped_stream+++def tool_execute_wrap(+ gen_ai_endpoint,+ version,+ environment,+ application_name,+ tracer,+ pricing_info,+ capture_message_content,+ metrics,+ disable_metrics,+ agent_registry,+):+ """Create a wrapper for ``FunctionTool.invoke()`` that emits ``execute_tool`` spans.++ The tool span is automatically a child of the active ``invoke_agent`` span+ because OTel context propagation is in effect during agent execution.+ """++ def wrapper(wrapped, instance, args, kwargs):+ if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):+ return wrapped(*args, **kwargs)++ operation_type = OPERATION_MAP.get(+ gen_ai_endpoint, SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS+ )+ span_kind = get_span_kind(operation_type)+ span_name = generate_span_name(gen_ai_endpoint, instance, args, kwargs)++ tool_call_id = kwargs.get("tool_call_id")+ raw_arguments = kwargs.get("arguments")+ if raw_arguments is not None:+ if hasattr(raw_arguments, "model_dump"):+ tool_arguments = raw_arguments.model_dump()+ elif isinstance(raw_arguments, dict):+ tool_arguments = dict(raw_arguments)+ else:+ tool_arguments = raw_arguments+ else:+ tool_arguments = None++ async def _instrumented():+ with tracer.start_as_current_span(span_name, kind=span_kind) as span:+ start_time = time.time()++ span.set_attribute(SemanticConvention.GEN_AI_OPERATION, operation_type)+ span.set_attribute(+ SemanticConvention.GEN_AI_PROVIDER_NAME,+ SemanticConvention.GEN_AI_SYSTEM_AGENT_FRAMEWORK,+ )+ span.set_attribute(SemanticConvention.GEN_AI_ENVIRONMENT, environment)+ span.set_attribute(+ SemanticConvention.GEN_AI_APPLICATION_NAME, application_name+ )++ _set_tool_attributes(+ span,+ instance,+ capture_message_content,+ tool_call_id=tool_call_id,+ arguments=tool_arguments,+ )++ try:+ result = await wrapped(*args, **kwargs)++ serialized_result = _serialize_content_list(result)+ _set_tool_attributes(+ span,+ None,+ capture_message_content,+ result=serialized_result,+ )++ duration = time.time() - start_time++ if not disable_metrics and metrics:+ _record_metrics(+ metrics,+ operation_type,+ duration,+ environment,+ application_name,+ "unknown",+ "",+ 0,+ )++ span.set_status(Status(StatusCode.OK))+ return result++ except Exception as e:+ handle_exception(span, e)+ raise++ return _instrumented()++ return wrapper+++def workflow_run_wrap(+ gen_ai_endpoint,+ version,+ environment,+ application_name,+ tracer,+ pricing_info,+ capture_message_content,+ metrics,+ disable_metrics,+ agent_registry,+):+ """Create a wrapper for ``Workflow.run()`` that emits ``invoke_workflow`` spans."""++ def wrapper(wrapped, instance, args, kwargs):+ if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):+ return wrapped(*args, **kwargs)++ operation_type = OPERATION_MAP.get(+ gen_ai_endpoint, SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK+ )+ span_kind = get_span_kind(operation_type)+ span_name = generate_span_name(gen_ai_endpoint, instance, args, kwargs)++ links = []+ all_contexts = agent_registry.get_all()+ if all_contexts:+ links = [Link(ctx) for ctx in all_contexts]++ async def _instrumented():+ with tracer.start_as_current_span(+ span_name, kind=span_kind, links=links+ ) as span:+ start_time = time.time()++ try:+ response = await wrapped(*args, **kwargs)++ process_agent_framework_response(+ span,+ gen_ai_endpoint,+ instance,+ start_time,+ version,+ environment,+ application_name,+ capture_message_content,+ metrics,+ disable_metrics,+ response=response,+ )++ return response++ except Exception as e:+ handle_exception(span, e)+ raise++ return _instrumented()++ return wrapperdiff --git a/sdk/python/src/openlit/instrumentation/agent_framework/utils.py b/sdk/python/src/openlit/instrumentation/agent_framework/utils.pynew file mode 100644index 00000000..3c23a60d--- /dev/null+++ b/sdk/python/src/openlit/instrumentation/agent_framework/utils.py@@ -0,0 +1,540 @@+"""+Microsoft Agent Framework utilities for OTel GenAI semantic convention+compliant telemetry.++Follows the same patterns as CrewAI / Google ADK / OpenAI Agents+instrumentations. All operation names, span kinds, and attributes comply+with the OTel GenAI semantic conventions (gen-ai-spans.md,+gen-ai-agent-spans.md).+"""++import time+import json+from opentelemetry.trace import SpanKind, Status, StatusCode++from openlit.__helpers import (+ common_framework_span_attributes,+ truncate_content,+)+from openlit.semcov import SemanticConvention++# ---------------------------------------------------------------------------+# OTel GenAI operation mapping+# ---------------------------------------------------------------------------+OPERATION_MAP = {+ "agent_init": SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT,+ "agent_run": SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,+ "tool_execute": SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS,+ "workflow_run": SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK,+}++# ---------------------------------------------------------------------------+# SpanKind per operation (OTel GenAI spec)+# ---------------------------------------------------------------------------+SPAN_KIND_MAP = {+ SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT: SpanKind.CLIENT,+ SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT: SpanKind.INTERNAL,+ SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK: SpanKind.INTERNAL,+ SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS: SpanKind.INTERNAL,+}+++def get_operation_type(endpoint):+ """Return the standard ``gen_ai.operation.name`` for an AF endpoint."""+ return OPERATION_MAP.get(endpoint, SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT)+++def get_span_kind(operation_type):+ """Return the correct ``SpanKind`` per OTel GenAI spec."""+ return SPAN_KIND_MAP.get(operation_type, SpanKind.INTERNAL)+++# ---------------------------------------------------------------------------+# Span name generation+# ---------------------------------------------------------------------------+def generate_span_name(endpoint, instance, args=None, kwargs=None):+ """Return an OTel-compliant span name: ``{operation} {entity_name}``."""+ operation_type = get_operation_type(endpoint)++ if endpoint == "agent_init":+ name = (+ getattr(instance, "name", None) or getattr(instance, "id", None) or "agent"+ )+ return f"create_agent {name}"++ if endpoint == "agent_run":+ name = (+ getattr(instance, "name", None) or getattr(instance, "id", None) or "agent"+ )+ return f"invoke_agent {name}"++ if endpoint == "tool_execute":+ name = getattr(instance, "name", None) or type(instance).__name__+ return f"execute_tool {name}"++ if endpoint == "workflow_run":+ name = (+ getattr(instance, "name", None)+ or getattr(instance, "id", None)+ or "workflow"+ )+ return f"invoke_workflow {name}"++ return f"{operation_type} {endpoint}"+++# ---------------------------------------------------------------------------+# Model name extraction+# ---------------------------------------------------------------------------+def _extract_model_name(instance):+ """Best-effort model name extraction from an AF Agent instance."""+ if not instance:+ return "unknown"++ model_id = getattr(instance, "model_id", None)+ if model_id:+ return str(model_id)++ chat_client = getattr(instance, "chat_client", None)+ if chat_client:+ model_id = getattr(chat_client, "model_id", None)+ if model_id:+ return str(model_id)++ default_options = getattr(instance, "default_options", None)+ if default_options and isinstance(default_options, dict):+ model_id = default_options.get("model_id")+ if model_id:+ return str(model_id)++ return "unknown"+++# ---------------------------------------------------------------------------+# Server address resolution+# ---------------------------------------------------------------------------+def _resolve_server_info(instance):+ """Return ``(server_address, server_port)`` from an AF agent's chat client."""+ server_address = ""+ server_port = 0+ try:+ chat_client = getattr(instance, "chat_client", None)+ if chat_client:+ service_url_fn = getattr(chat_client, "service_url", None)+ if callable(service_url_fn):+ url_str = str(service_url_fn())+ if url_str and url_str != "unknown":+ from urllib.parse import urlparse++ parsed = urlparse(url_str)+ server_address = parsed.hostname or ""+ server_port = parsed.port or 443+ except Exception:+ pass+ return server_address, server_port+++# ---------------------------------------------------------------------------+# Main response processor+# ---------------------------------------------------------------------------+def process_agent_framework_response(+ span,+ endpoint,+ instance,+ start_time,+ version,+ environment,+ application_name,+ capture_message_content,+ metrics,+ disable_metrics,+ response=None,+):+ """Set OTel-compliant span attributes and record metrics for a completed span."""+ end_time = time.time()++ operation_type = get_operation_type(endpoint)+ server_address, server_port = _resolve_server_info(instance)+ request_model = _extract_model_name(instance)++ scope = type("Scope", (), {})()+ scope._span = span+ scope._start_time = start_time+ scope._end_time = end_time++ model_proxy = (+ type("P", (), {"model_name": request_model})() if request_model else None+ )++ common_framework_span_attributes(+ scope,+ SemanticConvention.GEN_AI_SYSTEM_AGENT_FRAMEWORK,+ server_address,+ server_port,+ environment,+ application_name,+ version,+ operation_type,+ model_proxy,+ )++ if endpoint == "agent_run":+ _set_agent_attributes(span, instance)+ _extract_response_attributes(span, response)+ if capture_message_content:+ _capture_output_messages(span, response)++ elif endpoint == "workflow_run":+ _set_workflow_attributes(span, instance)++ span.set_attribute(+ SemanticConvention.GEN_AI_OUTPUT_TYPE,+ SemanticConvention.GEN_AI_OUTPUT_TYPE_TEXT,+ )++ if not disable_metrics and metrics:+ _record_metrics(+ metrics,+ operation_type,+ end_time - start_time,+ environment,+ application_name,+ request_model,+ server_address,+ server_port,+ )++ span.set_status(Status(StatusCode.OK))+++# ---------------------------------------------------------------------------+# Attribute setters+# ---------------------------------------------------------------------------+def _set_agent_attributes(span, instance):+ """Set agent-related attributes per OTel GenAI semantic conventions."""+ try:+ agent_id = getattr(instance, "id", None)+ if agent_id:+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_ID, str(agent_id))++ agent_name = getattr(instance, "name", None)+ if agent_name:+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_NAME, str(agent_name))+ elif agent_id:+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_NAME, str(agent_id))++ description = getattr(instance, "description", None)+ if description:+ span.set_attribute(+ SemanticConvention.GEN_AI_AGENT_DESCRIPTION, str(description)+ )+ except Exception:+ pass+++def _set_workflow_attributes(span, instance):+ """Set workflow-related attributes per OTel GenAI semantic conventions."""+ try:+ name = getattr(instance, "name", None) or getattr(instance, "id", None)+ if name:+ span.set_attribute(SemanticConvention.GEN_AI_WORKFLOW_NAME, str(name))+ except Exception:+ pass+++def _set_tool_attributes(+ span,+ function_tool,+ capture_message_content,+ tool_call_id=None,+ arguments=None,+ result=None,+):+ """Set tool-related attributes per OTel GenAI semantic conventions."""+ try:+ if function_tool:+ tool_name = (+ getattr(function_tool, "name", None) or type(function_tool).__name__+ )+ span.set_attribute(SemanticConvention.GEN_AI_TOOL_NAME, str(tool_name))+ span.set_attribute(SemanticConvention.GEN_AI_TOOL_TYPE, "function")++ tool_desc = getattr(function_tool, "description", None)+ if tool_desc:+ span.set_attribute(+ SemanticConvention.GEN_AI_TOOL_DESCRIPTION,+ truncate_content(str(tool_desc)),+ )++ if tool_call_id:+ span.set_attribute(+ SemanticConvention.GEN_AI_TOOL_CALL_ID, str(tool_call_id)+ )++ if capture_message_content:+ if arguments is not None:+ try:+ args_str = (+ json.dumps(arguments)+ if isinstance(arguments, dict)+ else str(arguments)+ )+ except (TypeError, ValueError):+ args_str = str(arguments)+ span.set_attribute(+ SemanticConvention.GEN_AI_TOOL_CALL_ARGUMENTS,+ truncate_content(args_str),+ )+ if result is not None:+ try:+ result_str = (+ json.dumps(result)+ if isinstance(result, (dict, list))+ else str(result)+ )+ except (TypeError, ValueError):+ result_str = str(result)+ span.set_attribute(+ SemanticConvention.GEN_AI_TOOL_CALL_RESULT,+ truncate_content(result_str),+ )+ except Exception:+ pass+++# ---------------------------------------------------------------------------+# Response attribute extraction+# ---------------------------------------------------------------------------+def _extract_response_attributes(span, response):+ """Extract token usage, model, and response ID from an AgentResponse."""+ if response is None:+ return+ try:+ response_id = getattr(response, "response_id", None)+ if response_id:+ span.set_attribute(SemanticConvention.GEN_AI_RESPONSE_ID, str(response_id))++ model_id = getattr(response, "model_id", None)+ if model_id:+ span.set_attribute(SemanticConvention.GEN_AI_RESPONSE_MODEL, str(model_id))++ usage = getattr(response, "usage_details", None)+ if usage and isinstance(usage, dict):+ input_tokens = usage.get("input_token_count")+ if input_tokens is not None:+ span.set_attribute(+ SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS, int(input_tokens)+ )+ output_tokens = usage.get("output_token_count")+ if output_tokens is not None:+ span.set_attribute(+ SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS, int(output_tokens)+ )++ finish_reason = getattr(response, "finish_reason", None)+ if finish_reason:+ span.set_attribute(+ SemanticConvention.GEN_AI_RESPONSE_FINISH_REASON,+ [str(finish_reason)],+ )+ except Exception:+ pass+++# ---------------------------------------------------------------------------+# Content capture+# ---------------------------------------------------------------------------+def _capture_input_messages(span, messages):+ """Set ``gen_ai.input.messages`` from user input messages."""+ try:+ if messages is None:+ return+ if isinstance(messages, str):+ otel_msgs = [{"role": "user", "content": truncate_content(messages)}]+ span.set_attribute(+ SemanticConvention.GEN_AI_INPUT_MESSAGES, json.dumps(otel_msgs)+ )+ return++ if isinstance(messages, list):+ otel_msgs = []+ for msg in messages[:20]:+ if isinstance(msg, str):+ otel_msgs.append({"role": "user", "content": truncate_content(msg)})+ elif hasattr(msg, "role") and hasattr(msg, "contents"):+ parts = []+ for content in getattr(msg, "contents", []):+ content_type = getattr(content, "type", "text")+ if content_type == "text":+ text = getattr(content, "text", "")+ parts.append(+ {"type": "text", "content": truncate_content(str(text))}+ )+ elif content_type == "function_call":+ parts.append(+ {+ "type": "tool_call",+ "id": getattr(content, "call_id", ""),+ "name": getattr(content, "name", ""),+ "arguments": str(getattr(content, "arguments", "")),+ }+ )+ elif content_type == "function_result":+ parts.append(+ {+ "type": "tool_call_response",+ "id": getattr(content, "call_id", ""),+ "response": str(getattr(content, "result", "")),+ }+ )+ otel_msgs.append(+ {+ "role": str(getattr(msg, "role", "user")),+ "parts": parts,+ }+ )+ elif isinstance(msg, dict):+ otel_msgs.append(+ {+ "role": msg.get("role", "user"),+ "content": truncate_content(str(msg.get("content", ""))),+ }+ )+ if otel_msgs:+ span.set_attribute(+ SemanticConvention.GEN_AI_INPUT_MESSAGES,+ json.dumps(otel_msgs),+ )+ except Exception:+ pass+++def _capture_output_messages(span, response):+ """Set ``gen_ai.output.messages`` from an AgentResponse."""+ if response is None:+ return+ try:+ messages = getattr(response, "messages", None)+ if not messages:+ return+ otel_msgs = []+ for msg in messages[:20]:+ parts = []+ for content in getattr(msg, "contents", []):+ content_type = getattr(content, "type", "text")+ if content_type == "text":+ text = getattr(content, "text", "")+ parts.append(+ {"type": "text", "content": truncate_content(str(text))}+ )+ elif content_type == "function_call":+ parts.append(+ {+ "type": "tool_call",+ "id": getattr(content, "call_id", ""),+ "name": getattr(content, "name", ""),+ "arguments": str(getattr(content, "arguments", "")),+ }+ )+ elif content_type == "function_result":+ parts.append(+ {+ "type": "tool_call_response",+ "id": getattr(content, "call_id", ""),+ "response": str(getattr(content, "result", "")),+ }+ )+ else:+ text = getattr(content, "text", None)+ if text:+ parts.append(+ {"type": "text", "content": truncate_content(str(text))}+ )+ role = str(getattr(msg, "role", "assistant"))+ otel_msgs.append({"role": role, "parts": parts})+ if otel_msgs:+ span.set_attribute(+ SemanticConvention.GEN_AI_OUTPUT_MESSAGES, json.dumps(otel_msgs)+ )+ except Exception:+ pass+++def _capture_system_instructions(span, instance):+ """Set ``gen_ai.system_instructions`` from an agent's instructions."""+ try:+ instructions = getattr(instance, "instructions", None)+ if instructions:+ span.set_attribute(+ SemanticConvention.GEN_AI_SYSTEM_INSTRUCTIONS,+ json.dumps(+ [+ {+ "type": "text",+ "content": truncate_content(str(instructions)),+ }+ ]+ ),+ )+ except Exception:+ pass+++def _capture_tool_definitions(span, instance):+ """Set ``gen_ai.tool.definitions`` from an agent's tools."""+ try:+ tools = getattr(instance, "tools", None)+ if not tools:+ return+ tool_defs = []+ for t in tools[:20]:+ t_name = (+ getattr(t, "name", None)+ or getattr(t, "__name__", None)+ or type(t).__name__+ )+ entry = {"type": "function", "name": str(t_name)}+ t_desc = getattr(t, "description", None)+ if t_desc:+ entry["description"] = truncate_content(str(t_desc))+ tool_defs.append(entry)+ if tool_defs:+ span.set_attribute(+ SemanticConvention.GEN_AI_TOOL_DEFINITIONS, json.dumps(tool_defs)+ )+ except Exception:+ pass+++# ---------------------------------------------------------------------------+# Metrics+# ---------------------------------------------------------------------------+def _record_metrics(+ metrics,+ operation_type,+ duration,+ environment,+ application_name,+ request_model,+ server_address,+ server_port,+):+ """Record OTel-compliant metrics."""+ try:+ attributes = {+ SemanticConvention.GEN_AI_OPERATION: operation_type,+ SemanticConvention.GEN_AI_PROVIDER_NAME: SemanticConvention.GEN_AI_SYSTEM_AGENT_FRAMEWORK,+ "service.name": application_name,+ "deployment.environment": environment,+ }+ if request_model and request_model != "unknown":+ attributes[SemanticConvention.GEN_AI_REQUEST_MODEL] = request_model+ if server_address:+ attributes[SemanticConvention.SERVER_ADDRESS] = server_address+ if server_port:+ attributes[SemanticConvention.SERVER_PORT] = server_port++ if "genai_client_operation_duration" in metrics:+ metrics["genai_client_operation_duration"].record(duration, attributes)+ except Exception:+ passdiff --git a/sdk/python/src/openlit/instrumentation/claude_agent_sdk/__init__.py b/sdk/python/src/openlit/instrumentation/claude_agent_sdk/__init__.pynew file mode 100644index 00000000..bfa3ef5f--- /dev/null+++ b/sdk/python/src/openlit/instrumentation/claude_agent_sdk/__init__.py@@ -0,0 +1,117 @@+"""+OpenLIT Claude Agent SDK Instrumentation — OTel GenAI semantic convention compliant.++Wraps the Claude Agent SDK's ``query()`` and ``ClaudeSDKClient`` to emit+``invoke_agent`` and ``execute_tool`` spans following the same patterns as+CrewAI, LangGraph, and OpenAI Agents instrumentations.+"""++import importlib+import importlib.metadata+import sys+from typing import Collection+from opentelemetry.instrumentation.instrumentor import BaseInstrumentor+from wrapt import wrap_function_wrapper++from openlit.instrumentation.claude_agent_sdk.claude_agent_sdk import (+ wrap_query,+ wrap_connect,+ wrap_client_query,+ wrap_receive_response,+)++_instruments = ("claude-agent-sdk >= 0.1.0",)+++class ClaudeAgentSDKInstrumentor(BaseInstrumentor):+ """OTel GenAI semantic convention compliant instrumentor for Claude Agent SDK."""++ def instrumentation_dependencies(self) -> Collection[str]:+ return _instruments++ def _instrument(self, **kwargs):+ version = importlib.metadata.version("claude-agent-sdk")+ environment = kwargs.get("environment", "default")+ application_name = kwargs.get("application_name", "default")+ tracer = kwargs.get("tracer")+ pricing_info = kwargs.get("pricing_info", {})+ capture_message_content = kwargs.get("capture_message_content", False)+ metrics = kwargs.get("metrics_dict")+ disable_metrics = kwargs.get("disable_metrics")+ event_provider = kwargs.get("event_provider")++ wrap_args = (+ version,+ environment,+ application_name,+ tracer,+ pricing_info,+ capture_message_content,+ metrics,+ disable_metrics,+ )+ wrap_kwargs = {"event_provider": event_provider}++ # Wrap query() — stateless one-shot API+ try:+ sdk_module = importlib.import_module("claude_agent_sdk")+ original_query = getattr(sdk_module, "query", None)++ wrap_function_wrapper(+ "claude_agent_sdk.query",+ "query",+ wrap_query(*wrap_args, **wrap_kwargs),+ )++ query_module = importlib.import_module("claude_agent_sdk.query")+ wrapped_query = query_module.query+ setattr(sdk_module, "query", wrapped_query)++ if original_query is not None:+ for module in list(sys.modules.values()):+ try:+ if (+ module is not None+ and getattr(module, "query", None) is original_query+ ):+ setattr(module, "query", wrapped_query)+ except Exception:+ continue+ except Exception:+ pass++ # Wrap ClaudeSDKClient methods — stateful multi-turn API+ try:+ wrap_function_wrapper(+ "claude_agent_sdk.client",+ "ClaudeSDKClient.connect",+ wrap_connect(*wrap_args, **wrap_kwargs),+ )+ except Exception:+ pass++ try:+ wrap_function_wrapper(+ "claude_agent_sdk.client",+ "ClaudeSDKClient.query",+ wrap_client_query(*wrap_args, **wrap_kwargs),+ )+ except Exception:+ pass++ try:+ wrap_function_wrapper(+ "claude_agent_sdk.client",+ "ClaudeSDKClient.receive_response",+ wrap_receive_response(*wrap_args, **wrap_kwargs),+ )+ except Exception:+ pass++ def _uninstrument(self, **kwargs):+ try:+ sdk_module = importlib.import_module("claude_agent_sdk")+ query_module = importlib.import_module("claude_agent_sdk.query")+ setattr(sdk_module, "query", query_module.query)+ except Exception:+ passdiff --git a/sdk/python/src/openlit/instrumentation/claude_agent_sdk/claude_agent_sdk.py b/sdk/python/src/openlit/instrumentation/claude_agent_sdk/claude_agent_sdk.pynew file mode 100644index 00000000..879dd917--- /dev/null+++ b/sdk/python/src/openlit/instrumentation/claude_agent_sdk/claude_agent_sdk.py@@ -0,0 +1,934 @@+"""+Claude Agent SDK async wrappers — OTel GenAI semantic convention compliant.++Wraps ``query()`` and ``ClaudeSDKClient`` methods to produce ``invoke_agent``+and ``execute_tool`` spans using the same patterns as CrewAI / LangGraph.++Tool spans are created via the SDK's hook system (PreToolUse / PostToolUse /+PostToolUseFailure). A message-based fallback handles cases where hooks+cannot be injected.+"""++import time++from opentelemetry import context as context_api+from opentelemetry import trace as trace_api+from opentelemetry.trace import SpanKind, Status, StatusCode++from openlit.__helpers import handle_exception+from openlit.semcov import SemanticConvention+from openlit.instrumentation.claude_agent_sdk.utils import (+ generate_span_name,+ set_initial_span_attributes,+ update_root_from_assistant,+ has_llm_call_data,+ build_input_from_tool_results,+ set_chat_span_attributes,+ set_create_agent_attributes,+ process_result_message,+ finalize_span,+ set_tool_span_attributes,+ finalize_tool_span,+ GEN_AI_SYSTEM_ATTR,+ GEN_AI_SYSTEM_VALUE,+)++# Attribute key stored on client instances to pass prompt between wrappers+_PROMPT_ATTR = "_openlit_last_prompt"+_HOOKS_INJECTED_ATTR = "_openlit_hooks_injected"+++# ---------------------------------------------------------------------------+# Tool span tracker — shared between hooks and the message stream+# ---------------------------------------------------------------------------+class _ToolSpanTracker:+ """Manages in-flight tool spans created by SDK hooks."""++ def __init__(+ self,+ tracer,+ parent_span,+ version,+ environment,+ application_name,+ capture_message_content,+ ):+ self._tracer = tracer+ self._parent_span = parent_span+ self._version = version+ self._environment = environment+ self._application_name = application_name+ self._capture_message_content = capture_message_content+ self._in_flight: dict = {}+ self._completed: set = set()++ def start_tool(self, tool_name, tool_input, tool_use_id):+ """Create and track a new tool span."""+ span_name = generate_span_name("execute_tool", tool_name)+ parent_ctx = trace_api.set_span_in_context(self._parent_span)++ span = self._tracer.start_span(+ span_name, kind=SpanKind.INTERNAL, context=parent_ctx+ )+ set_tool_span_attributes(+ span,+ tool_name,+ tool_input,+ tool_use_id,+ self._capture_message_content,+ self._environment,+ self._application_name,+ self._version,+ )+ self._in_flight[tool_use_id] = span++ def end_tool(self, tool_use_id, tool_response=None):+ """End a tool span successfully."""+ span = self._in_flight.pop(tool_use_id, None)+ if span:+ finalize_tool_span(span, tool_response, self._capture_message_content)+ span.end()+ self._completed.add(tool_use_id)++ def end_tool_error(self, tool_use_id, error=None):+ """End a tool span with an error."""+ span = self._in_flight.pop(tool_use_id, None)+ if span:+ finalize_tool_span(+ span,+ None,+ self._capture_message_content,+ is_error=True,+ error_message=error,+ )+ span.end()+ self._completed.add(tool_use_id)++ def end_all(self):+ """End all in-flight tool spans (cleanup)."""+ for tool_use_id in list(self._in_flight.keys()):+ span = self._in_flight.pop(tool_use_id, None)+ if span:+ finalize_tool_span(+ span,+ None,+ self._capture_message_content,+ is_error=True,+ error_message="abandoned",+ )+ span.end()+++# ---------------------------------------------------------------------------+# Subagent span tracker — for Task tool (programmatic subagents)+# ---------------------------------------------------------------------------+class _SubagentSpanTracker:+ """Manages subagent spans triggered by TaskStarted / TaskNotification messages."""++ def __init__(self, tracer, tool_tracker, version, environment, application_name):+ self._tracer = tracer+ self._tool_tracker = tool_tracker+ self._version = version+ self._environment = environment+ self._application_name = application_name+ self._in_flight: dict = {}+ self._tool_use_to_task: dict = {}++ def start_subagent(self, task_id, description, tool_use_id=None):+ """Create a subagent span, parented under the corresponding tool span."""+ name = description or task_id or "subagent"+ span_name = generate_span_name("subagent", name)++ if tool_use_id:+ self._tool_use_to_task[tool_use_id] = task_id++ parent_span = None+ if tool_use_id and tool_use_id in self._tool_tracker._in_flight:+ parent_span = self._tool_tracker._in_flight[tool_use_id]++ ctx = trace_api.set_span_in_context(parent_span) if parent_span else None++ span = self._tracer.start_span(span_name, kind=SpanKind.INTERNAL, context=ctx)+ span.set_attribute(+ SemanticConvention.GEN_AI_OPERATION,+ SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,+ )+ span.set_attribute(+ SemanticConvention.GEN_AI_PROVIDER_NAME,+ SemanticConvention.GEN_AI_SYSTEM_CLAUDE_AGENT_SDK,+ )+ span.set_attribute(GEN_AI_SYSTEM_ATTR, GEN_AI_SYSTEM_VALUE)+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_NAME, str(name))+ span.set_attribute(SemanticConvention.GEN_AI_ENVIRONMENT, self._environment)+ span.set_attribute(+ SemanticConvention.GEN_AI_APPLICATION_NAME, self._application_name+ )+ span.set_attribute(SemanticConvention.GEN_AI_SDK_VERSION, self._version)++ self._in_flight[task_id] = span++ def end_subagent(self, task_id, is_error=False, error_message=None, usage=None):+ """End a subagent span, optionally setting usage attributes."""+ span = self._in_flight.pop(task_id, None)+ if span:+ if usage:+ total_tokens = usage.get("total_tokens")+ if total_tokens is not None:+ try:+ span.set_attribute(+ SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS,+ int(total_tokens),+ )+ except (TypeError, ValueError):+ pass+ tool_uses = usage.get("tool_uses")+ if tool_uses is not None:+ try:+ span.set_attribute("gen_ai.agent.tool_uses", int(tool_uses))+ except (TypeError, ValueError):+ pass+ duration_ms = usage.get("duration_ms")+ if duration_ms is not None:+ try:+ span.set_attribute("gen_ai.agent.duration_ms", int(duration_ms))+ except (TypeError, ValueError):+ pass++ if is_error:+ err = str(error_message) if error_message else "task failed"+ span.set_attribute(SemanticConvention.ERROR_TYPE, err)+ span.set_status(Status(StatusCode.ERROR, err))+ else:+ span.set_status(Status(StatusCode.OK))+ span.end()++ def get_span_for_tool_use_id(self, tool_use_id):+ """Return the subagent span that owns this tool_use_id, or None."""+ task_id = self._tool_use_to_task.get(tool_use_id)+ if task_id:+ return self._in_flight.get(task_id)+ return None++ def end_all(self):+ """End all in-flight subagent spans (cleanup)."""+ for task_id in list(self._in_flight.keys()):+ self.end_subagent(task_id, is_error=True, error_message="abandoned")+++# ---------------------------------------------------------------------------+# Hook factory — creates callbacks that drive the tool & subagent trackers+# ---------------------------------------------------------------------------+def _build_tool_hooks(tracker):+ """Return (pre, post, failure) async hook callbacks bound to *tracker*."""++ async def pre_tool_use(input_data, tool_use_id, context):+ try:+ tool_name = input_data.get("tool_name", "unknown")+ tool_input = input_data.get("tool_input")+ tracker.start_tool(tool_name, tool_input, tool_use_id)+ except Exception:+ pass+ return {}++ async def post_tool_use(input_data, tool_use_id, context):+ try:+ tool_response = input_data.get("tool_response")+ tracker.end_tool(tool_use_id, tool_response)+ except Exception:+ pass+ return {}++ async def post_tool_use_failure(input_data, tool_use_id, context):+ try:+ error = input_data.get("error", "unknown error")+ tracker.end_tool_error(tool_use_id, error)+ except Exception:+ pass+ return {}++ return pre_tool_use, post_tool_use, post_tool_use_failure+++def _build_subagent_hooks(subagent_tracker):+ """Return (start, stop) async hook callbacks bound to *subagent_tracker*."""++ async def subagent_start(input_data, tool_use_id, context):+ try:+ agent_id = input_data.get("agent_id")+ description = input_data.get("description", agent_id or "subagent")+ if agent_id and subagent_tracker:+ subagent_tracker.start_subagent(agent_id, description, tool_use_id)+ except Exception:+ pass+ return {}++ async def subagent_stop(input_data, tool_use_id, context):+ try:+ agent_id = input_data.get("agent_id")+ if not agent_id or not subagent_tracker:+ return {}+ error = input_data.get("error")+ is_error = bool(error)+ subagent_tracker.end_subagent(+ agent_id, is_error=is_error, error_message=error+ )+ except Exception:+ pass+ return {}++ return subagent_start, subagent_stop+++# ---------------------------------------------------------------------------+# Hook injection — merges OpenLIT hooks into user-provided options+# ---------------------------------------------------------------------------+def _inject_hooks(options, tracker, subagent_tracker=None):+ """Merge tracing hooks into *options*, preserving user-defined hooks.++ Modifies ``options.hooks`` in place and returns *options*.+ """+ try:+ from claude_agent_sdk.types import HookMatcher+ except ImportError:+ return options++ pre, post, failure = _build_tool_hooks(tracker)++ if options.hooks is None:+ options.hooks = {}++ hook_pairs = [+ ("PreToolUse", pre),+ ("PostToolUse", post),+ ("PostToolUseFailure", failure),+ ]++ if subagent_tracker:+ sa_start, sa_stop = _build_subagent_hooks(subagent_tracker)+ hook_pairs.extend(+ [+ ("SubagentStart", sa_start),+ ("SubagentStop", sa_stop),+ ]+ )++ for event, callback in hook_pairs:+ matcher = HookMatcher(matcher=None, hooks=[callback])+ if event in options.hooks:+ options.hooks[event].append(matcher)+ else:+ options.hooks[event] = [matcher]++ return options+++def _get_or_create_options(kwargs):+ """Return the ClaudeAgentOptions from *kwargs*, creating one if absent."""+ try:+ from claude_agent_sdk.types import ClaudeAgentOptions+ except ImportError:+ return kwargs.get("options"), kwargs++ options = kwargs.get("options")+ if options is None:+ options = ClaudeAgentOptions()+ kwargs["options"] = options+ return options, kwargs+++# ---------------------------------------------------------------------------+# Chat child span — deferred creation for correct content & ordering+# ---------------------------------------------------------------------------+def _buffer_chat_message(message, chat_state):+ """Buffer an AssistantMessage for deferred chat span creation.++ The Claude Agent SDK yields the same ``message_id`` in multiple chunks:+ first with text / thinking, then with tool_use blocks. By buffering+ and replacing on the same ``message_id``, we capture the most complete+ content. A different ``message_id`` means a new LLM turn — the caller+ must flush the previous buffer first via ``_flush_pending_chat``.+ """+ if not has_llm_call_data(message):+ return++ chat_state["pending_chat_msg"] = message+ chat_state["pending_chat_msg_id"] = getattr(message, "message_id", None)+ chat_state["pending_end_ns"] = time.time_ns()+++def _flush_pending_chat(+ tracer,+ parent_span,+ chat_state,+ capture_message_content,+ version,+ environment,+ application_name,+ pricing_info=None,+ event_provider=None,+ subagent_tracker=None,+):+ """Create a ``chat {model}`` child span from the buffered AssistantMessage."""+ message = chat_state.pop("pending_chat_msg", None)+ if message is None:+ return++ chat_state.pop("pending_chat_msg_id", None)+ end_ns = chat_state.pop("pending_end_ns", time.time_ns())++ model = str(getattr(message, "model", "unknown"))+ span_name = generate_span_name("chat", model)++ effective_parent = parent_span+ parent_tool_use_id = getattr(message, "parent_tool_use_id", None)+ if parent_tool_use_id and subagent_tracker:+ subagent_span = subagent_tracker.get_span_for_tool_use_id(parent_tool_use_id)+ if subagent_span:+ effective_parent = subagent_span++ parent_ctx = trace_api.set_span_in_context(effective_parent)+ start_ns = chat_state.get("last_boundary_ns", end_ns)++ chat_span = tracer.start_span(+ span_name,+ kind=SpanKind.CLIENT,+ context=parent_ctx,+ start_time=start_ns,+ )++ input_messages = chat_state.pop("pending_input", None)++ set_chat_span_attributes(+ chat_span,+ message,+ capture_message_content,+ environment,+ application_name,+ version,+ pricing_info=pricing_info,+ event_provider=event_provider,+ input_messages=input_messages,+ )+ chat_span.end(end_time=end_ns)++ chat_state["last_boundary_ns"] = end_ns+++# ---------------------------------------------------------------------------+# Message stream processor+# ---------------------------------------------------------------------------+def _process_message(+ message,+ span,+ tool_tracker,+ subagent_tracker,+ capture_message_content,+ tracer,+ chat_state,+ version,+ environment,+ application_name,+ pricing_info=None,+ event_provider=None,+):+ """Inspect a yielded message and update spans accordingly.++ Returns a usage dict ``{"input_tokens": int, "output_tokens": int}`` when+ the message is a ``ResultMessage``; ``None`` otherwise.+ """++ flush_kw = {+ "tracer": tracer,+ "parent_span": span,+ "chat_state": chat_state,+ "capture_message_content": capture_message_content,+ "version": version,+ "environment": environment,+ "application_name": application_name,+ "pricing_info": pricing_info,+ "event_provider": event_provider,+ "subagent_tracker": subagent_tracker,+ }++ msg_type = type(message).__name__+ result_usage = None++ if msg_type == "AssistantMessage":+ update_root_from_assistant(span, message)++ if has_llm_call_data(message):+ new_msg_id = getattr(message, "message_id", None)+ pending_msg_id = chat_state.get("pending_chat_msg_id")+ if pending_msg_id is not None and new_msg_id != pending_msg_id:+ _flush_pending_chat(**flush_kw)+ _buffer_chat_message(message, chat_state)++ elif msg_type == "UserMessage":+ _flush_pending_chat(**flush_kw)+ if capture_message_content:+ tool_input = build_input_from_tool_results(message)+ if tool_input:+ chat_state["pending_input"] = tool_input++ elif msg_type == "ResultMessage":+ _flush_pending_chat(**flush_kw)+ result_usage = process_result_message(span, message, capture_message_content)++ elif msg_type == "TaskStartedMessage":+ _flush_pending_chat(**flush_kw)+ try:+ task_id = getattr(message, "task_id", None)+ description = getattr(message, "description", None)+ tool_use_id = getattr(message, "tool_use_id", None)+ if task_id and subagent_tracker:+ subagent_tracker.start_subagent(task_id, description, tool_use_id)+ except Exception:+ pass++ elif msg_type == "TaskNotificationMessage":+ _flush_pending_chat(**flush_kw)+ try:+ task_id = getattr(message, "task_id", None)+ status = getattr(message, "status", None)+ is_error = status in ("failed", "error", "stopped")+ error_msg = getattr(message, "summary", None) if is_error else None+ task_usage = getattr(message, "usage", None)+ usage_dict = None+ if task_usage is not None:+ if isinstance(task_usage, dict):+ usage_dict = task_usage+ else:+ usage_dict = {+ "total_tokens": getattr(task_usage, "total_tokens", None),+ "tool_uses": getattr(task_usage, "tool_uses", None),+ "duration_ms": getattr(task_usage, "duration_ms", None),+ }+ if task_id and subagent_tracker:+ subagent_tracker.end_subagent(+ task_id, is_error, error_msg, usage=usage_dict+ )+ except Exception:+ pass++ chat_state["last_boundary_ns"] = time.time_ns()+ return result_usage+++# ---------------------------------------------------------------------------+# Message-based tool span fallback (when hooks cannot be injected)+# ---------------------------------------------------------------------------+def _process_tool_blocks_from_messages(message, tool_tracker, subagent_tracker=None):+ """Fallback: create/end tool spans by scanning content blocks.++ Skips tool_use_ids already handled by the hook system (tracked in+ ``tool_tracker._completed``) to avoid duplicate spans.++ When *subagent_tracker* is provided and the message has a+ ``parent_tool_use_id``, tool spans are parented under the subagent+ span instead of the root.+ """+ msg_type = type(message).__name__++ if msg_type == "AssistantMessage":+ content = getattr(message, "content", None)+ if not content:+ return++ parent_tool_use_id = getattr(message, "parent_tool_use_id", None)+ effective_parent = None+ if parent_tool_use_id and subagent_tracker:+ effective_parent = subagent_tracker.get_span_for_tool_use_id(+ parent_tool_use_id+ )++ for block in content:+ if type(block).__name__ == "ToolUseBlock":+ tool_name = getattr(block, "name", "unknown")+ tool_input = getattr(block, "input", None)+ tool_id = getattr(block, "id", None)+ if (+ tool_id+ and tool_id not in tool_tracker._in_flight+ and tool_id not in tool_tracker._completed+ ):+ if effective_parent:+ span_name = generate_span_name("execute_tool", tool_name)+ parent_ctx = trace_api.set_span_in_context(effective_parent)+ span = tool_tracker._tracer.start_span(+ span_name, kind=SpanKind.INTERNAL, context=parent_ctx+ )+ set_tool_span_attributes(+ span,+ tool_name,+ tool_input,+ tool_id,+ tool_tracker._capture_message_content,+ tool_tracker._environment,+ tool_tracker._application_name,+ tool_tracker._version,+ )+ tool_tracker._in_flight[tool_id] = span+ else:+ tool_tracker.start_tool(tool_name, tool_input, tool_id)++ elif msg_type == "UserMessage":+ content = getattr(message, "content", None)+ if not content or not isinstance(content, list):+ return+ for block in content:+ if type(block).__name__ == "ToolResultBlock":+ tool_use_id = getattr(block, "tool_use_id", None)+ is_error = getattr(block, "is_error", False)+ result_content = getattr(block, "content", None)+ if tool_use_id and tool_use_id in tool_tracker._in_flight:+ if is_error:+ tool_tracker.end_tool_error(tool_use_id, result_content)+ else:+ tool_tracker.end_tool(tool_use_id, result_content)+++# ---------------------------------------------------------------------------+# wrap_query — wraps the stateless query() async generator+# ---------------------------------------------------------------------------+def wrap_query(+ version,+ environment,+ application_name,+ tracer,+ pricing_info,+ capture_message_content,+ metrics,+ disable_metrics,+ event_provider=None,+):+ """Return a wrapt-compatible wrapper for ``claude_agent_sdk.query.query``."""++ async def wrapper(wrapped, instance, args, kwargs):+ if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):+ async for msg in wrapped(*args, **kwargs):+ yield msg+ return++ span_name = generate_span_name("query")+ span = tracer.start_span(span_name, kind=SpanKind.INTERNAL)+ ctx = trace_api.set_span_in_context(span)+ token = context_api.attach(ctx)+ start_time = time.time()+ chat_state = {"last_boundary_ns": time.time_ns()}++ tool_tracker = _ToolSpanTracker(+ tracer,+ span,+ version,+ environment,+ application_name,+ capture_message_content,+ )+ subagent_tracker = _SubagentSpanTracker(+ tracer,+ tool_tracker,+ version,+ environment,+ application_name,+ )+ aggregate_usage = {"input_tokens": 0, "output_tokens": 0}++ try:+ options, kwargs = _get_or_create_options(kwargs)+ prompt = kwargs.get("prompt")++ if prompt and capture_message_content:+ chat_state["pending_input"] = [+ {+ "role": "user",+ "parts": [{"type": "text", "content": str(prompt)}],+ }+ ]++ _inject_hooks(options, tool_tracker, subagent_tracker)++ set_initial_span_attributes(+ span,+ start_time,+ version,+ environment,+ application_name,+ options,+ prompt,+ capture_message_content,+ )++ has_result = False+ async for message in wrapped(*args, **kwargs):+ msg_usage = _process_message(+ message,+ span,+ tool_tracker,+ subagent_tracker,+ capture_message_content,+ tracer,+ chat_state,+ version,+ environment,+ application_name,+ pricing_info=pricing_info,+ event_provider=event_provider,+ )+ if msg_usage:+ aggregate_usage["input_tokens"] = msg_usage.get("input_tokens", 0)+ aggregate_usage["output_tokens"] = msg_usage.get("output_tokens", 0)+ _process_tool_blocks_from_messages(+ message, tool_tracker, subagent_tracker+ )++ if type(message).__name__ == "ResultMessage":+ has_result = True++ yield message++ _flush_pending_chat(+ tracer=tracer,+ parent_span=span,+ chat_state=chat_state,+ capture_message_content=capture_message_content,+ version=version,+ environment=environment,+ application_name=application_name,+ pricing_info=pricing_info,+ event_provider=event_provider,+ subagent_tracker=subagent_tracker,+ )++ if not has_result:+ span.set_status(Status(StatusCode.OK))++ except Exception as e:+ handle_exception(span, e)+ raise+ finally:+ subagent_tracker.end_all()+ tool_tracker.end_all()+ finalize_span(+ span,+ start_time,+ metrics,+ disable_metrics,+ environment,+ application_name,+ input_tokens=aggregate_usage["input_tokens"],+ output_tokens=aggregate_usage["output_tokens"],+ )+ span.end()+ context_api.detach(token)++ return wrapper+++# ---------------------------------------------------------------------------+# wrap_connect — captures initial prompt, emits create_agent, injects hooks+# ---------------------------------------------------------------------------+def wrap_connect(+ version,+ environment,+ application_name,+ tracer,+ pricing_info,+ capture_message_content,+ metrics,+ disable_metrics,+ event_provider=None,+):+ """Return a wrapt-compatible wrapper for ``ClaudeSDKClient.connect``."""++ async def wrapper(wrapped, instance, args, kwargs):+ try:+ prompt = kwargs.get("prompt") or (args[0] if args else None)+ setattr(instance, _PROMPT_ATTR, prompt)+ except Exception:+ pass++ span_name = generate_span_name("create_agent", "claude_agent_sdk")+ with tracer.start_as_current_span(span_name, kind=SpanKind.CLIENT) as span:+ set_create_agent_attributes(+ span,+ version,+ environment,+ application_name,+ )+ try:+ result = await wrapped(*args, **kwargs)+ span.set_status(Status(StatusCode.OK))+ return result+ except Exception as e:+ handle_exception(span, e)+ raise++ return wrapper+++# ---------------------------------------------------------------------------+# wrap_client_query — captures prompt for subsequent receive_response+# ---------------------------------------------------------------------------+def wrap_client_query(+ version,+ environment,+ application_name,+ tracer,+ pricing_info,+ capture_message_content,+ metrics,+ disable_metrics,+ event_provider=None,+):+ """Return a wrapt-compatible wrapper for ``ClaudeSDKClient.query``."""++ async def wrapper(wrapped, instance, args, kwargs):+ try:+ prompt = kwargs.get("prompt") or (args[0] if args else None)+ setattr(instance, _PROMPT_ATTR, prompt)+ except Exception:+ pass++ return await wrapped(*args, **kwargs)++ return wrapper+++# ---------------------------------------------------------------------------+# wrap_receive_response — wraps the per-turn async generator+# ---------------------------------------------------------------------------+def wrap_receive_response(+ version,+ environment,+ application_name,+ tracer,+ pricing_info,+ capture_message_content,+ metrics,+ disable_metrics,+ event_provider=None,+):+ """Return a wrapt-compatible wrapper for ``ClaudeSDKClient.receive_response``."""++ async def wrapper(wrapped, instance, args, kwargs):+ if context_api.get_value(context_api._SUPPRESS_INSTRUMENTATION_KEY):+ async for msg in wrapped(*args, **kwargs):+ yield msg+ return++ span_name = generate_span_name("receive_response")+ span = tracer.start_span(span_name, kind=SpanKind.INTERNAL)+ ctx = trace_api.set_span_in_context(span)+ token = context_api.attach(ctx)+ start_time = time.time()+ chat_state = {"last_boundary_ns": time.time_ns()}++ tool_tracker = _ToolSpanTracker(+ tracer,+ span,+ version,+ environment,+ application_name,+ capture_message_content,+ )+ subagent_tracker = _SubagentSpanTracker(+ tracer,+ tool_tracker,+ version,+ environment,+ application_name,+ )+ aggregate_usage = {"input_tokens": 0, "output_tokens": 0}++ try:+ prompt = getattr(instance, _PROMPT_ATTR, None)+ options = getattr(instance, "_options", None)++ if prompt and capture_message_content:+ chat_state["pending_input"] = [+ {+ "role": "user",+ "parts": [{"type": "text", "content": str(prompt)}],+ }+ ]++ if not getattr(instance, _HOOKS_INJECTED_ATTR, False):+ if options is not None:+ _inject_hooks(options, tool_tracker, subagent_tracker)+ setattr(instance, _HOOKS_INJECTED_ATTR, True)++ set_initial_span_attributes(+ span,+ start_time,+ version,+ environment,+ application_name,+ options,+ prompt,+ capture_message_content,+ )++ has_result = False+ async for message in wrapped(*args, **kwargs):+ msg_usage = _process_message(+ message,+ span,+ tool_tracker,+ subagent_tracker,+ capture_message_content,+ tracer,+ chat_state,+ version,+ environment,+ application_name,+ pricing_info=pricing_info,+ event_provider=event_provider,+ )+ if msg_usage:+ aggregate_usage["input_tokens"] = msg_usage.get("input_tokens", 0)+ aggregate_usage["output_tokens"] = msg_usage.get("output_tokens", 0)+ _process_tool_blocks_from_messages(+ message, tool_tracker, subagent_tracker+ )++ if type(message).__name__ == "ResultMessage":+ has_result = True++ yield message++ _flush_pending_chat(+ tracer=tracer,+ parent_span=span,+ chat_state=chat_state,+ capture_message_content=capture_message_content,+ version=version,+ environment=environment,+ application_name=application_name,+ pricing_info=pricing_info,+ event_provider=event_provider,+ subagent_tracker=subagent_tracker,+ )++ if not has_result:+ span.set_status(Status(StatusCode.OK))++ except Exception as e:+ handle_exception(span, e)+ raise+ finally:+ subagent_tracker.end_all()+ tool_tracker.end_all()+ finalize_span(+ span,+ start_time,+ metrics,+ disable_metrics,+ environment,+ application_name,+ input_tokens=aggregate_usage["input_tokens"],+ output_tokens=aggregate_usage["output_tokens"],+ )+ span.end()+ context_api.detach(token)++ return wrapperdiff --git a/sdk/python/src/openlit/instrumentation/claude_agent_sdk/utils.py b/sdk/python/src/openlit/instrumentation/claude_agent_sdk/utils.pynew file mode 100644index 00000000..ed439ce1--- /dev/null+++ b/sdk/python/src/openlit/instrumentation/claude_agent_sdk/utils.py@@ -0,0 +1,811 @@+"""+Claude Agent SDK utilities for OTel GenAI semantic convention compliant telemetry.++Follows the same patterns as the CrewAI / LangGraph / OpenAI Agents instrumentations.+All operation names, span kinds, and attributes comply with the OTel GenAI+semantic conventions (gen-ai-spans.md, gen-ai-agent-spans.md, gen-ai-events.md).+"""++import json+import logging+import time++from opentelemetry.trace import SpanKind, Status, StatusCode++from openlit.__helpers import (+ common_framework_span_attributes,+ get_chat_model_cost,+ handle_exception,+ otel_event,+ truncate_content,+)+from openlit.semcov import SemanticConvention++logger = logging.getLogger(__name__)++# ---------------------------------------------------------------------------+# OTel GenAI Operation Mapping+# ---------------------------------------------------------------------------+OPERATION_MAP = {+ "query": SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,+ "receive_response": SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,+ "execute_tool": SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS,+ "subagent": SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,+ "chat": SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,+ "create_agent": SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT,+}++# ---------------------------------------------------------------------------+# SpanKind per operation type (OTel GenAI spec)+# ---------------------------------------------------------------------------+SPAN_KIND_MAP = {+ SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT: SpanKind.INTERNAL,+ SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS: SpanKind.INTERNAL,+ SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT: SpanKind.CLIENT,+ SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT: SpanKind.CLIENT,+}++SERVER_ADDRESS = "api.anthropic.com"+SERVER_PORT = 443+GEN_AI_SYSTEM_ATTR = "gen_ai.system"+GEN_AI_SYSTEM_VALUE = "anthropic"++ANTHROPIC_FINISH_REASON_MAP = {+ "end_turn": "stop",+ "max_tokens": "length",+ "stop_sequence": "stop",+ "tool_use": "tool_call",+}+++def _map_finish_reason(raw_reason):+ """Map an Anthropic stop_reason to the OTel standard value."""+ if not raw_reason:+ return "stop"+ return ANTHROPIC_FINISH_REASON_MAP.get(str(raw_reason), str(raw_reason))+++def get_span_kind(operation_type):+ """Return the correct SpanKind for *operation_type* per OTel GenAI spec."""+ return SPAN_KIND_MAP.get(operation_type, SpanKind.INTERNAL)+++def generate_span_name(endpoint, entity_name=None):+ """Return an OTel-compliant span name: ``{operation} {entity}``."""+ operation = OPERATION_MAP.get(+ endpoint, SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT+ )++ if endpoint in ("execute_tool", "subagent", "chat", "create_agent") and entity_name:+ return f"{operation} {entity_name}"++ return f"{operation} claude_agent_sdk"+++# ---------------------------------------------------------------------------+# Message attribute extraction+# ---------------------------------------------------------------------------+def extract_usage(usage):+ """Extract token counts from a usage dict or object.++ Returns a dict with keys mapping to SemanticConvention constants.+ """+ attrs = {}+ if usage is None:+ return attrs++ if isinstance(usage, dict):+ get = usage.get+ else:++ def get(key, default=None):+ return getattr(usage, key, default)++ raw_input = get("input_tokens")+ try:+ raw_input = int(raw_input) if raw_input is not None else 0+ except (TypeError, ValueError):+ raw_input = 0++ output_tokens = get("output_tokens")+ if output_tokens is not None:+ try:+ attrs[SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS] = int(output_tokens)+ except (TypeError, ValueError):+ pass++ cache_read = get("cache_read_input_tokens")+ cache_read_int = 0+ if cache_read is not None:+ try:+ cache_read_int = int(cache_read)+ attrs[SemanticConvention.GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS] = (+ cache_read_int+ )+ except (TypeError, ValueError):+ pass++ cache_creation = get("cache_creation_input_tokens")+ if cache_creation is None:+ cache_creation = get("cache_write_input_tokens")+ cache_creation_int = 0+ if cache_creation is not None:+ try:+ cache_creation_int = int(cache_creation)+ attrs[SemanticConvention.GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS] = (+ cache_creation_int+ )+ except (TypeError, ValueError):+ pass++ total_input = raw_input + cache_read_int + cache_creation_int+ attrs[SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS] = total_input++ return attrs+++def update_root_from_assistant(span, message):+ """Update the root invoke_agent span with metadata from an AssistantMessage.++ Only sets model and session_id on the root span. Per-call usage and+ content go on chat child spans instead.+ """+ try:+ model = getattr(message, "model", None)+ if model:+ span.set_attribute(SemanticConvention.GEN_AI_REQUEST_MODEL, str(model))+ span.set_attribute(SemanticConvention.GEN_AI_RESPONSE_MODEL, str(model))++ session_id = getattr(message, "session_id", None)+ if session_id:+ span.set_attribute(+ SemanticConvention.GEN_AI_CONVERSATION_ID, str(session_id)+ )++ except Exception:+ pass+++def has_llm_call_data(message):+ """Return True if this AssistantMessage represents an actual LLM API call."""+ return (+ getattr(message, "model", None) is not None+ and getattr(message, "usage", None) is not None+ )+++def has_meaningful_content(content):+ """Return True if *content* has at least one non-empty TextBlock or ToolUseBlock.++ ThinkingBlocks and empty TextBlocks are NOT considered meaningful — the+ SDK often yields an initial AssistantMessage with only those before+ delivering the real content in a follow-up yield with the same+ ``message_id``.+ """+ if not content:+ return False+ for block in content:+ name = type(block).__name__+ if name == "ToolUseBlock":+ return True+ if name == "TextBlock" and getattr(block, "text", ""):+ return True+ return False+++def build_input_from_tool_results(message):+ """Build an OTel-compliant input_messages list from a UserMessage with tool results.++ Returns a list like::++ [{"role": "user", "parts": [{"type": "tool_call_response", "id": "...", "response": "..."}]}]++ Returns ``None`` if there are no tool result blocks.+ """+ content = getattr(message, "content", None)+ if not content or not isinstance(content, list):+ return None+ parts = []+ for block in content:+ if type(block).__name__ == "ToolResultBlock":+ tool_use_id = getattr(block, "tool_use_id", None)+ result_content = getattr(block, "content", None)+ parts.append(+ {+ "type": "tool_call_response",+ "id": str(tool_use_id) if tool_use_id else "",+ "response": truncate_content(str(result_content))+ if result_content+ else "",+ }+ )+ if not parts:+ return None+ return [{"role": "user", "parts": parts}]+++def set_chat_span_attributes(+ span,+ message,+ capture_message_content,+ environment,+ application_name,+ version,+ pricing_info=None,+ event_provider=None,+ input_messages=None,+):+ """Set OTel-compliant attributes on a chat child span.++ Chat spans represent the underlying Anthropic LLM API call, so+ ``gen_ai.provider.name`` is set to the OTel well-known value+ ``"anthropic"`` (not ``"claude_agent_sdk"``).+ """+ try:+ model = getattr(message, "model", None)+ model_str = str(model) if model else None++ span.set_attribute(+ SemanticConvention.GEN_AI_OPERATION,+ SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,+ )+ span.set_attribute(+ SemanticConvention.GEN_AI_PROVIDER_NAME,+ SemanticConvention.GEN_AI_SYSTEM_ANTHROPIC,+ )+ span.set_attribute(GEN_AI_SYSTEM_ATTR, GEN_AI_SYSTEM_VALUE)+ span.set_attribute(SemanticConvention.SERVER_ADDRESS, SERVER_ADDRESS)+ span.set_attribute(SemanticConvention.SERVER_PORT, SERVER_PORT)+ span.set_attribute(SemanticConvention.GEN_AI_ENVIRONMENT, environment)+ span.set_attribute(SemanticConvention.GEN_AI_APPLICATION_NAME, application_name)+ span.set_attribute(SemanticConvention.GEN_AI_SDK_VERSION, version)++ if model_str:+ span.set_attribute(SemanticConvention.GEN_AI_REQUEST_MODEL, model_str)+ span.set_attribute(SemanticConvention.GEN_AI_RESPONSE_MODEL, model_str)++ usage = getattr(message, "usage", None)+ usage_attrs = extract_usage(usage) if usage else {}+ for key, value in usage_attrs.items():+ span.set_attribute(key, value)++ stop_reason = getattr(message, "stop_reason", None)+ if not stop_reason:+ content_blocks = getattr(message, "content", None)+ if content_blocks:+ for block in content_blocks:+ if type(block).__name__ == "ToolUseBlock":+ stop_reason = "tool_use"+ break+ mapped_reason = _map_finish_reason(stop_reason)+ span.set_attribute(+ SemanticConvention.GEN_AI_RESPONSE_FINISH_REASON, [mapped_reason]+ )++ message_id = getattr(message, "message_id", None)+ if message_id:+ span.set_attribute(SemanticConvention.GEN_AI_RESPONSE_ID, str(message_id))++ session_id = getattr(message, "session_id", None)+ if session_id:+ span.set_attribute(+ SemanticConvention.GEN_AI_CONVERSATION_ID, str(session_id)+ )++ input_tokens = usage_attrs.get(SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS, 0)+ output_tokens = usage_attrs.get(+ SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS, 0+ )+ cost = _calculate_cost(model_str, pricing_info, input_tokens, output_tokens)+ span.set_attribute(SemanticConvention.GEN_AI_USAGE_COST, cost)++ output_messages = None+ if capture_message_content:+ if input_messages:+ span.set_attribute(+ SemanticConvention.GEN_AI_INPUT_MESSAGES,+ json.dumps(input_messages),+ )++ output_messages = _build_output_messages(message, mapped_reason)+ if output_messages:+ span.set_attribute(+ SemanticConvention.GEN_AI_OUTPUT_MESSAGES,+ json.dumps(output_messages),+ )++ span.set_status(Status(StatusCode.OK))++ if event_provider and capture_message_content:+ _emit_chat_inference_event(+ event_provider,+ model_str,+ message_id,+ session_id,+ mapped_reason,+ usage_attrs,+ input_messages,+ output_messages,+ )++ except Exception:+ pass+++def _build_output_messages(message, mapped_finish_reason):+ """Build OTel-compliant output messages from assistant content blocks.++ Returns a list following the gen-ai-output-messages JSON schema::++ [{"role": "assistant",+ "parts": [{"type": "text", "content": "..."},+ {"type": "tool_call", "id": "...", "name": "...", "arguments": {...}}],+ "finish_reason": "stop"}]++ Returns ``None`` if there is no content.+ """+ try:+ content = getattr(message, "content", None)+ if not content:+ return None++ parts = []+ for block in content:+ block_type = type(block).__name__+ if block_type == "TextBlock":+ text = getattr(block, "text", None)+ if text:+ parts.append(+ {+ "type": "text",+ "content": truncate_content(str(text)),+ }+ )+ elif block_type == "ThinkingBlock":+ thinking = getattr(block, "thinking", None)+ if thinking:+ parts.append(+ {+ "type": "reasoning",+ "content": truncate_content(str(thinking)),+ }+ )+ elif block_type == "ToolUseBlock":+ tool_name = getattr(block, "name", "unknown")+ tool_input = getattr(block, "input", {})+ tool_id = getattr(block, "id", "")+ if not isinstance(tool_input, dict):+ try:+ tool_input = json.loads(str(tool_input))+ except (TypeError, ValueError, json.JSONDecodeError):+ tool_input = {}+ parts.append(+ {+ "type": "tool_call",+ "id": str(tool_id),+ "name": str(tool_name),+ "arguments": tool_input,+ }+ )++ if not parts:+ return None++ return [+ {+ "role": "assistant",+ "parts": parts,+ "finish_reason": mapped_finish_reason,+ }+ ]+ except Exception:+ return None+++def _calculate_cost(model_str, pricing_info, input_tokens, output_tokens):+ """Estimate cost using the shared OpenLIT pricing helper."""+ if not pricing_info or not model_str:+ return 0+ return get_chat_model_cost(model_str, pricing_info, input_tokens, output_tokens)+++def _emit_chat_inference_event(+ event_provider,+ model_str,+ message_id,+ session_id,+ mapped_reason,+ usage_attrs,+ input_messages,+ output_messages,+):+ """Emit ``gen_ai.client.inference.operation.details`` log event for a chat span."""+ try:+ if not event_provider:+ return++ attributes = {+ SemanticConvention.GEN_AI_OPERATION: SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT,+ SemanticConvention.SERVER_ADDRESS: SERVER_ADDRESS,+ SemanticConvention.SERVER_PORT: SERVER_PORT,+ }++ if model_str:+ attributes[SemanticConvention.GEN_AI_REQUEST_MODEL] = model_str+ attributes[SemanticConvention.GEN_AI_RESPONSE_MODEL] = model_str+ if message_id:+ attributes[SemanticConvention.GEN_AI_RESPONSE_ID] = str(message_id)+ if session_id:+ attributes[SemanticConvention.GEN_AI_CONVERSATION_ID] = str(session_id)+ if mapped_reason:+ attributes[SemanticConvention.GEN_AI_RESPONSE_FINISH_REASON] = [+ mapped_reason+ ]++ for key, value in usage_attrs.items():+ attributes[key] = value++ if input_messages is not None:+ attributes[SemanticConvention.GEN_AI_INPUT_MESSAGES] = input_messages+ if output_messages is not None:+ attributes[SemanticConvention.GEN_AI_OUTPUT_MESSAGES] = output_messages++ event = otel_event(+ name=SemanticConvention.GEN_AI_CLIENT_INFERENCE_OPERATION_DETAILS,+ attributes=attributes,+ body="",+ )+ event_provider.emit(event)++ except Exception as exc:+ logger.debug("Failed to emit chat inference event: %s", exc)+++def process_result_message(span, message, capture_message_content):+ """Set span attributes from a ResultMessage (final result).++ Returns a dict with ``input_tokens`` and ``output_tokens`` for metrics.+ """+ result_usage = {"input_tokens": 0, "output_tokens": 0}+ try:+ session_id = getattr(message, "session_id", None)+ if session_id:+ span.set_attribute(+ SemanticConvention.GEN_AI_CONVERSATION_ID, str(session_id)+ )++ usage = getattr(message, "usage", None)+ if usage:+ usage_attrs = extract_usage(usage)+ for key, value in usage_attrs.items():+ span.set_attribute(key, value)+ result_usage["input_tokens"] = usage_attrs.get(+ SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS, 0+ )+ result_usage["output_tokens"] = usage_attrs.get(+ SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS, 0+ )++ cost = getattr(message, "total_cost_usd", None)+ if cost is not None:+ try:+ span.set_attribute(SemanticConvention.GEN_AI_USAGE_COST, float(cost))+ except (TypeError, ValueError):+ pass++ model_usage = getattr(message, "model_usage", None)+ if model_usage and isinstance(model_usage, dict):+ for model_name in model_usage:+ span.set_attribute(+ SemanticConvention.GEN_AI_RESPONSE_MODEL, str(model_name)+ )+ break++ num_turns = getattr(message, "num_turns", None)+ if num_turns is not None:+ try:+ span.set_attribute("gen_ai.agent.num_turns", int(num_turns))+ except (TypeError, ValueError):+ pass++ duration_ms = getattr(message, "duration_ms", None)+ if duration_ms is not None:+ try:+ span.set_attribute("gen_ai.agent.duration_ms", int(duration_ms))+ except (TypeError, ValueError):+ pass++ duration_api_ms = getattr(message, "duration_api_ms", None)+ if duration_api_ms is not None:+ try:+ span.set_attribute("gen_ai.agent.duration_api_ms", int(duration_api_ms))+ except (TypeError, ValueError):+ pass++ is_error = getattr(message, "is_error", False)+ if is_error:+ error_result = getattr(message, "result", None)+ error_msg = str(error_result) if error_result else "unknown error"+ span.set_attribute(SemanticConvention.ERROR_TYPE, error_msg)+ span.set_status(Status(StatusCode.ERROR, error_msg))+ else:+ span.set_status(Status(StatusCode.OK))++ if capture_message_content:+ result = getattr(message, "result", None)+ if result:+ span.set_attribute(+ SemanticConvention.GEN_AI_OUTPUT_MESSAGES,+ json.dumps(+ [+ {+ "role": "assistant",+ "parts": [+ {+ "type": "text",+ "content": truncate_content(str(result)),+ }+ ],+ }+ ]+ ),+ )+ except Exception:+ pass++ return result_usage+++def set_create_agent_attributes(span, version, environment, application_name):+ """Set OTel-compliant attributes on a create_agent span."""+ try:+ span.set_attribute(+ SemanticConvention.GEN_AI_OPERATION,+ SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT,+ )+ span.set_attribute(+ SemanticConvention.GEN_AI_PROVIDER_NAME,+ SemanticConvention.GEN_AI_SYSTEM_CLAUDE_AGENT_SDK,+ )+ span.set_attribute(GEN_AI_SYSTEM_ATTR, GEN_AI_SYSTEM_VALUE)+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_NAME, "claude_agent_sdk")+ span.set_attribute(SemanticConvention.SERVER_ADDRESS, SERVER_ADDRESS)+ span.set_attribute(SemanticConvention.SERVER_PORT, SERVER_PORT)+ span.set_attribute(SemanticConvention.GEN_AI_ENVIRONMENT, environment)+ span.set_attribute(SemanticConvention.GEN_AI_APPLICATION_NAME, application_name)+ span.set_attribute(SemanticConvention.GEN_AI_SDK_VERSION, version)+ except Exception:+ pass+++def set_initial_span_attributes(+ span,+ start_time,+ version,+ environment,+ application_name,+ options=None,+ prompt=None,+ capture_message_content=False,+):+ """Set the initial common attributes on an agent span at creation time."""+ try:+ scope = type("Scope", (), {})()+ scope._span = span+ scope._start_time = start_time+ scope._end_time = start_time++ model = None+ if options is not None:+ model = getattr(options, "model", None)++ model_proxy = type("P", (), {"model_name": str(model)})() if model else None++ common_framework_span_attributes(+ scope,+ SemanticConvention.GEN_AI_SYSTEM_CLAUDE_AGENT_SDK,+ SERVER_ADDRESS,+ SERVER_PORT,+ environment,+ application_name,+ version,+ SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,+ model_proxy,+ )++ span.set_attribute(+ SemanticConvention.GEN_AI_OPERATION,+ SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,+ )+ span.set_attribute(+ SemanticConvention.GEN_AI_PROVIDER_NAME,+ SemanticConvention.GEN_AI_SYSTEM_CLAUDE_AGENT_SDK,+ )+ span.set_attribute(GEN_AI_SYSTEM_ATTR, GEN_AI_SYSTEM_VALUE)+ span.set_attribute(SemanticConvention.GEN_AI_AGENT_NAME, "claude_agent_sdk")++ if model:+ span.set_attribute(SemanticConvention.GEN_AI_REQUEST_MODEL, str(model))++ if capture_message_content:+ if options is not None:+ system_prompt = getattr(options, "system_prompt", None)+ if system_prompt and isinstance(system_prompt, str):+ span.set_attribute(+ SemanticConvention.GEN_AI_SYSTEM_INSTRUCTIONS,+ json.dumps(+ [+ {+ "type": "text",+ "content": truncate_content(str(system_prompt)),+ }+ ]+ ),+ )++ if prompt and isinstance(prompt, str):+ span.set_attribute(+ SemanticConvention.GEN_AI_INPUT_MESSAGES,+ json.dumps(+ [+ {+ "role": "user",+ "parts": [+ {+ "type": "text",+ "content": truncate_content(str(prompt)),+ }+ ],+ }+ ]+ ),+ )++ except Exception as e:+ handle_exception(span, e)+++def finalize_span(+ span,+ start_time,+ metrics,+ disable_metrics,+ environment,+ application_name,+ input_tokens=0,+ output_tokens=0,+):+ """Record duration and token usage metrics and finalize an agent span."""+ try:+ end_time = time.time()+ duration = end_time - start_time++ span.set_attribute(+ SemanticConvention.GEN_AI_CLIENT_OPERATION_DURATION, duration+ )++ if not disable_metrics and metrics:+ _record_metrics(+ metrics,+ SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,+ duration,+ environment,+ application_name,+ input_tokens=input_tokens,+ output_tokens=output_tokens,+ )+ except Exception:+ pass+++def set_tool_span_attributes(+ span,+ tool_name,+ tool_input,+ tool_use_id,+ capture_message_content,+ environment,+ application_name,+ version,+):+ """Set OTel-compliant attributes on an execute_tool span."""+ try:+ span.set_attribute(+ SemanticConvention.GEN_AI_OPERATION,+ SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS,+ )+ span.set_attribute(+ SemanticConvention.GEN_AI_PROVIDER_NAME,+ SemanticConvention.GEN_AI_SYSTEM_CLAUDE_AGENT_SDK,+ )+ span.set_attribute(GEN_AI_SYSTEM_ATTR, GEN_AI_SYSTEM_VALUE)+ span.set_attribute(SemanticConvention.GEN_AI_TOOL_NAME, str(tool_name))+ tool_type = "extension" if str(tool_name).startswith("mcp__") else "function"+ span.set_attribute(SemanticConvention.GEN_AI_TOOL_TYPE, tool_type)++ if tool_use_id:+ span.set_attribute(SemanticConvention.GEN_AI_TOOL_CALL_ID, str(tool_use_id))++ span.set_attribute(SemanticConvention.SERVER_ADDRESS, SERVER_ADDRESS)+ span.set_attribute(SemanticConvention.SERVER_PORT, SERVER_PORT)+ span.set_attribute(SemanticConvention.GEN_AI_ENVIRONMENT, environment)+ span.set_attribute(SemanticConvention.GEN_AI_APPLICATION_NAME, application_name)+ span.set_attribute(SemanticConvention.GEN_AI_SDK_VERSION, version)++ if capture_message_content and tool_input is not None:+ try:+ args_str = json.dumps(tool_input)+ except (TypeError, ValueError):+ args_str = str(tool_input)+ span.set_attribute(+ SemanticConvention.GEN_AI_TOOL_CALL_ARGUMENTS,+ truncate_content(args_str),+ )+ except Exception:+ pass+++def finalize_tool_span(+ span, tool_response, capture_message_content, is_error=False, error_message=None+):+ """Finalize an execute_tool span with result or error."""+ try:+ if is_error:+ err_msg = str(error_message) if error_message else "tool execution failed"+ span.set_attribute(SemanticConvention.ERROR_TYPE, err_msg)+ span.set_status(Status(StatusCode.ERROR, err_msg))+ else:+ if capture_message_content and tool_response is not None:+ span.set_attribute(+ SemanticConvention.GEN_AI_TOOL_CALL_RESULT,+ truncate_content(str(tool_response)),+ )+ span.set_status(Status(StatusCode.OK))+ except Exception:+ pass+++# ---------------------------------------------------------------------------+# Metrics+# ---------------------------------------------------------------------------+def _record_metrics(+ metrics,+ operation_type,+ duration,+ environment,+ application_name,+ input_tokens=0,+ output_tokens=0,+):+ """Record OTel-compliant metrics with correct attribute keys."""+ try:+ attributes = {+ SemanticConvention.GEN_AI_OPERATION: operation_type,+ SemanticConvention.GEN_AI_PROVIDER_NAME: (+ SemanticConvention.GEN_AI_SYSTEM_CLAUDE_AGENT_SDK+ ),+ GEN_AI_SYSTEM_ATTR: GEN_AI_SYSTEM_VALUE,+ "service.name": application_name,+ "deployment.environment": environment,+ SemanticConvention.SERVER_ADDRESS: SERVER_ADDRESS,+ SemanticConvention.SERVER_PORT: SERVER_PORT,+ }++ if "genai_client_operation_duration" in metrics:+ metrics["genai_client_operation_duration"].record(duration, attributes)++ if "genai_client_usage_tokens" in metrics:+ if input_tokens:+ input_attrs = {+ **attributes,+ SemanticConvention.GEN_AI_TOKEN_TYPE: SemanticConvention.GEN_AI_TOKEN_TYPE_INPUT,+ }+ metrics["genai_client_usage_tokens"].record(input_tokens, input_attrs)+ if output_tokens:+ output_attrs = {+ **attributes,+ SemanticConvention.GEN_AI_TOKEN_TYPE: SemanticConvention.GEN_AI_TOKEN_TYPE_OUTPUT,+ }+ metrics["genai_client_usage_tokens"].record(output_tokens, output_attrs)+ except Exception:+ passdiff --git a/sdk/python/src/openlit/instrumentation/openai/async_openai.py b/sdk/python/src/openlit/instrumentation/openai/async_openai.pyindex 1466b41c..b0edf3f8 100644--- a/sdk/python/src/openlit/instrumentation/openai/async_openai.py+++ b/sdk/python/src/openlit/instrumentation/openai/async_openai.py@@ -3,6 +3,7 @@ Module for monitoring OpenAI API calls."""import time+from opentelemetry import trace as trace_api, context as context_apifrom opentelemetry.trace import SpanKindfrom openlit.__helpers import (handle_exception,@@ -129,8 +130,17 @@ def async_chat_completions(span_name = f"{SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT} {request_model}"if streaming:- awaited_wrapped = await wrapped(*args, **kwargs)span = tracer.start_span(span_name, kind=SpanKind.CLIENT)+ ctx = trace_api.set_span_in_context(span)+ token = context_api.attach(ctx)+ try:+ awaited_wrapped = await wrapped(*args, **kwargs)+ except Exception as e:+ handle_exception(span, e)+ context_api.detach(token)+ span.end()+ raise+ context_api.detach(token)return TracedAsyncStream(awaited_wrapped,@@ -299,8 +309,17 @@ def async_responses(span_name = f"{SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT} {request_model}"if streaming:- awaited_wrapped = await wrapped(*args, **kwargs)span = tracer.start_span(span_name, kind=SpanKind.CLIENT)+ ctx = trace_api.set_span_in_context(span)+ token = context_api.attach(ctx)+ try:+ awaited_wrapped = await wrapped(*args, **kwargs)+ except Exception as e:+ handle_exception(span, e)+ context_api.detach(token)+ span.end()+ raise+ context_api.detach(token)return TracedAsyncStream(awaited_wrapped,diff --git a/sdk/python/src/openlit/instrumentation/openai/openai.py b/sdk/python/src/openlit/instrumentation/openai/openai.pyindex 4e24be5a..aa6cc9d1 100644--- a/sdk/python/src/openlit/instrumentation/openai/openai.py+++ b/sdk/python/src/openlit/instrumentation/openai/openai.py@@ -3,6 +3,7 @@ Module for monitoring OpenAI API calls."""import time+from opentelemetry import trace as trace_api, context as context_apifrom opentelemetry.trace import SpanKindfrom openlit.__helpers import (handle_exception,@@ -129,8 +130,17 @@ def chat_completions(span_name = f"{SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT} {request_model}"if streaming:- awaited_wrapped = wrapped(*args, **kwargs)span = tracer.start_span(span_name, kind=SpanKind.CLIENT)+ ctx = trace_api.set_span_in_context(span)+ token = context_api.attach(ctx)+ try:+ awaited_wrapped = wrapped(*args, **kwargs)+ except Exception as e:+ handle_exception(span, e)+ context_api.detach(token)+ span.end()+ raise+ context_api.detach(token)return TracedSyncStream(awaited_wrapped,@@ -301,8 +311,17 @@ def responses(span_name = f"{SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT} {request_model}"if streaming:- awaited_wrapped = wrapped(*args, **kwargs)span = tracer.start_span(span_name, kind=SpanKind.CLIENT)+ ctx = trace_api.set_span_in_context(span)+ token = context_api.attach(ctx)+ try:+ awaited_wrapped = wrapped(*args, **kwargs)+ except Exception as e:+ handle_exception(span, e)+ context_api.detach(token)+ span.end()+ raise+ context_api.detach(token)return TracedSyncStream(awaited_wrapped,diff --git a/sdk/python/src/openlit/instrumentation/openai/utils.py b/sdk/python/src/openlit/instrumentation/openai/utils.pyindex 7d0499c2..04d257c5 100644--- a/sdk/python/src/openlit/instrumentation/openai/utils.py+++ b/sdk/python/src/openlit/instrumentation/openai/utils.py@@ -290,15 +290,31 @@ def build_output_messages(response_text, finish_reason, tool_calls=None):if isinstance(tool_calls, list):for tool_call in tool_calls:try:- # Extract tool call data+ # Extract tool call data -- OpenAI nests name/arguments+ # under a "function" key; fall back to top-level keys for+ # other providers that use a flat structure.if isinstance(tool_call, dict):+ func = tool_call.get("function", {})tool_id = tool_call.get("id", "")- tool_name = tool_call.get("name", "")- tool_args = tool_call.get("arguments", {})+ tool_name = func.get("name", "") or tool_call.get(+ "name", ""+ )+ tool_args = func.get("arguments", "") or tool_call.get(+ "arguments", {}+ )else:+ func = getattr(tool_call, "function", None)tool_id = getattr(tool_call, "id", "")- tool_name = getattr(tool_call, "name", "")- tool_args = getattr(tool_call, "arguments", {})+ tool_name = (+ getattr(func, "name", "")+ if func+ else getattr(tool_call, "name", "")+ )+ tool_args = (+ getattr(func, "arguments", "")+ if func+ else getattr(tool_call, "arguments", {})+ )# Parse arguments if it's a stringif isinstance(tool_args, str):@@ -646,7 +662,15 @@ def process_chat_chunk(scope, chunk):chunked.get("choices", [])[0].get("finish_reason") or scope._finish_reason)except (IndexError, AttributeError, TypeError):- scope._finish_reason = "stop"+ pass++ # Extract token usage from the final streaming chunk (sent when+ # stream_options={"include_usage": True}). The usage chunk typically+ # has an empty choices list, so this must run outside the choices block.+ usage = chunked.get("usage")+ if usage:+ scope._input_tokens = usage.get("prompt_tokens", 0)+ scope._output_tokens = usage.get("completion_tokens", 0)scope._system_fingerprint = (chunked.get("system_fingerprint") or scope._system_fingerprint@@ -1223,18 +1247,22 @@ def common_chat_logic(SemanticConvention.GEN_AI_REQUEST_FREQUENCY_PENALTY,handle_not_given(scope._kwargs.get("frequency_penalty"), 0.0),)- scope._span.set_attribute(- SemanticConvention.GEN_AI_REQUEST_MAX_TOKENS,- handle_not_given(scope._kwargs.get("max_tokens"), -1),- )+ max_tokens = handle_not_given(scope._kwargs.get("max_tokens"))+ if max_tokens is not None:+ scope._span.set_attribute(+ SemanticConvention.GEN_AI_REQUEST_MAX_TOKENS,+ max_tokens,+ )scope._span.set_attribute(SemanticConvention.GEN_AI_REQUEST_PRESENCE_PENALTY,handle_not_given(scope._kwargs.get("presence_penalty"), 0.0),)- scope._span.set_attribute(- SemanticConvention.GEN_AI_REQUEST_STOP_SEQUENCES,- handle_not_given(scope._kwargs.get("stop"), []),- )+ stop_sequences = handle_not_given(scope._kwargs.get("stop"))+ if stop_sequences:+ scope._span.set_attribute(+ SemanticConvention.GEN_AI_REQUEST_STOP_SEQUENCES,+ stop_sequences,+ )scope._span.set_attribute(SemanticConvention.GEN_AI_REQUEST_TEMPERATURE,handle_not_given(scope._kwargs.get("temperature"), 1.0),@@ -1371,7 +1399,7 @@ def common_chat_logic("temperature": handle_not_given(scope._kwargs.get("temperature"), 1.0),- "max_tokens": handle_not_given(scope._kwargs.get("max_tokens"), -1),+ "max_tokens": handle_not_given(scope._kwargs.get("max_tokens")),"top_p": handle_not_given(scope._kwargs.get("top_p"), 1.0),"frequency_penalty": handle_not_given(scope._kwargs.get("frequency_penalty"), 0.0@@ -1379,7 +1407,7 @@ def common_chat_logic("presence_penalty": handle_not_given(scope._kwargs.get("presence_penalty"), 0.0),- "stop_sequences": handle_not_given(scope._kwargs.get("stop"), []),+ "stop_sequences": handle_not_given(scope._kwargs.get("stop")),"seed": int(handle_not_given(scope._kwargs.get("seed"), 0))if handle_not_given(scope._kwargs.get("seed"))else None,diff --git a/sdk/python/src/openlit/semcov/__init__.py b/sdk/python/src/openlit/semcov/__init__.pyindex 359db518..004b4c59 100644--- a/sdk/python/src/openlit/semcov/__init__.py+++ b/sdk/python/src/openlit/semcov/__init__.py@@ -358,6 +358,8 @@ class SemanticConvention:GEN_AI_SYSTEM_BROWSER_USE = "browser_use"GEN_AI_SYSTEM_LANGGRAPH = "langgraph"GEN_AI_SYSTEM_GOOGLE_ADK = "google_adk"+ GEN_AI_SYSTEM_CLAUDE_AGENT_SDK = "claude_agent_sdk"+ GEN_AI_SYSTEM_AGENT_FRAMEWORK = "agent_framework"# Graph Execution Attributes (framework-agnostic, usable across LangGraph, CrewAI, etc.)GEN_AI_GRAPH_NODES = "gen_ai.graph.nodes"diff --git a/sdk/python/tests/test_agent_framework.py b/sdk/python/tests/test_agent_framework.pynew file mode 100644index 00000000..2e8af706--- /dev/null+++ b/sdk/python/tests/test_agent_framework.py@@ -0,0 +1,1127 @@+# pylint: disable=duplicate-code, no-member, too-few-public-methods, missing-class-docstring, missing-function-docstring+"""+Tests for Microsoft Agent Framework instrumentation.++Tests cover:+- Instrumentor import and basic instantiation+- Utils: OPERATION_MAP, SPAN_KIND_MAP, generate_span_name+- Agent creation registry+- Model name extraction+- Server info resolution+- Response attribute extraction+- Content capture (input/output messages, system instructions, tool defs)+- Tool attribute setting+- Metrics recording+- Process response++Note: These tests do NOT require agent-framework to be installed -- they mock+all AF internals so the test suite can run in any environment.+"""++import json+from unittest.mock import MagicMock++import pytest++from opentelemetry.trace import SpanKind++from openlit.instrumentation.agent_framework.utils import (+ OPERATION_MAP,+ SPAN_KIND_MAP,+ generate_span_name,+ get_operation_type,+ get_span_kind,+ _extract_model_name,+ _resolve_server_info,+ _set_agent_attributes,+ _set_workflow_attributes,+ _set_tool_attributes,+ _extract_response_attributes,+ _capture_input_messages,+ _capture_output_messages,+ _capture_system_instructions,+ _capture_tool_definitions,+ _record_metrics,+ process_agent_framework_response,+)+from openlit.instrumentation.agent_framework import (+ _AgentCreationRegistry,+ _wrap_agent_init,+ AgentFrameworkInstrumentor,+ WORKFLOW_OPERATIONS,+ DETAILED_OPERATIONS,+)+from openlit.instrumentation.agent_framework.async_agent_framework import (+ tool_execute_wrap,+ _serialize_content_list,+)+from openlit.semcov import SemanticConvention+++# ===================================================================+# OPERATION_MAP and SPAN_KIND_MAP+# ===================================================================+class TestOperationMap:+ """Tests for OPERATION_MAP and SPAN_KIND_MAP completeness."""++ def test_operation_map_has_required_endpoints(self):+ required = ["agent_init", "agent_run", "tool_execute", "workflow_run"]+ for key in required:+ assert key in OPERATION_MAP, f"Missing endpoint: {key}"++ def test_span_kind_map_has_required_operations(self):+ required = [+ SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT,+ SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,+ SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK,+ SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS,+ ]+ for key in required:+ assert key in SPAN_KIND_MAP, f"Missing span kind: {key}"++ def test_get_operation_type_defaults(self):+ assert (+ get_operation_type("agent_init")+ == SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT+ )+ assert (+ get_operation_type("unknown_key")+ == SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT+ )++ def test_agent_run_maps_to_invoke_agent(self):+ assert (+ OPERATION_MAP["agent_run"]+ == SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT+ )++ def test_workflow_run_maps_to_invoke_workflow(self):+ assert (+ OPERATION_MAP["workflow_run"]+ == SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK+ )++ def test_tool_execute_maps_to_execute_tool(self):+ assert (+ OPERATION_MAP["tool_execute"]+ == SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS+ )++ def test_create_agent_span_kind_is_client(self):+ assert (+ get_span_kind(SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT)+ == SpanKind.CLIENT+ )++ def test_invoke_agent_span_kind_is_internal(self):+ assert (+ get_span_kind(SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT)+ == SpanKind.INTERNAL+ )+++# ===================================================================+# Span Name Generation+# ===================================================================+class TestSpanNameGeneration:+ """Tests for generate_span_name."""++ def test_agent_init_span_name(self):+ instance = MagicMock()+ instance.name = "my_agent"+ assert generate_span_name("agent_init", instance) == "create_agent my_agent"++ def test_agent_init_fallback_to_id(self):+ instance = MagicMock(spec=["id"])+ instance.id = "agent-123"+ assert generate_span_name("agent_init", instance) == "create_agent agent-123"++ def test_agent_init_fallback_default(self):+ instance = MagicMock(spec=[])+ assert generate_span_name("agent_init", instance) == "create_agent agent"++ def test_agent_run_span_name(self):+ instance = MagicMock()+ instance.name = "weather_agent"+ assert (+ generate_span_name("agent_run", instance) == "invoke_agent weather_agent"+ )++ def test_agent_run_fallback_to_id(self):+ instance = MagicMock(spec=["id"])+ instance.id = "run-456"+ assert generate_span_name("agent_run", instance) == "invoke_agent run-456"++ def test_tool_execute_span_name(self):+ instance = MagicMock()+ instance.name = "get_weather"+ assert (+ generate_span_name("tool_execute", instance) == "execute_tool get_weather"+ )++ def test_tool_execute_fallback_to_class_name(self):+ instance = MagicMock(spec=[])+ name = generate_span_name("tool_execute", instance)+ assert "execute_tool" in name++ def test_workflow_run_span_name(self):+ instance = MagicMock()+ instance.name = "my_workflow"+ assert (+ generate_span_name("workflow_run", instance)+ == "invoke_workflow my_workflow"+ )++ def test_unknown_endpoint_uses_operation_type(self):+ instance = MagicMock(spec=[])+ name = generate_span_name("something_new", instance)+ assert SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT in name+++# ===================================================================+# Agent Creation Registry+# ===================================================================+class TestAgentCreationRegistry:+ """Tests for _AgentCreationRegistry."""++ def test_register_and_get(self):+ registry = _AgentCreationRegistry()+ ctx = MagicMock()+ registry.register("agent1", ctx)+ assert registry.get("agent1") is ctx++ def test_get_nonexistent_returns_none(self):+ registry = _AgentCreationRegistry()+ assert registry.get("missing") is None++ def test_get_all(self):+ registry = _AgentCreationRegistry()+ ctx1 = MagicMock()+ ctx2 = MagicMock()+ registry.register("a", ctx1)+ registry.register("b", ctx2)+ all_ctxs = registry.get_all()+ assert len(all_ctxs) == 2+ assert ctx1 in all_ctxs+ assert ctx2 in all_ctxs++ def test_overwrite_existing(self):+ registry = _AgentCreationRegistry()+ ctx1 = MagicMock()+ ctx2 = MagicMock()+ registry.register("agent1", ctx1)+ registry.register("agent1", ctx2)+ assert registry.get("agent1") is ctx2+++# ===================================================================+# Model Name Extraction+# ===================================================================+class TestModelExtraction:+ """Tests for _extract_model_name."""++ def test_direct_model_id(self):+ instance = MagicMock()+ instance.model_id = "gpt-4o"+ assert _extract_model_name(instance) == "gpt-4o"++ def test_chat_client_model_id(self):+ instance = MagicMock(spec=["chat_client"])+ instance.chat_client = MagicMock()+ instance.chat_client.model_id = "gpt-4"+ assert _extract_model_name(instance) == "gpt-4"++ def test_default_options_model_id(self):+ instance = MagicMock(spec=["default_options"])+ instance.default_options = {"model_id": "claude-sonnet-4-20250514"}+ assert _extract_model_name(instance) == "claude-sonnet-4-20250514"++ def test_unknown_fallback(self):+ instance = MagicMock(spec=[])+ assert _extract_model_name(instance) == "unknown"++ def test_none_instance(self):+ assert _extract_model_name(None) == "unknown"+++# ===================================================================+# Server Info Resolution+# ===================================================================+class TestServerInfoResolution:+ """Tests for _resolve_server_info."""++ def test_with_service_url(self):+ instance = MagicMock()+ instance.chat_client = MagicMock()+ instance.chat_client.service_url = MagicMock(+ return_value="https://api.openai.com:443/v1"+ )+ addr, port = _resolve_server_info(instance)+ assert addr == "api.openai.com"+ assert port == 443++ def test_no_chat_client(self):+ instance = MagicMock(spec=[])+ addr, port = _resolve_server_info(instance)+ assert addr == ""+ assert port == 0++ def test_unknown_service_url(self):+ instance = MagicMock()+ instance.chat_client = MagicMock()+ instance.chat_client.service_url = MagicMock(return_value="unknown")+ addr, port = _resolve_server_info(instance)+ assert addr == ""+ assert port == 0+++# ===================================================================+# Agent Attributes+# ===================================================================+class TestAgentAttributes:+ """Tests for _set_agent_attributes."""++ def test_sets_all_attributes(self):+ span = MagicMock()+ instance = MagicMock()+ instance.id = "agent-abc"+ instance.name = "WeatherBot"+ instance.description = "A bot that gets weather"++ _set_agent_attributes(span, instance)++ span.set_attribute.assert_any_call(+ SemanticConvention.GEN_AI_AGENT_ID, "agent-abc"+ )+ span.set_attribute.assert_any_call(+ SemanticConvention.GEN_AI_AGENT_NAME, "WeatherBot"+ )+ span.set_attribute.assert_any_call(+ SemanticConvention.GEN_AI_AGENT_DESCRIPTION, "A bot that gets weather"+ )++ def test_name_falls_back_to_id(self):+ span = MagicMock()+ instance = MagicMock()+ instance.id = "agent-xyz"+ instance.name = None+ instance.description = None++ _set_agent_attributes(span, instance)++ span.set_attribute.assert_any_call(+ SemanticConvention.GEN_AI_AGENT_NAME, "agent-xyz"+ )+++# ===================================================================+# Workflow Attributes+# ===================================================================+class TestWorkflowAttributes:+ """Tests for _set_workflow_attributes."""++ def test_sets_workflow_name(self):+ span = MagicMock()+ instance = MagicMock()+ instance.name = "my_pipeline"++ _set_workflow_attributes(span, instance)++ span.set_attribute.assert_any_call(+ SemanticConvention.GEN_AI_WORKFLOW_NAME, "my_pipeline"+ )++ def test_fallback_to_id(self):+ span = MagicMock()+ instance = MagicMock(spec=["id"])+ instance.id = "wf-123"++ _set_workflow_attributes(span, instance)++ span.set_attribute.assert_any_call(+ SemanticConvention.GEN_AI_WORKFLOW_NAME, "wf-123"+ )+++# ===================================================================+# Tool Attributes+# ===================================================================+class TestToolAttributes:+ """Tests for _set_tool_attributes."""++ def test_basic_tool_attributes(self):+ span = MagicMock()+ tool = MagicMock()+ tool.name = "calculator"+ tool.description = "Does math"++ _set_tool_attributes(span, tool, capture_message_content=False)++ span.set_attribute.assert_any_call(+ SemanticConvention.GEN_AI_TOOL_NAME, "calculator"+ )+ span.set_attribute.assert_any_call(+ SemanticConvention.GEN_AI_TOOL_TYPE, "function"+ )+ span.set_attribute.assert_any_call(+ SemanticConvention.GEN_AI_TOOL_DESCRIPTION, "Does math"+ )++ def test_tool_call_args_and_result(self):+ span = MagicMock()+ tool = MagicMock()+ tool.name = "search"+ tool.description = None++ _set_tool_attributes(+ span, tool,+ capture_message_content=True,+ tool_call_id="call-123",+ arguments={"query": "weather"},+ result={"temp": 72},+ )++ span.set_attribute.assert_any_call(+ SemanticConvention.GEN_AI_TOOL_CALL_ID, "call-123"+ )+ # Check arguments and result are JSON+ call_args = {+ c[0][0]: c[0][1]+ for c in span.set_attribute.call_args_list+ }+ assert SemanticConvention.GEN_AI_TOOL_CALL_ARGUMENTS in call_args+ assert SemanticConvention.GEN_AI_TOOL_CALL_RESULT in call_args++ def test_no_content_capture_skips_args_result(self):+ span = MagicMock()+ tool = MagicMock()+ tool.name = "search"+ tool.description = None++ _set_tool_attributes(+ span, tool,+ capture_message_content=False,+ arguments={"query": "test"},+ result="some result",+ )++ call_attrs = {c[0][0] for c in span.set_attribute.call_args_list}+ assert SemanticConvention.GEN_AI_TOOL_CALL_ARGUMENTS not in call_attrs+ assert SemanticConvention.GEN_AI_TOOL_CALL_RESULT not in call_attrs+++# ===================================================================+# Response Attribute Extraction+# ===================================================================+class TestResponseAttributes:+ """Tests for _extract_response_attributes."""++ def test_full_response(self):+ span = MagicMock()+ response = MagicMock()+ response.response_id = "resp-001"+ response.model_id = "gpt-4o"+ response.usage_details = {+ "input_token_count": 100,+ "output_token_count": 50,+ }+ response.finish_reason = "stop"++ _extract_response_attributes(span, response)++ span.set_attribute.assert_any_call(+ SemanticConvention.GEN_AI_RESPONSE_ID, "resp-001"+ )+ span.set_attribute.assert_any_call(+ SemanticConvention.GEN_AI_RESPONSE_MODEL, "gpt-4o"+ )+ span.set_attribute.assert_any_call(+ SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS, 100+ )+ span.set_attribute.assert_any_call(+ SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS, 50+ )++ def test_none_response(self):+ span = MagicMock()+ _extract_response_attributes(span, None)+ span.set_attribute.assert_not_called()++ def test_no_usage(self):+ span = MagicMock()+ response = MagicMock()+ response.response_id = "r1"+ response.model_id = None+ response.usage_details = None+ response.finish_reason = None++ _extract_response_attributes(span, response)++ call_attrs = {c[0][0] for c in span.set_attribute.call_args_list}+ assert SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS not in call_attrs+++# ===================================================================+# Input Message Capture+# ===================================================================+class TestInputMessageCapture:+ """Tests for _capture_input_messages."""++ def test_string_input(self):+ span = MagicMock()+ _capture_input_messages(span, "Hello, world!")++ call_attrs = {c[0][0]: c[0][1] for c in span.set_attribute.call_args_list}+ assert SemanticConvention.GEN_AI_INPUT_MESSAGES in call_attrs+ parsed = json.loads(call_attrs[SemanticConvention.GEN_AI_INPUT_MESSAGES])+ assert parsed[0]["role"] == "user"+ assert "Hello" in parsed[0]["content"]++ def test_list_of_strings(self):+ span = MagicMock()+ _capture_input_messages(span, ["msg1", "msg2"])++ call_attrs = {c[0][0]: c[0][1] for c in span.set_attribute.call_args_list}+ parsed = json.loads(call_attrs[SemanticConvention.GEN_AI_INPUT_MESSAGES])+ assert len(parsed) == 2++ def test_none_input(self):+ span = MagicMock()+ _capture_input_messages(span, None)+ span.set_attribute.assert_not_called()++ def test_af_message_objects(self):+ span = MagicMock()++ content = MagicMock()+ content.type = "text"+ content.text = "What is 2+2?"++ msg = MagicMock()+ msg.role = "user"+ msg.contents = [content]++ _capture_input_messages(span, [msg])++ call_attrs = {c[0][0]: c[0][1] for c in span.set_attribute.call_args_list}+ parsed = json.loads(call_attrs[SemanticConvention.GEN_AI_INPUT_MESSAGES])+ assert parsed[0]["role"] == "user"+ assert parsed[0]["parts"][0]["type"] == "text"+++# ===================================================================+# Output Message Capture+# ===================================================================+class TestOutputMessageCapture:+ """Tests for _capture_output_messages."""++ def test_basic_output(self):+ span = MagicMock()++ content = MagicMock()+ content.type = "text"+ content.text = "The answer is 4."++ msg = MagicMock()+ msg.role = "assistant"+ msg.contents = [content]++ response = MagicMock()+ response.messages = [msg]++ _capture_output_messages(span, response)++ call_attrs = {c[0][0]: c[0][1] for c in span.set_attribute.call_args_list}+ parsed = json.loads(call_attrs[SemanticConvention.GEN_AI_OUTPUT_MESSAGES])+ assert parsed[0]["role"] == "assistant"+ assert "4" in parsed[0]["parts"][0]["content"]++ def test_none_response(self):+ span = MagicMock()+ _capture_output_messages(span, None)+ span.set_attribute.assert_not_called()++ def test_function_call_content(self):+ span = MagicMock()++ content = MagicMock()+ content.type = "function_call"+ content.call_id = "call-99"+ content.name = "get_weather"+ content.arguments = '{"city": "NYC"}'++ msg = MagicMock()+ msg.role = "assistant"+ msg.contents = [content]++ response = MagicMock()+ response.messages = [msg]++ _capture_output_messages(span, response)++ call_attrs = {c[0][0]: c[0][1] for c in span.set_attribute.call_args_list}+ parsed = json.loads(call_attrs[SemanticConvention.GEN_AI_OUTPUT_MESSAGES])+ assert parsed[0]["parts"][0]["type"] == "tool_call"+ assert parsed[0]["parts"][0]["name"] == "get_weather"+++# ===================================================================+# System Instructions and Tool Definitions+# ===================================================================+class TestSystemInstructions:+ """Tests for _capture_system_instructions."""++ def test_captures_instructions(self):+ span = MagicMock()+ instance = MagicMock()+ instance.instructions = "You are a helpful assistant."++ _capture_system_instructions(span, instance)++ call_attrs = {c[0][0]: c[0][1] for c in span.set_attribute.call_args_list}+ assert SemanticConvention.GEN_AI_SYSTEM_INSTRUCTIONS in call_attrs+ parsed = json.loads(call_attrs[SemanticConvention.GEN_AI_SYSTEM_INSTRUCTIONS])+ assert parsed[0]["type"] == "text"+ assert "helpful" in parsed[0]["content"]++ def test_no_instructions(self):+ span = MagicMock()+ instance = MagicMock()+ instance.instructions = None++ _capture_system_instructions(span, instance)+ span.set_attribute.assert_not_called()+++class TestToolDefinitions:+ """Tests for _capture_tool_definitions."""++ def test_captures_tool_defs(self):+ span = MagicMock()++ tool1 = MagicMock()+ tool1.name = "search"+ tool1.description = "Search the web"++ tool2 = MagicMock()+ tool2.name = "calculator"+ tool2.description = None++ instance = MagicMock()+ instance.tools = [tool1, tool2]++ _capture_tool_definitions(span, instance)++ call_attrs = {c[0][0]: c[0][1] for c in span.set_attribute.call_args_list}+ assert SemanticConvention.GEN_AI_TOOL_DEFINITIONS in call_attrs+ parsed = json.loads(call_attrs[SemanticConvention.GEN_AI_TOOL_DEFINITIONS])+ assert len(parsed) == 2+ assert parsed[0]["name"] == "search"+ assert parsed[0]["type"] == "function"++ def test_no_tools(self):+ span = MagicMock()+ instance = MagicMock()+ instance.tools = None++ _capture_tool_definitions(span, instance)+ span.set_attribute.assert_not_called()+++# ===================================================================+# Metrics Recording+# ===================================================================+class TestMetricsRecording:+ """Tests for _record_metrics."""++ def test_records_duration(self):+ metrics = {"genai_client_operation_duration": MagicMock()}+ _record_metrics(+ metrics,+ "invoke_agent",+ 1.5,+ "production",+ "my_app",+ "gpt-4o",+ "api.openai.com",+ 443,+ )+ metrics["genai_client_operation_duration"].record.assert_called_once()+ call_args = metrics["genai_client_operation_duration"].record.call_args+ assert call_args[0][0] == 1.5++ def test_skips_unknown_model(self):+ metrics = {"genai_client_operation_duration": MagicMock()}+ _record_metrics(+ metrics, "invoke_agent", 1.0, "dev", "app", "unknown", "", 0+ )+ call_attrs = metrics["genai_client_operation_duration"].record.call_args[1].get(+ "attributes"+ ) or metrics["genai_client_operation_duration"].record.call_args[0][1]+ assert SemanticConvention.GEN_AI_REQUEST_MODEL not in call_attrs++ def test_no_metrics_dict(self):+ _record_metrics({}, "invoke_agent", 1.0, "dev", "app", "gpt-4", "", 0)+++# ===================================================================+# Process Response+# ===================================================================+class TestProcessResponse:+ """Tests for process_agent_framework_response."""++ def test_sets_status_ok(self):+ span = MagicMock()+ instance = MagicMock(spec=[])++ process_agent_framework_response(+ span=span,+ endpoint="agent_run",+ instance=instance,+ start_time=100.0,+ version="0.1.0",+ environment="test",+ application_name="app",+ capture_message_content=False,+ metrics=None,+ disable_metrics=True,+ )++ span.set_status.assert_called_once()+++# ===================================================================+# Agent Init Wrapper+# ===================================================================+class TestWrapAgentInit:+ """Tests for _wrap_agent_init."""++ def test_emits_create_agent_span(self):+ tracer = MagicMock()+ mock_span = MagicMock()+ mock_span.get_span_context.return_value = MagicMock()+ tracer.start_as_current_span.return_value.__enter__ = MagicMock(+ return_value=mock_span+ )+ tracer.start_as_current_span.return_value.__exit__ = MagicMock(+ return_value=False+ )++ registry = _AgentCreationRegistry()+ wrapper_fn = _wrap_agent_init(+ tracer, "test", "app", True, registry+ )++ original_init = MagicMock(return_value=None)+ instance = MagicMock()+ instance.name = "TestAgent"+ instance.id = "agent-001"+ instance.description = "A test agent"+ instance.model_id = "gpt-4"+ instance.instructions = "Be helpful"+ instance.tools = None++ wrapper_fn(original_init, instance, [], {})++ original_init.assert_called_once()+ tracer.start_as_current_span.assert_called_once()+ assert "create_agent" in tracer.start_as_current_span.call_args[0][0]++ def test_registers_creation_context(self):+ tracer = MagicMock()+ mock_span = MagicMock()+ mock_ctx = MagicMock()+ mock_span.get_span_context.return_value = mock_ctx+ tracer.start_as_current_span.return_value.__enter__ = MagicMock(+ return_value=mock_span+ )+ tracer.start_as_current_span.return_value.__exit__ = MagicMock(+ return_value=False+ )++ registry = _AgentCreationRegistry()+ wrapper_fn = _wrap_agent_init(+ tracer, "test", "app", False, registry+ )++ original_init = MagicMock(return_value=None)+ instance = MagicMock()+ instance.name = "MyAgent"+ instance.id = None+ instance.description = None+ instance.model_id = None+ instance.instructions = None+ instance.tools = None++ wrapper_fn(original_init, instance, [], {})++ assert registry.get("MyAgent") is mock_ctx+++# ===================================================================+# Instrumentor Basic+# ===================================================================+class TestInstrumentorBasic:+ """Basic tests for AgentFrameworkInstrumentor."""++ def test_instrumentor_can_be_instantiated(self):+ instrumentor = AgentFrameworkInstrumentor()+ assert instrumentor is not None++ def test_instrumentation_dependencies(self):+ instrumentor = AgentFrameworkInstrumentor()+ deps = instrumentor.instrumentation_dependencies()+ assert any("agent-framework" in d for d in deps)+++# ===================================================================+# Semconv Constants+# ===================================================================+class TestSemconvConstants:+ """Verify required semantic convention constants exist."""++ def test_agent_framework_system_constant(self):+ assert hasattr(SemanticConvention, "GEN_AI_SYSTEM_AGENT_FRAMEWORK")+ assert SemanticConvention.GEN_AI_SYSTEM_AGENT_FRAMEWORK == "agent_framework"++ def test_required_operation_type_constants(self):+ assert hasattr(SemanticConvention, "GEN_AI_OPERATION_TYPE_CREATE_AGENT")+ assert hasattr(SemanticConvention, "GEN_AI_OPERATION_TYPE_AGENT")+ assert hasattr(SemanticConvention, "GEN_AI_OPERATION_TYPE_FRAMEWORK")+ assert hasattr(SemanticConvention, "GEN_AI_OPERATION_TYPE_TOOLS")++ def test_required_attribute_constants(self):+ attrs = [+ "GEN_AI_AGENT_ID",+ "GEN_AI_AGENT_NAME",+ "GEN_AI_AGENT_DESCRIPTION",+ "GEN_AI_WORKFLOW_NAME",+ "GEN_AI_TOOL_NAME",+ "GEN_AI_TOOL_TYPE",+ "GEN_AI_TOOL_DESCRIPTION",+ "GEN_AI_TOOL_CALL_ID",+ "GEN_AI_TOOL_CALL_ARGUMENTS",+ "GEN_AI_TOOL_CALL_RESULT",+ "GEN_AI_TOOL_DEFINITIONS",+ "GEN_AI_SYSTEM_INSTRUCTIONS",+ "GEN_AI_INPUT_MESSAGES",+ "GEN_AI_OUTPUT_MESSAGES",+ "GEN_AI_USAGE_INPUT_TOKENS",+ "GEN_AI_USAGE_OUTPUT_TOKENS",+ "GEN_AI_RESPONSE_ID",+ "GEN_AI_RESPONSE_MODEL",+ "GEN_AI_REQUEST_MODEL",+ "GEN_AI_CONVERSATION_ID",+ ]+ for attr in attrs:+ assert hasattr(SemanticConvention, attr), f"Missing constant: {attr}"+++# ===================================================================+# Operations Lists+# ===================================================================+class TestOperationsLists:+ """Verify that WORKFLOW_OPERATIONS and DETAILED_OPERATIONS are structured+ correctly -- tool_execute always active, create_agent detailed-only."""++ def test_workflow_operations_contains_agent_run(self):+ op_keys = [op[2] for op in WORKFLOW_OPERATIONS]+ assert "agent_run" in op_keys++ def test_workflow_operations_contains_tool_execute(self):+ op_keys = [op[2] for op in WORKFLOW_OPERATIONS]+ assert "tool_execute" in op_keys++ def test_workflow_operations_does_not_contain_agent_init(self):+ op_keys = [op[2] for op in WORKFLOW_OPERATIONS]+ assert "agent_init" not in op_keys++ def test_detailed_operations_contains_agent_init(self):+ op_keys = [op[2] for op in DETAILED_OPERATIONS]+ assert "agent_init" in op_keys++ def test_detailed_operations_contains_workflow_run(self):+ op_keys = [op[2] for op in DETAILED_OPERATIONS]+ assert "workflow_run" in op_keys++ def test_tool_execute_targets_function_tool(self):+ tool_entry = [op for op in WORKFLOW_OPERATIONS if op[2] == "tool_execute"]+ assert len(tool_entry) == 1+ module, method, _, _ = tool_entry[0]+ assert module == "agent_framework._tools"+ assert method == "FunctionTool.invoke"+++# ===================================================================+# Tool Execute Wrapper+# ===================================================================+class TestToolExecuteWrap:+ """Tests for tool_execute_wrap that emits execute_tool spans."""++ def _make_wrapper(self, capture_message_content=True, disable_metrics=True):+ tracer = MagicMock()+ mock_span = MagicMock()+ tracer.start_as_current_span.return_value.__enter__ = MagicMock(+ return_value=mock_span+ )+ tracer.start_as_current_span.return_value.__exit__ = MagicMock(+ return_value=False+ )+ registry = _AgentCreationRegistry()+ wrapper_fn = tool_execute_wrap(+ "tool_execute",+ "1.0.0rc5",+ "test",+ "test_app",+ tracer,+ {},+ capture_message_content,+ {"genai_client_operation_duration": MagicMock()},+ disable_metrics,+ registry,+ )+ return wrapper_fn, tracer, mock_span++ @pytest.mark.asyncio+ async def test_emits_execute_tool_span(self):+ wrapper_fn, tracer, _mock_span = self._make_wrapper()++ async def fake_invoke(*args, **kwargs):+ return "tool result"++ instance = MagicMock()+ instance.name = "get_weather"+ instance.description = "Get weather for a city"++ result_coro = wrapper_fn(+ fake_invoke, instance, [],+ {"tool_call_id": "call-1", "city": "NYC"},+ )+ result = await result_coro++ assert result == "tool result"+ tracer.start_as_current_span.assert_called_once()+ span_name = tracer.start_as_current_span.call_args[0][0]+ assert span_name == "execute_tool get_weather"+ assert tracer.start_as_current_span.call_args[1]["kind"] == SpanKind.INTERNAL++ @pytest.mark.asyncio+ async def test_sets_tool_attributes(self):+ wrapper_fn, _tracer, mock_span = self._make_wrapper()++ async def fake_invoke(*args, **kwargs):+ return '{"temp": 72}'++ instance = MagicMock()+ instance.name = "get_weather"+ instance.description = "Get weather"++ await wrapper_fn(+ fake_invoke, instance, [],+ {"tool_call_id": "call-42", "city": "SF"},+ )++ call_attrs = {+ c[0][0]: c[0][1] for c in mock_span.set_attribute.call_args_list+ }+ assert call_attrs[SemanticConvention.GEN_AI_TOOL_NAME] == "get_weather"+ assert call_attrs[SemanticConvention.GEN_AI_TOOL_CALL_ID] == "call-42"+ assert call_attrs[SemanticConvention.GEN_AI_OPERATION] == SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS++ @pytest.mark.asyncio+ async def test_captures_arguments_when_enabled(self):+ wrapper_fn, _, mock_span = self._make_wrapper(capture_message_content=True)++ async def fake_invoke(*args, **kwargs):+ return "result"++ instance = MagicMock()+ instance.name = "search"+ instance.description = None++ await wrapper_fn(+ fake_invoke, instance, [],+ {"tool_call_id": "call-1", "arguments": {"query": "hello"}},+ )++ call_attrs = {+ c[0][0]: c[0][1] for c in mock_span.set_attribute.call_args_list+ }+ assert SemanticConvention.GEN_AI_TOOL_CALL_ARGUMENTS in call_attrs+ parsed = json.loads(call_attrs[SemanticConvention.GEN_AI_TOOL_CALL_ARGUMENTS])+ assert parsed == {"query": "hello"}++ @pytest.mark.asyncio+ async def test_captures_result_when_enabled(self):+ wrapper_fn, _, mock_span = self._make_wrapper(capture_message_content=True)++ async def fake_invoke(*args, **kwargs):+ return '{"data": "value"}'++ instance = MagicMock()+ instance.name = "fetch"+ instance.description = None++ await wrapper_fn(+ fake_invoke, instance, [],+ {"tool_call_id": "call-1"},+ )++ call_attrs = {+ c[0][0]: c[0][1] for c in mock_span.set_attribute.call_args_list+ }+ assert SemanticConvention.GEN_AI_TOOL_CALL_RESULT in call_attrs++ @pytest.mark.asyncio+ async def test_skips_content_when_disabled(self):+ wrapper_fn, _, mock_span = self._make_wrapper(capture_message_content=False)++ async def fake_invoke(*args, **kwargs):+ return "secret"++ instance = MagicMock()+ instance.name = "tool"+ instance.description = None++ await wrapper_fn(+ fake_invoke, instance, [],+ {"tool_call_id": "call-1", "password": "abc"},+ )++ call_attrs = {+ c[0][0] for c in mock_span.set_attribute.call_args_list+ }+ assert SemanticConvention.GEN_AI_TOOL_CALL_ARGUMENTS not in call_attrs+ assert SemanticConvention.GEN_AI_TOOL_CALL_RESULT not in call_attrs++ @pytest.mark.asyncio+ async def test_handles_exception(self):+ wrapper_fn, _, _mock_span = self._make_wrapper()++ async def failing_invoke(*args, **kwargs):+ raise ValueError("tool error")++ instance = MagicMock()+ instance.name = "bad_tool"+ instance.description = None++ with pytest.raises(ValueError, match="tool error"):+ await wrapper_fn(+ failing_invoke, instance, [],+ {"tool_call_id": "call-1"},+ )++ @pytest.mark.asyncio+ async def test_records_metrics_when_enabled(self):+ metrics_mock = {"genai_client_operation_duration": MagicMock()}+ tracer = MagicMock()+ mock_span = MagicMock()+ tracer.start_as_current_span.return_value.__enter__ = MagicMock(+ return_value=mock_span+ )+ tracer.start_as_current_span.return_value.__exit__ = MagicMock(+ return_value=False+ )+ registry = _AgentCreationRegistry()+ wrapper_fn = tool_execute_wrap(+ "tool_execute", "1.0.0", "prod", "app",+ tracer, {}, False, metrics_mock, False, registry,+ )++ async def fake_invoke(*args, **kwargs):+ return "ok"++ instance = MagicMock()+ instance.name = "tool"+ instance.description = None++ await wrapper_fn(fake_invoke, instance, [], {"tool_call_id": "c1"})+ metrics_mock["genai_client_operation_duration"].record.assert_called_once()++ @pytest.mark.asyncio+ async def test_extracts_arguments_from_arguments_kwarg(self):+ """Verify that only kwargs['arguments'] is used, not the full kwargs dict."""+ wrapper_fn, _, mock_span = self._make_wrapper(capture_message_content=True)++ async def fake_invoke(*args, **kwargs):+ return "ok"++ instance = MagicMock()+ instance.name = "tool"+ instance.description = None++ await wrapper_fn(+ fake_invoke, instance, [],+ {"tool_call_id": "c1", "arguments": {"city": "SF"}, "context": None},+ )++ call_attrs = {+ c[0][0]: c[0][1] for c in mock_span.set_attribute.call_args_list+ }+ args_str = call_attrs.get(SemanticConvention.GEN_AI_TOOL_CALL_ARGUMENTS, "")+ assert "context" not in args_str+ assert "city" in args_str++ @pytest.mark.asyncio+ async def test_serializes_content_result(self):+ """Verify that list[Content] results are serialized via __str__."""+ wrapper_fn, _, mock_span = self._make_wrapper(capture_message_content=True)++ content_obj = MagicMock()+ content_obj.type = "text"+ content_obj.text = "62°F, foggy"+ content_obj.__str__ = MagicMock(return_value="62°F, foggy")++ async def fake_invoke(*args, **kwargs):+ return [content_obj]++ instance = MagicMock()+ instance.name = "get_weather"+ instance.description = None++ await wrapper_fn(+ fake_invoke, instance, [],+ {"tool_call_id": "c1"},+ )++ call_attrs = {+ c[0][0]: c[0][1] for c in mock_span.set_attribute.call_args_list+ }+ result_str = call_attrs.get(SemanticConvention.GEN_AI_TOOL_CALL_RESULT, "")+ assert "62°F, foggy" in result_str+++# ===================================================================+# Content Serialization Helper+# ===================================================================+class TestSerializeContentList:+ """Tests for _serialize_content_list helper."""++ def test_none_returns_none(self):+ assert _serialize_content_list(None) is None++ def test_empty_list_returns_none(self):+ assert _serialize_content_list([]) is None++ def test_string_passthrough(self):+ assert _serialize_content_list("hello") == "hello"++ def test_single_content_object(self):+ obj = MagicMock()+ obj.__str__ = MagicMock(return_value="The weather is sunny")+ result = _serialize_content_list([obj])+ assert result == "The weather is sunny"++ def test_multiple_content_objects(self):+ obj1 = MagicMock()+ obj1.__str__ = MagicMock(return_value="Line 1")+ obj2 = MagicMock()+ obj2.__str__ = MagicMock(return_value="Line 2")+ result = _serialize_content_list([obj1, obj2])+ assert result == "Line 1\nLine 2"++ def test_filters_none_items(self):+ obj = MagicMock()+ obj.__str__ = MagicMock(return_value="valid")+ result = _serialize_content_list([None, obj, None])+ assert result == "valid"diff --git a/sdk/python/tests/test_claude_agent_sdk.py b/sdk/python/tests/test_claude_agent_sdk.pynew file mode 100644index 00000000..b226ede4--- /dev/null+++ b/sdk/python/tests/test_claude_agent_sdk.py@@ -0,0 +1,1430 @@+# pylint: disable=duplicate-code, no-member, too-few-public-methods, missing-class-docstring, missing-function-docstring+"""+Tests for Claude Agent SDK instrumentation using the claude-agent-sdk Python library.++Tests cover:+- Instrumentor import and basic instantiation+- Utils: OPERATION_MAP, SPAN_KIND_MAP, ANTHROPIC_FINISH_REASON_MAP+- Span name generation+- SpanKind resolution+- Token usage extraction (including cached token summing)+- Finish reason mapping+- AssistantMessage meaningful content detection+- Tool result input building+- Chat span attribute enrichment+- Tool span attribute enrichment (incl. MCP type detection)+- Create agent span attributes+- Root invoke_agent span attributes+- ResultMessage processing (num_turns, duration, cost, error)+- Output message JSON schema compliance (OTel parts schema)+- Input message JSON schema compliance+- System instructions JSON schema compliance+- Inference event emission+- Metrics recording (duration + token usage)+- Cost calculation+- ToolSpanTracker lifecycle (start, end, error, end_all, dedup)+- SubagentSpanTracker lifecycle (start, end, tool_use_id mapping)++Note: These tests do NOT require claude-agent-sdk to be installed -- they mock+all SDK internals so the test suite can run in any environment.+"""++import json+from unittest.mock import MagicMock++import pytest+from opentelemetry.trace import SpanKind, StatusCode++from openlit.instrumentation.claude_agent_sdk.utils import (+ OPERATION_MAP,+ SPAN_KIND_MAP,+ ANTHROPIC_FINISH_REASON_MAP,+ SERVER_ADDRESS,+ SERVER_PORT,+ GEN_AI_SYSTEM_ATTR,+ GEN_AI_SYSTEM_VALUE,+ generate_span_name,+ get_span_kind,+ extract_usage,+ update_root_from_assistant,+ has_llm_call_data,+ has_meaningful_content,+ build_input_from_tool_results,+ set_chat_span_attributes,+ set_tool_span_attributes,+ finalize_tool_span,+ set_create_agent_attributes,+ set_initial_span_attributes,+ process_result_message,+ finalize_span,+)+from openlit.semcov import SemanticConvention+++# ---------------------------------------------------------------------------+# Helpers — mock Claude Agent SDK types+# ---------------------------------------------------------------------------+def _make_assistant_message(+ model="claude-sonnet-4-20250514",+ content=None,+ usage=None,+ stop_reason=None,+ message_id="msg_001",+ session_id="sess_001",+ parent_tool_use_id=None,+):+ msg = MagicMock()+ type(msg).__name__ = "AssistantMessage"+ msg.model = model+ msg.content = content or []+ msg.usage = usage+ msg.stop_reason = stop_reason+ msg.message_id = message_id+ msg.session_id = session_id+ msg.parent_tool_use_id = parent_tool_use_id+ return msg+++def _make_text_block(text="Hello world"):+ block = MagicMock()+ type(block).__name__ = "TextBlock"+ block.text = text+ return block+++def _make_thinking_block(thinking="Let me think about this..."):+ block = MagicMock()+ type(block).__name__ = "ThinkingBlock"+ block.thinking = thinking+ return block+++def _make_tool_use_block(name="Bash", input_data=None, tool_id="toolu_001"):+ block = MagicMock()+ type(block).__name__ = "ToolUseBlock"+ block.name = name+ block.input = input_data or {"command": "ls"}+ block.id = tool_id+ return block+++def _make_tool_result_block(tool_use_id="toolu_001", content="file1.txt\nfile2.txt",+ is_error=False):+ block = MagicMock()+ type(block).__name__ = "ToolResultBlock"+ block.tool_use_id = tool_use_id+ block.content = content+ block.is_error = is_error+ return block+++def _make_usage(input_tokens=100, output_tokens=50, cache_read=0, cache_creation=0):+ """Build a usage object with only the fields extract_usage looks for.++ Uses SimpleNamespace to avoid MagicMock auto-creating unexpected attributes+ (e.g. cache_write_input_tokens) that break int() coercion.+ """+ from types import SimpleNamespace+ return SimpleNamespace(+ input_tokens=input_tokens,+ output_tokens=output_tokens,+ cache_read_input_tokens=cache_read,+ cache_creation_input_tokens=cache_creation,+ )+++def _make_result_message(+ session_id="sess_001",+ usage=None,+ total_cost_usd=0.005,+ model_usage=None,+ num_turns=2,+ duration_ms=5000,+ duration_api_ms=4000,+ is_error=False,+ result="The answer is 42.",+):+ msg = MagicMock()+ type(msg).__name__ = "ResultMessage"+ msg.session_id = session_id+ msg.usage = usage+ msg.total_cost_usd = total_cost_usd+ msg.model_usage = model_usage or {"claude-sonnet-4-20250514": {}}+ msg.num_turns = num_turns+ msg.duration_ms = duration_ms+ msg.duration_api_ms = duration_api_ms+ msg.is_error = is_error+ msg.result = result+ return msg+++def _make_user_message(content=None):+ msg = MagicMock()+ type(msg).__name__ = "UserMessage"+ msg.content = content or []+ return msg+++def _get_span_attrs(span):+ """Extract a dict of all set_attribute calls on a mock span."""+ return {c[0][0]: c[0][1] for c in span.set_attribute.call_args_list}+++# ===========================================================================+# Constants & Maps+# ===========================================================================+class TestOperationMap:+ def test_has_required_endpoints(self):+ for key in ("query", "receive_response", "execute_tool", "subagent", "chat", "create_agent"):+ assert key in OPERATION_MAP, f"Missing endpoint: {key}"++ def test_query_maps_to_invoke_agent(self):+ assert OPERATION_MAP["query"] == SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT++ def test_chat_maps_to_chat(self):+ assert OPERATION_MAP["chat"] == SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT++ def test_execute_tool_maps_to_tools(self):+ assert OPERATION_MAP["execute_tool"] == SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS++ def test_create_agent_maps_correctly(self):+ assert OPERATION_MAP["create_agent"] == SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT+++class TestSpanKindMap:+ def test_agent_is_internal(self):+ assert SPAN_KIND_MAP[SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT] == SpanKind.INTERNAL++ def test_chat_is_client(self):+ assert SPAN_KIND_MAP[SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT] == SpanKind.CLIENT++ def test_tools_is_internal(self):+ assert SPAN_KIND_MAP[SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS] == SpanKind.INTERNAL++ def test_create_agent_is_client(self):+ assert SPAN_KIND_MAP[SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT] == SpanKind.CLIENT+++class TestFinishReasonMap:+ def test_end_turn_maps_to_stop(self):+ assert ANTHROPIC_FINISH_REASON_MAP["end_turn"] == "stop"++ def test_max_tokens_maps_to_length(self):+ assert ANTHROPIC_FINISH_REASON_MAP["max_tokens"] == "length"++ def test_tool_use_maps_to_tool_call(self):+ assert ANTHROPIC_FINISH_REASON_MAP["tool_use"] == "tool_call"++ def test_stop_sequence_maps_to_stop(self):+ assert ANTHROPIC_FINISH_REASON_MAP["stop_sequence"] == "stop"+++class TestConstants:+ def test_server_address(self):+ assert SERVER_ADDRESS == "api.anthropic.com"++ def test_server_port(self):+ assert SERVER_PORT == 443++ def test_gen_ai_system_value(self):+ assert GEN_AI_SYSTEM_VALUE == "anthropic"++ def test_gen_ai_system_attr(self):+ assert GEN_AI_SYSTEM_ATTR == "gen_ai.system"++ def test_semconv_constant_exists(self):+ assert hasattr(SemanticConvention, "GEN_AI_SYSTEM_CLAUDE_AGENT_SDK")+ assert SemanticConvention.GEN_AI_SYSTEM_CLAUDE_AGENT_SDK == "claude_agent_sdk"+++# ===========================================================================+# Span Name Generation+# ===========================================================================+class TestSpanNameGeneration:+ def test_query_span_name(self):+ assert generate_span_name("query") == "invoke_agent claude_agent_sdk"++ def test_receive_response_span_name(self):+ assert generate_span_name("receive_response") == "invoke_agent claude_agent_sdk"++ def test_chat_span_name_with_model(self):+ assert generate_span_name("chat", "claude-sonnet-4-20250514") == "chat claude-sonnet-4-20250514"++ def test_execute_tool_span_name(self):+ assert generate_span_name("execute_tool", "Bash") == "execute_tool Bash"++ def test_create_agent_span_name(self):+ assert generate_span_name("create_agent", "claude_agent_sdk") == "create_agent claude_agent_sdk"++ def test_subagent_span_name(self):+ assert generate_span_name("subagent", "search_agent") == "invoke_agent search_agent"++ def test_unknown_operation_falls_back(self):+ name = generate_span_name("unknown_op")+ assert "invoke_agent" in name+++class TestGetSpanKind:+ def test_known_operation_types(self):+ assert get_span_kind(SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT) == SpanKind.CLIENT+ assert get_span_kind(SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT) == SpanKind.INTERNAL++ def test_unknown_defaults_to_internal(self):+ assert get_span_kind("completely_unknown") == SpanKind.INTERNAL+++# ===========================================================================+# Token Usage Extraction+# ===========================================================================+class TestExtractUsage:+ def test_full_usage_object(self):+ usage = _make_usage(input_tokens=10, output_tokens=50, cache_read=90, cache_creation=5)+ attrs = extract_usage(usage)++ assert attrs[SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS] == 10 + 90 + 5+ assert attrs[SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS] == 50+ assert attrs[SemanticConvention.GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS] == 90+ assert attrs[SemanticConvention.GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS] == 5++ def test_input_tokens_sums_all_types(self):+ """OTel spec: gen_ai.usage.input_tokens SHOULD include cached tokens."""+ usage = _make_usage(input_tokens=3, cache_read=9284, cache_creation=122)+ attrs = extract_usage(usage)+ assert attrs[SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS] == 3 + 9284 + 122++ def test_no_cache_tokens(self):+ from types import SimpleNamespace+ usage = SimpleNamespace(+ input_tokens=100, output_tokens=50,+ cache_read_input_tokens=None, cache_creation_input_tokens=None,+ )+ attrs = extract_usage(usage)+ assert attrs[SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS] == 100++ def test_none_usage_returns_empty(self):+ assert not extract_usage(None)++ def test_dict_usage(self):+ usage = {+ "input_tokens": 200,+ "output_tokens": 100,+ "cache_read_input_tokens": 50,+ }+ attrs = extract_usage(usage)+ assert attrs[SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS] == 250+ assert attrs[SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS] == 100++ def test_none_output_tokens_omitted(self):+ usage = _make_usage(input_tokens=10, output_tokens=0)+ usage.output_tokens = None+ attrs = extract_usage(usage)+ assert SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS not in attrs++ def test_non_numeric_handled_gracefully(self):+ from types import SimpleNamespace+ usage = SimpleNamespace(+ input_tokens="not_a_number", output_tokens="bad",+ cache_read_input_tokens=None, cache_creation_input_tokens=None,+ )+ attrs = extract_usage(usage)+ assert attrs[SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS] == 0+++# ===========================================================================+# Finish Reason Mapping+# ===========================================================================+class TestMapFinishReason:+ def test_all_anthropic_reasons(self):+ from openlit.instrumentation.claude_agent_sdk.utils import _map_finish_reason++ assert _map_finish_reason("end_turn") == "stop"+ assert _map_finish_reason("max_tokens") == "length"+ assert _map_finish_reason("tool_use") == "tool_call"+ assert _map_finish_reason("stop_sequence") == "stop"++ def test_none_defaults_to_stop(self):+ from openlit.instrumentation.claude_agent_sdk.utils import _map_finish_reason+ assert _map_finish_reason(None) == "stop"++ def test_unknown_passed_through(self):+ from openlit.instrumentation.claude_agent_sdk.utils import _map_finish_reason+ assert _map_finish_reason("custom_reason") == "custom_reason"+++# ===========================================================================+# Content Detection+# ===========================================================================+class TestHasLLMCallData:+ def test_true_with_model_and_usage(self):+ msg = _make_assistant_message(usage=_make_usage())+ assert has_llm_call_data(msg) is True++ def test_false_without_model(self):+ msg = _make_assistant_message(model=None, usage=_make_usage())+ assert has_llm_call_data(msg) is False++ def test_false_without_usage(self):+ msg = _make_assistant_message(usage=None)+ assert has_llm_call_data(msg) is False+++class TestHasMeaningfulContent:+ def test_text_block_is_meaningful(self):+ assert has_meaningful_content([_make_text_block("Hello")]) is True++ def test_empty_text_block_not_meaningful(self):+ assert has_meaningful_content([_make_text_block("")]) is False++ def test_tool_use_block_is_meaningful(self):+ assert has_meaningful_content([_make_tool_use_block()]) is True++ def test_thinking_block_not_meaningful(self):+ assert has_meaningful_content([_make_thinking_block()]) is False++ def test_empty_list_not_meaningful(self):+ assert has_meaningful_content([]) is False++ def test_none_not_meaningful(self):+ assert has_meaningful_content(None) is False++ def test_thinking_plus_tool_use_is_meaningful(self):+ content = [_make_thinking_block(), _make_tool_use_block()]+ assert has_meaningful_content(content) is True++ def test_thinking_only_not_meaningful(self):+ content = [_make_thinking_block(), _make_text_block("")]+ assert has_meaningful_content(content) is False+++# ===========================================================================+# Tool Result Input Building+# ===========================================================================+class TestBuildInputFromToolResults:+ def test_builds_tool_call_response_parts(self):+ msg = _make_user_message(content=[+ _make_tool_result_block("toolu_001", "result_data"),+ ])+ result = build_input_from_tool_results(msg)++ assert result is not None+ assert len(result) == 1+ assert result[0]["role"] == "user"+ assert result[0]["parts"][0]["type"] == "tool_call_response"+ assert result[0]["parts"][0]["id"] == "toolu_001"+ assert "result_data" in result[0]["parts"][0]["response"]++ def test_multiple_tool_results(self):+ msg = _make_user_message(content=[+ _make_tool_result_block("toolu_001", "res1"),+ _make_tool_result_block("toolu_002", "res2"),+ ])+ result = build_input_from_tool_results(msg)+ assert len(result[0]["parts"]) == 2++ def test_no_tool_result_blocks_returns_none(self):+ msg = _make_user_message(content=[_make_text_block("hello")])+ assert build_input_from_tool_results(msg) is None++ def test_empty_content_returns_none(self):+ msg = _make_user_message(content=[])+ assert build_input_from_tool_results(msg) is None++ def test_none_content_returns_none(self):+ msg = MagicMock()+ msg.content = None+ assert build_input_from_tool_results(msg) is None+++# ===========================================================================+# Chat Span Attributes+# ===========================================================================+class TestSetChatSpanAttributes:+ def _call(self, message=None, capture=True, pricing_info=None, input_messages=None):+ span = MagicMock()+ if message is None:+ message = _make_assistant_message(+ usage=_make_usage(input_tokens=10, output_tokens=50),+ stop_reason="end_turn",+ content=[_make_text_block("Hello!")],+ )+ set_chat_span_attributes(+ span, message, capture,+ environment="test",+ application_name="test_app",+ version="0.1.0",+ pricing_info=pricing_info,+ event_provider=None,+ input_messages=input_messages,+ )+ return span, _get_span_attrs(span)++ def test_required_attributes_present(self):+ _, attrs = self._call()+ assert attrs[SemanticConvention.GEN_AI_OPERATION] == SemanticConvention.GEN_AI_OPERATION_TYPE_CHAT+ assert attrs[SemanticConvention.GEN_AI_PROVIDER_NAME] == SemanticConvention.GEN_AI_SYSTEM_ANTHROPIC++ def test_gen_ai_system_set(self):+ _, attrs = self._call()+ assert attrs[GEN_AI_SYSTEM_ATTR] == "anthropic"++ def test_server_address_and_port(self):+ _, attrs = self._call()+ assert attrs[SemanticConvention.SERVER_ADDRESS] == "api.anthropic.com"+ assert attrs[SemanticConvention.SERVER_PORT] == 443++ def test_model_attributes(self):+ _, attrs = self._call()+ assert attrs[SemanticConvention.GEN_AI_REQUEST_MODEL] == "claude-sonnet-4-20250514"+ assert attrs[SemanticConvention.GEN_AI_RESPONSE_MODEL] == "claude-sonnet-4-20250514"++ def test_usage_tokens(self):+ _, attrs = self._call()+ assert attrs[SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS] == 10+ assert attrs[SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS] == 50++ def test_finish_reason_mapped(self):+ _, attrs = self._call()+ assert attrs[SemanticConvention.GEN_AI_RESPONSE_FINISH_REASON] == ["stop"]++ def test_finish_reason_inferred_for_tool_use(self):+ """When stop_reason is None but content has ToolUseBlock, infer tool_use."""+ msg = _make_assistant_message(+ usage=_make_usage(),+ stop_reason=None,+ content=[_make_tool_use_block()],+ )+ _, attrs = self._call(message=msg)+ assert attrs[SemanticConvention.GEN_AI_RESPONSE_FINISH_REASON] == ["tool_call"]++ def test_response_id_set(self):+ _, attrs = self._call()+ assert attrs[SemanticConvention.GEN_AI_RESPONSE_ID] == "msg_001"++ def test_conversation_id_set(self):+ _, attrs = self._call()+ assert attrs[SemanticConvention.GEN_AI_CONVERSATION_ID] == "sess_001"++ def test_cost_always_present(self):+ _, attrs = self._call()+ assert SemanticConvention.GEN_AI_USAGE_COST in attrs++ def test_cost_defaults_to_zero(self):+ _, attrs = self._call(pricing_info=None)+ assert attrs[SemanticConvention.GEN_AI_USAGE_COST] == 0++ def test_output_messages_when_capture_enabled(self):+ _, attrs = self._call(capture=True)+ raw = attrs.get(SemanticConvention.GEN_AI_OUTPUT_MESSAGES)+ assert raw is not None+ messages = json.loads(raw)+ assert messages[0]["role"] == "assistant"+ assert "parts" in messages[0]+ assert messages[0]["parts"][0]["type"] == "text"+ assert "finish_reason" in messages[0]++ def test_no_output_messages_when_capture_disabled(self):+ _, attrs = self._call(capture=False)+ assert SemanticConvention.GEN_AI_OUTPUT_MESSAGES not in attrs++ def test_input_messages_set_when_provided(self):+ input_msgs = [{"role": "user", "parts": [{"type": "text", "content": "Hi"}]}]+ _, attrs = self._call(input_messages=input_msgs)+ raw = attrs.get(SemanticConvention.GEN_AI_INPUT_MESSAGES)+ assert raw is not None+ parsed = json.loads(raw)+ assert parsed[0]["role"] == "user"+ assert parsed[0]["parts"][0]["type"] == "text"++ def test_span_status_ok(self):+ span, _ = self._call()+ span.set_status.assert_called_once()+ status = span.set_status.call_args[0][0]+ assert status.status_code == StatusCode.OK+++# ===========================================================================+# Output Message JSON Schema Compliance+# ===========================================================================+class TestOutputMessageSchema:+ def test_text_output_follows_parts_schema(self):+ from openlit.instrumentation.claude_agent_sdk.utils import _build_output_messages++ msg = _make_assistant_message(content=[_make_text_block("Hello!")])+ result = _build_output_messages(msg, "stop")++ assert isinstance(result, list)+ assert result[0]["role"] == "assistant"+ assert result[0]["finish_reason"] == "stop"+ assert result[0]["parts"][0]["type"] == "text"+ assert result[0]["parts"][0]["content"] == "Hello!"++ def test_tool_call_output_follows_parts_schema(self):+ from openlit.instrumentation.claude_agent_sdk.utils import _build_output_messages++ msg = _make_assistant_message(content=[+ _make_tool_use_block("Bash", {"command": "ls"}, "toolu_001"),+ ])+ result = _build_output_messages(msg, "tool_call")++ tc_part = result[0]["parts"][0]+ assert tc_part["type"] == "tool_call"+ assert tc_part["name"] == "Bash"+ assert tc_part["id"] == "toolu_001"+ assert tc_part["arguments"] == {"command": "ls"}+ assert result[0]["finish_reason"] == "tool_call"++ def test_reasoning_output_uses_correct_type(self):+ """OTel ReasoningPart requires type='reasoning', not 'thinking'."""+ from openlit.instrumentation.claude_agent_sdk.utils import _build_output_messages++ msg = _make_assistant_message(content=[+ _make_thinking_block("Let me analyze..."),+ _make_text_block("The answer is 42."),+ ])+ result = _build_output_messages(msg, "stop")++ parts = result[0]["parts"]+ reasoning_part = parts[0]+ assert reasoning_part["type"] == "reasoning"+ assert reasoning_part["content"] == "Let me analyze..."+ text_part = parts[1]+ assert text_part["type"] == "text"++ def test_mixed_content_output(self):+ from openlit.instrumentation.claude_agent_sdk.utils import _build_output_messages++ msg = _make_assistant_message(content=[+ _make_thinking_block("Thinking..."),+ _make_text_block("Here's the plan:"),+ _make_tool_use_block("Bash", {"command": "ls"}, "toolu_x"),+ ])+ result = _build_output_messages(msg, "tool_call")+ parts = result[0]["parts"]++ assert len(parts) == 3+ assert parts[0]["type"] == "reasoning"+ assert parts[1]["type"] == "text"+ assert parts[2]["type"] == "tool_call"++ def test_empty_content_returns_none(self):+ from openlit.instrumentation.claude_agent_sdk.utils import _build_output_messages++ msg = _make_assistant_message(content=[])+ assert _build_output_messages(msg, "stop") is None+++# ===========================================================================+# Tool Span Attributes+# ===========================================================================+class TestSetToolSpanAttributes:+ def _call(self, tool_name="Bash", tool_input=None, tool_use_id="toolu_001",+ capture=True):+ span = MagicMock()+ set_tool_span_attributes(+ span, tool_name, tool_input or {"command": "ls"}, tool_use_id,+ capture, "test", "test_app", "0.1.0",+ )+ return span, _get_span_attrs(span)++ def test_operation_name_is_execute_tool(self):+ _, attrs = self._call()+ assert attrs[SemanticConvention.GEN_AI_OPERATION] == SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS++ def test_gen_ai_system_set(self):+ _, attrs = self._call()+ assert attrs[GEN_AI_SYSTEM_ATTR] == "anthropic"++ def test_tool_name_set(self):+ _, attrs = self._call(tool_name="Bash")+ assert attrs[SemanticConvention.GEN_AI_TOOL_NAME] == "Bash"++ def test_tool_type_function_for_regular_tools(self):+ _, attrs = self._call(tool_name="Bash")+ assert attrs[SemanticConvention.GEN_AI_TOOL_TYPE] == "function"++ def test_tool_type_extension_for_mcp_tools(self):+ _, attrs = self._call(tool_name="mcp__filesystem__read_file")+ assert attrs[SemanticConvention.GEN_AI_TOOL_TYPE] == "extension"++ def test_tool_call_id_set(self):+ _, attrs = self._call(tool_use_id="toolu_abc")+ assert attrs[SemanticConvention.GEN_AI_TOOL_CALL_ID] == "toolu_abc"++ def test_arguments_captured_when_enabled(self):+ _, attrs = self._call(tool_input={"cmd": "ls -la"}, capture=True)+ assert SemanticConvention.GEN_AI_TOOL_CALL_ARGUMENTS in attrs+ parsed = json.loads(attrs[SemanticConvention.GEN_AI_TOOL_CALL_ARGUMENTS])+ assert parsed["cmd"] == "ls -la"++ def test_arguments_not_captured_when_disabled(self):+ _, attrs = self._call(capture=False)+ assert SemanticConvention.GEN_AI_TOOL_CALL_ARGUMENTS not in attrs++ def test_server_address_and_port(self):+ _, attrs = self._call()+ assert attrs[SemanticConvention.SERVER_ADDRESS] == "api.anthropic.com"+ assert attrs[SemanticConvention.SERVER_PORT] == 443+++class TestFinalizeToolSpan:+ def test_success_with_result(self):+ span = MagicMock()+ finalize_tool_span(span, "file1.txt\nfile2.txt", capture_message_content=True)++ attrs = _get_span_attrs(span)+ assert SemanticConvention.GEN_AI_TOOL_CALL_RESULT in attrs+ span.set_status.assert_called_once()+ status = span.set_status.call_args[0][0]+ assert status.status_code == StatusCode.OK++ def test_success_without_capture(self):+ span = MagicMock()+ finalize_tool_span(span, "result", capture_message_content=False)++ attrs = _get_span_attrs(span)+ assert SemanticConvention.GEN_AI_TOOL_CALL_RESULT not in attrs++ def test_error_sets_error_type_and_status(self):+ span = MagicMock()+ finalize_tool_span(+ span, None, capture_message_content=True,+ is_error=True, error_message="Permission denied",+ )++ attrs = _get_span_attrs(span)+ assert attrs[SemanticConvention.ERROR_TYPE] == "Permission denied"+ status = span.set_status.call_args[0][0]+ assert status.status_code == StatusCode.ERROR+++# ===========================================================================+# Create Agent Span+# ===========================================================================+class TestSetCreateAgentAttributes:+ def test_attributes(self):+ span = MagicMock()+ set_create_agent_attributes(span, "0.1.0", "test", "test_app")++ attrs = _get_span_attrs(span)+ assert attrs[SemanticConvention.GEN_AI_OPERATION] == SemanticConvention.GEN_AI_OPERATION_TYPE_CREATE_AGENT+ assert attrs[GEN_AI_SYSTEM_ATTR] == "anthropic"+ assert attrs[SemanticConvention.GEN_AI_AGENT_NAME] == "claude_agent_sdk"+ assert attrs[SemanticConvention.SERVER_ADDRESS] == "api.anthropic.com"+ assert attrs[SemanticConvention.SERVER_PORT] == 443+++# ===========================================================================+# Root Span (invoke_agent) Attributes+# ===========================================================================+class TestSetInitialSpanAttributes:+ def _call(self, model="claude-sonnet-4-20250514", prompt="Hello", capture=True,+ system_prompt=None):+ span = MagicMock()+ options = MagicMock()+ options.model = model+ options.system_prompt = system_prompt++ set_initial_span_attributes(+ span, 1000.0, "0.1.0", "test", "test_app",+ options=options, prompt=prompt, capture_message_content=capture,+ )+ return span, _get_span_attrs(span)++ def test_operation_name(self):+ _, attrs = self._call()+ assert attrs[SemanticConvention.GEN_AI_OPERATION] == SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT++ def test_provider_name(self):+ _, attrs = self._call()+ assert attrs[SemanticConvention.GEN_AI_PROVIDER_NAME] == SemanticConvention.GEN_AI_SYSTEM_CLAUDE_AGENT_SDK++ def test_gen_ai_system(self):+ _, attrs = self._call()+ assert attrs[GEN_AI_SYSTEM_ATTR] == "anthropic"++ def test_agent_name(self):+ _, attrs = self._call()+ assert attrs[SemanticConvention.GEN_AI_AGENT_NAME] == "claude_agent_sdk"++ def test_request_model(self):+ _, attrs = self._call(model="claude-sonnet-4-20250514")+ assert attrs[SemanticConvention.GEN_AI_REQUEST_MODEL] == "claude-sonnet-4-20250514"++ def test_input_messages_parts_schema(self):+ """gen_ai.input.messages must use [{role, parts}] schema."""+ _, attrs = self._call(prompt="What is 2+2?", capture=True)+ raw = attrs.get(SemanticConvention.GEN_AI_INPUT_MESSAGES)+ assert raw is not None+ parsed = json.loads(raw)+ assert parsed[0]["role"] == "user"+ assert "parts" in parsed[0]+ assert parsed[0]["parts"][0]["type"] == "text"+ assert parsed[0]["parts"][0]["content"] == "What is 2+2?"++ def test_no_input_messages_when_capture_disabled(self):+ _, attrs = self._call(capture=False)+ assert SemanticConvention.GEN_AI_INPUT_MESSAGES not in attrs++ def test_system_instructions_json_schema(self):+ """gen_ai.system_instructions must follow [{'type': 'text', 'content': '...'}]."""+ _, attrs = self._call(system_prompt="You are a helpful assistant.", capture=True)+ raw = attrs.get(SemanticConvention.GEN_AI_SYSTEM_INSTRUCTIONS)+ assert raw is not None+ parsed = json.loads(raw)+ assert isinstance(parsed, list)+ assert parsed[0]["type"] == "text"+ assert parsed[0]["content"] == "You are a helpful assistant."+++class TestUpdateRootFromAssistant:+ def test_sets_model_and_session(self):+ span = MagicMock()+ msg = _make_assistant_message(model="claude-sonnet-4-20250514", session_id="sess_x")+ update_root_from_assistant(span, msg)++ attrs = _get_span_attrs(span)+ assert attrs[SemanticConvention.GEN_AI_REQUEST_MODEL] == "claude-sonnet-4-20250514"+ assert attrs[SemanticConvention.GEN_AI_RESPONSE_MODEL] == "claude-sonnet-4-20250514"+ assert attrs[SemanticConvention.GEN_AI_CONVERSATION_ID] == "sess_x"++ def test_handles_none_model_gracefully(self):+ span = MagicMock()+ msg = _make_assistant_message(model=None, session_id=None)+ update_root_from_assistant(span, msg)+ span.set_attribute.assert_not_called()+++# ===========================================================================+# ResultMessage Processing+# ===========================================================================+class TestProcessResultMessage:+ def _call(self, **kwargs):+ span = MagicMock()+ msg = _make_result_message(**kwargs)+ result_usage = process_result_message(span, msg, capture_message_content=True)+ return span, _get_span_attrs(span), result_usage++ def test_session_id_set(self):+ _, attrs, _ = self._call(session_id="sess_abc")+ assert attrs[SemanticConvention.GEN_AI_CONVERSATION_ID] == "sess_abc"++ def test_usage_extracted(self):+ usage = _make_usage(input_tokens=100, output_tokens=50, cache_read=200, cache_creation=50)+ _, attrs, result_usage = self._call(usage=usage)+ assert attrs[SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS] == 350 # 100 + 200 + 50+ assert attrs[SemanticConvention.GEN_AI_USAGE_OUTPUT_TOKENS] == 50+ assert result_usage["input_tokens"] == 350+ assert result_usage["output_tokens"] == 50++ def test_cost_from_total_cost_usd(self):+ _, attrs, _ = self._call(total_cost_usd=0.0123)+ assert attrs[SemanticConvention.GEN_AI_USAGE_COST] == 0.0123++ def test_response_model_from_model_usage(self):+ _, attrs, _ = self._call(model_usage={"claude-sonnet-4-20250514": {}})+ assert attrs[SemanticConvention.GEN_AI_RESPONSE_MODEL] == "claude-sonnet-4-20250514"++ def test_num_turns_set(self):+ _, attrs, _ = self._call(num_turns=3)+ assert attrs["gen_ai.agent.num_turns"] == 3++ def test_duration_ms_set(self):+ _, attrs, _ = self._call(duration_ms=5000)+ assert attrs["gen_ai.agent.duration_ms"] == 5000++ def test_duration_api_ms_set(self):+ _, attrs, _ = self._call(duration_api_ms=4000)+ assert attrs["gen_ai.agent.duration_api_ms"] == 4000++ def test_error_sets_error_type(self):+ span, attrs, _ = self._call(is_error=True, result="Something went wrong")+ assert attrs[SemanticConvention.ERROR_TYPE] == "Something went wrong"+ status = span.set_status.call_args[0][0]+ assert status.status_code == StatusCode.ERROR++ def test_success_sets_ok_status(self):+ span, _, _ = self._call(is_error=False)+ status = span.set_status.call_args[0][0]+ assert status.status_code == StatusCode.OK++ def test_output_messages_in_parts_schema(self):+ _, attrs, _ = self._call(result="The answer is 42.")+ raw = attrs.get(SemanticConvention.GEN_AI_OUTPUT_MESSAGES)+ assert raw is not None+ parsed = json.loads(raw)+ assert parsed[0]["role"] == "assistant"+ assert "parts" in parsed[0]+ assert parsed[0]["parts"][0]["type"] == "text"++ def test_returns_usage_dict(self):+ usage = _make_usage(input_tokens=500, output_tokens=200)+ _, _, result_usage = self._call(usage=usage)+ assert result_usage["input_tokens"] == 500+ assert result_usage["output_tokens"] == 200++ def test_returns_zero_usage_when_no_usage(self):+ _, _, result_usage = self._call(usage=None)+ assert result_usage["input_tokens"] == 0+ assert result_usage["output_tokens"] == 0+++# ===========================================================================+# Finalize Span & Metrics+# ===========================================================================+class TestFinalizeSpan:+ def test_sets_duration_attribute(self):+ span = MagicMock()+ metrics = {"genai_client_operation_duration": MagicMock()}+ finalize_span(span, 1000.0, metrics, False, "test", "test_app")++ attrs = _get_span_attrs(span)+ assert SemanticConvention.GEN_AI_CLIENT_OPERATION_DURATION in attrs+ duration = attrs[SemanticConvention.GEN_AI_CLIENT_OPERATION_DURATION]+ assert duration > 0++ def test_records_duration_metric(self):+ metrics = {"genai_client_operation_duration": MagicMock()}+ span = MagicMock()+ finalize_span(span, 1000.0, metrics, False, "test", "test_app")+ metrics["genai_client_operation_duration"].record.assert_called_once()++ def test_records_token_metrics(self):+ metrics = {+ "genai_client_operation_duration": MagicMock(),+ "genai_client_usage_tokens": MagicMock(),+ }+ span = MagicMock()+ finalize_span(+ span, 1000.0, metrics, False, "test", "test_app",+ input_tokens=500, output_tokens=200,+ )+ assert metrics["genai_client_usage_tokens"].record.call_count == 2++ def test_skips_metrics_when_disabled(self):+ metrics = {"genai_client_operation_duration": MagicMock()}+ span = MagicMock()+ finalize_span(span, 1000.0, metrics, True, "test", "test_app")+ metrics["genai_client_operation_duration"].record.assert_not_called()++ def test_skips_zero_token_metrics(self):+ metrics = {+ "genai_client_operation_duration": MagicMock(),+ "genai_client_usage_tokens": MagicMock(),+ }+ span = MagicMock()+ finalize_span(+ span, 1000.0, metrics, False, "test", "test_app",+ input_tokens=0, output_tokens=0,+ )+ metrics["genai_client_usage_tokens"].record.assert_not_called()+++# ===========================================================================+# Cost Calculation+# ===========================================================================+class TestCostCalculation:+ def test_no_pricing_returns_zero(self):+ from openlit.instrumentation.claude_agent_sdk.utils import _calculate_cost+ assert _calculate_cost("claude-sonnet-4-20250514", None, 100, 50) == 0++ def test_no_model_returns_zero(self):+ from openlit.instrumentation.claude_agent_sdk.utils import _calculate_cost+ assert _calculate_cost(None, {"some": "info"}, 100, 50) == 0+++# ===========================================================================+# Event Emission+# ===========================================================================+class TestEmitChatInferenceEvent:+ def test_emits_event(self):+ from openlit.instrumentation.claude_agent_sdk.utils import _emit_chat_inference_event++ event_provider = MagicMock()+ _emit_chat_inference_event(+ event_provider,+ "claude-sonnet-4-20250514",+ "msg_001",+ "sess_001",+ "stop",+ {SemanticConvention.GEN_AI_USAGE_INPUT_TOKENS: 100},+ [{"role": "user", "parts": [{"type": "text", "content": "Hi"}]}],+ [{"role": "assistant", "parts": [{"type": "text", "content": "Hello!"}]}],+ )+ event_provider.emit.assert_called_once()++ def test_no_event_when_provider_is_none(self):+ from openlit.instrumentation.claude_agent_sdk.utils import _emit_chat_inference_event++ _emit_chat_inference_event(None, "model", "id", "sess", "stop", {}, None, None)+++# ===========================================================================+# ToolSpanTracker+# ===========================================================================+class TestToolSpanTracker:+ def _make_tracker(self):+ from openlit.instrumentation.claude_agent_sdk.claude_agent_sdk import _ToolSpanTracker++ tracer = MagicMock()+ tracer.start_span.return_value = MagicMock()+ parent_span = MagicMock()+ return _ToolSpanTracker(+ tracer, parent_span, "0.1.0", "test", "test_app",+ capture_message_content=True,+ )++ def test_start_and_end_tool(self):+ tracker = self._make_tracker()+ tracker.start_tool("Bash", {"command": "ls"}, "toolu_001")+ assert "toolu_001" in tracker._in_flight++ tracker.end_tool("toolu_001", "file1.txt")+ assert "toolu_001" not in tracker._in_flight+ assert "toolu_001" in tracker._completed++ def test_end_tool_error(self):+ tracker = self._make_tracker()+ tracker.start_tool("Bash", {}, "toolu_err")+ tracker.end_tool_error("toolu_err", "command failed")++ assert "toolu_err" not in tracker._in_flight+ assert "toolu_err" in tracker._completed++ def test_end_all_cleans_up(self):+ tracker = self._make_tracker()+ tracker.start_tool("Bash", {}, "toolu_a")+ tracker.start_tool("Read", {}, "toolu_b")++ tracker.end_all()+ assert len(tracker._in_flight) == 0++ def test_end_nonexistent_is_safe(self):+ tracker = self._make_tracker()+ tracker.end_tool("nonexistent_id", "result")++ def test_completed_prevents_duplicate(self):+ tracker = self._make_tracker()+ tracker.start_tool("Bash", {}, "toolu_dedup")+ tracker.end_tool("toolu_dedup", "result")++ assert "toolu_dedup" in tracker._completed+ assert "toolu_dedup" not in tracker._in_flight+++# ===========================================================================+# SubagentSpanTracker+# ===========================================================================+class TestSubagentSpanTracker:+ def _make_tracker(self):+ from openlit.instrumentation.claude_agent_sdk.claude_agent_sdk import (+ _SubagentSpanTracker, _ToolSpanTracker,+ )++ tracer = MagicMock()+ tracer.start_span.return_value = MagicMock()+ parent_span = MagicMock()+ tool_tracker = _ToolSpanTracker(+ tracer, parent_span, "0.1.0", "test", "test_app", True,+ )+ return _SubagentSpanTracker(+ tracer, tool_tracker, "0.1.0", "test", "test_app",+ )++ def test_start_and_end_subagent(self):+ tracker = self._make_tracker()+ tracker.start_subagent("task_001", "search_agent")+ assert "task_001" in tracker._in_flight++ tracker.end_subagent("task_001")+ assert "task_001" not in tracker._in_flight++ def test_start_with_tool_use_id_mapping(self):+ tracker = self._make_tracker()+ tracker.start_subagent("task_001", "agent", tool_use_id="toolu_sub")+ assert tracker._tool_use_to_task["toolu_sub"] == "task_001"++ def test_get_span_for_tool_use_id(self):+ tracker = self._make_tracker()+ tracker.start_subagent("task_001", "agent", tool_use_id="toolu_sub")++ span = tracker.get_span_for_tool_use_id("toolu_sub")+ assert span is not None++ def test_get_span_for_unknown_tool_use_id(self):+ tracker = self._make_tracker()+ assert tracker.get_span_for_tool_use_id("unknown") is None++ def test_end_subagent_with_usage(self):+ tracker = self._make_tracker()+ tracker.start_subagent("task_002", "agent")++ usage = {"total_tokens": 1000, "tool_uses": 3, "duration_ms": 5000}+ tracker.end_subagent("task_002", usage=usage)++ assert "task_002" not in tracker._in_flight++ def test_end_subagent_with_error(self):+ tracker = self._make_tracker()+ tracker.start_subagent("task_err", "agent")+ tracker.end_subagent("task_err", is_error=True, error_message="task failed")+ assert "task_err" not in tracker._in_flight++ def test_end_all_cleans_up(self):+ tracker = self._make_tracker()+ tracker.start_subagent("t1", "a1")+ tracker.start_subagent("t2", "a2")+ tracker.end_all()+ assert len(tracker._in_flight) == 0++ def test_subagent_span_has_gen_ai_system(self):+ tracker = self._make_tracker()+ tracker.start_subagent("task_sys", "agent")+ span = tracker._in_flight["task_sys"]+ span.set_attribute.assert_any_call(GEN_AI_SYSTEM_ATTR, "anthropic")+++# ===========================================================================+# Deferred Chat Span (buffer / flush)+# ===========================================================================+class TestBufferChatMessage:+ """Tests for _buffer_chat_message — deferred chat span buffering."""++ def _call(self, message, chat_state=None):+ from openlit.instrumentation.claude_agent_sdk.claude_agent_sdk import (+ _buffer_chat_message,+ )+ if chat_state is None:+ chat_state = {"last_boundary_ns": 1_000_000}+ _buffer_chat_message(message, chat_state)+ return chat_state++ def test_buffers_message_with_llm_call_data(self):+ msg = _make_assistant_message(usage=_make_usage(), content=[_make_text_block("Hi")])+ state = self._call(msg)+ assert state["pending_chat_msg"] is msg+ assert state["pending_chat_msg_id"] == "msg_001"+ assert "pending_end_ns" in state++ def test_replaces_on_same_message_id(self):+ msg1 = _make_assistant_message(+ usage=_make_usage(), content=[_make_text_block("Sure!")], message_id="msg_X",+ )+ msg2 = _make_assistant_message(+ usage=_make_usage(),+ content=[_make_tool_use_block("Bash", {"command": "ls"}, "toolu_001")],+ message_id="msg_X",+ )+ state = {"last_boundary_ns": 1_000_000}+ self._call(msg1, state)+ assert state["pending_chat_msg"] is msg1++ self._call(msg2, state)+ assert state["pending_chat_msg"] is msg2++ def test_skips_message_without_llm_call_data(self):+ msg = _make_assistant_message(usage=None)+ state = {"last_boundary_ns": 1_000_000}+ self._call(msg, state)+ assert "pending_chat_msg" not in state+++class TestFlushPendingChat:+ """Tests for _flush_pending_chat — creates a chat span from the buffer."""++ def _flush(self, chat_state, **overrides):+ from openlit.instrumentation.claude_agent_sdk.claude_agent_sdk import (+ _flush_pending_chat,+ )+ tracer = overrides.pop("tracer", MagicMock())+ span = MagicMock()+ tracer.start_span.return_value = span++ _flush_pending_chat(+ tracer=tracer,+ parent_span=overrides.pop("parent_span", MagicMock()),+ chat_state=chat_state,+ capture_message_content=overrides.pop("capture_message_content", True),+ version=overrides.pop("version", "0.1.0"),+ environment=overrides.pop("environment", "test"),+ application_name=overrides.pop("application_name", "test_app"),+ pricing_info=overrides.pop("pricing_info", None),+ event_provider=overrides.pop("event_provider", None),+ subagent_tracker=overrides.pop("subagent_tracker", None),+ )+ return tracer, span++ def test_creates_span_when_buffer_present(self):+ msg = _make_assistant_message(+ usage=_make_usage(), content=[_make_text_block("Hello")],+ )+ state = {+ "last_boundary_ns": 1_000_000,+ "pending_chat_msg": msg,+ "pending_chat_msg_id": "msg_001",+ "pending_end_ns": 2_000_000,+ }+ tracer, span = self._flush(state)++ tracer.start_span.assert_called_once()+ call_kwargs = tracer.start_span.call_args+ assert "chat" in call_kwargs[0][0]+ assert call_kwargs[1]["start_time"] == 1_000_000++ span.end.assert_called_once_with(end_time=2_000_000)++ def test_clears_buffer_after_flush(self):+ msg = _make_assistant_message(usage=_make_usage(), content=[_make_text_block("Hi")])+ state = {+ "last_boundary_ns": 1_000_000,+ "pending_chat_msg": msg,+ "pending_chat_msg_id": "msg_001",+ "pending_end_ns": 2_000_000,+ }+ self._flush(state)++ assert "pending_chat_msg" not in state+ assert "pending_chat_msg_id" not in state+ assert "pending_end_ns" not in state++ def test_updates_last_boundary_ns(self):+ msg = _make_assistant_message(usage=_make_usage(), content=[_make_text_block("Hi")])+ state = {+ "last_boundary_ns": 1_000_000,+ "pending_chat_msg": msg,+ "pending_chat_msg_id": "msg_001",+ "pending_end_ns": 5_000_000,+ }+ self._flush(state)+ assert state["last_boundary_ns"] == 5_000_000++ def test_noop_when_no_buffer(self):+ state = {"last_boundary_ns": 1_000_000}+ tracer, _ = self._flush(state)+ tracer.start_span.assert_not_called()++ def test_consumes_pending_input(self):+ msg = _make_assistant_message(usage=_make_usage(), content=[_make_text_block("Hi")])+ pending_input = [{"role": "user", "parts": [{"type": "text", "content": "Hello"}]}]+ state = {+ "last_boundary_ns": 1_000_000,+ "pending_chat_msg": msg,+ "pending_chat_msg_id": "msg_001",+ "pending_end_ns": 2_000_000,+ "pending_input": pending_input,+ }+ self._flush(state)+ assert "pending_input" not in state+++class TestProcessMessageFlushTriggers:+ """Tests that _process_message triggers flush at the right boundaries."""++ def _make_deps(self):+ from openlit.instrumentation.claude_agent_sdk.claude_agent_sdk import (+ _ToolSpanTracker, _SubagentSpanTracker,+ )+ tracer = MagicMock()+ tracer.start_span.return_value = MagicMock()+ parent_span = MagicMock()+ tool_tracker = _ToolSpanTracker(+ tracer, parent_span, "0.1.0", "test", "test_app", True,+ )+ subagent_tracker = _SubagentSpanTracker(+ tracer, tool_tracker, "0.1.0", "test", "test_app",+ )+ return tracer, parent_span, tool_tracker, subagent_tracker++ def _process(self, message, chat_state=None):+ from openlit.instrumentation.claude_agent_sdk.claude_agent_sdk import (+ _process_message,+ )+ tracer, parent_span, tool_tracker, subagent_tracker = self._make_deps()+ if chat_state is None:+ chat_state = {"last_boundary_ns": 1_000_000}+ result = _process_message(+ message, parent_span, tool_tracker, subagent_tracker,+ capture_message_content=True, tracer=tracer, chat_state=chat_state,+ version="0.1.0", environment="test", application_name="test_app",+ )+ return tracer, chat_state, result++ def test_assistant_message_buffers_not_flushes(self):+ msg = _make_assistant_message(+ usage=_make_usage(), content=[_make_text_block("Hello")],+ )+ tracer, state, _ = self._process(msg)+ assert "pending_chat_msg" in state+ assert tracer.start_span.call_count == 0++ def test_user_message_flushes_pending_chat(self):+ buffered_msg = _make_assistant_message(+ usage=_make_usage(), content=[_make_text_block("Planning...")],+ message_id="msg_A",+ )+ state = {+ "last_boundary_ns": 1_000_000,+ "pending_chat_msg": buffered_msg,+ "pending_chat_msg_id": "msg_A",+ "pending_end_ns": 2_000_000,+ }+ user_msg = _make_user_message(content=[+ _make_tool_result_block("toolu_001", "result_data"),+ ])+ tracer, state, _ = self._process(user_msg, chat_state=state)+ tracer.start_span.assert_called_once()+ assert "pending_chat_msg" not in state++ def test_result_message_flushes_pending_chat(self):+ buffered_msg = _make_assistant_message(+ usage=_make_usage(), content=[_make_text_block("Summary")],+ message_id="msg_B",+ )+ state = {+ "last_boundary_ns": 1_000_000,+ "pending_chat_msg": buffered_msg,+ "pending_chat_msg_id": "msg_B",+ "pending_end_ns": 3_000_000,+ }+ result_msg = _make_result_message()+ tracer, state, _ = self._process(result_msg, chat_state=state)+ tracer.start_span.assert_called_once()++ def test_different_message_id_flushes_previous(self):+ msg1 = _make_assistant_message(+ usage=_make_usage(), content=[_make_text_block("First")],+ message_id="msg_1",+ )+ state = {+ "last_boundary_ns": 1_000_000,+ "pending_chat_msg": msg1,+ "pending_chat_msg_id": "msg_1",+ "pending_end_ns": 2_000_000,+ }+ msg2 = _make_assistant_message(+ usage=_make_usage(), content=[_make_text_block("Second")],+ message_id="msg_2",+ )+ tracer, state, _ = self._process(msg2, chat_state=state)+ tracer.start_span.assert_called_once()+ assert state["pending_chat_msg"] is msg2+ assert state["pending_chat_msg_id"] == "msg_2"++ def test_same_message_id_replaces_buffer(self):+ msg1 = _make_assistant_message(+ usage=_make_usage(), content=[_make_text_block("Text only")],+ message_id="msg_same",+ )+ state = {+ "last_boundary_ns": 1_000_000,+ "pending_chat_msg": msg1,+ "pending_chat_msg_id": "msg_same",+ "pending_end_ns": 2_000_000,+ }+ msg2 = _make_assistant_message(+ usage=_make_usage(),+ content=[_make_tool_use_block("Bash", {"command": "ls"}, "toolu_X")],+ message_id="msg_same",+ )+ tracer, state, _ = self._process(msg2, chat_state=state)+ tracer.start_span.assert_not_called()+ assert state["pending_chat_msg"] is msg2+++# ===========================================================================+# Instrumentor Imports+# ===========================================================================+class TestInstrumentorImport:+ def test_import_instrumentor(self):+ from openlit.instrumentation.claude_agent_sdk import ClaudeAgentSDKInstrumentor+ assert ClaudeAgentSDKInstrumentor is not None++ def test_import_utils(self):+ from openlit.instrumentation.claude_agent_sdk import utils+ assert hasattr(utils, "OPERATION_MAP")+ assert hasattr(utils, "extract_usage")+ assert hasattr(utils, "set_chat_span_attributes")+ assert hasattr(utils, "set_tool_span_attributes")++ def test_import_wrapper_functions(self):+ from openlit.instrumentation.claude_agent_sdk.claude_agent_sdk import (+ wrap_query,+ wrap_connect,+ wrap_client_query,+ wrap_receive_response,+ )+ assert wrap_query is not None+ assert wrap_connect is not None+ assert wrap_client_query is not None+ assert wrap_receive_response is not None+++# ===========================================================================+# Input Message Schema (tool_call_response)+# ===========================================================================+class TestInputMessageSchema:+ def test_tool_result_follows_otel_schema(self):+ msg = _make_user_message(content=[+ _make_tool_result_block("toolu_001", "file1.txt\nfile2.txt"),+ ])+ result = build_input_from_tool_results(msg)++ assert result[0]["role"] == "user"+ part = result[0]["parts"][0]+ assert part["type"] == "tool_call_response"+ assert part["id"] == "toolu_001"+ assert "file1.txt" in part["response"]++ def test_multiple_tool_results(self):+ msg = _make_user_message(content=[+ _make_tool_result_block("toolu_a", "res_a"),+ _make_tool_result_block("toolu_b", "res_b"),+ ])+ result = build_input_from_tool_results(msg)+ parts = result[0]["parts"]++ assert len(parts) == 2+ assert parts[0]["id"] == "toolu_a"+ assert parts[1]["id"] == "toolu_b"+++# ===========================================================================+# Metrics Recording Detail+# ===========================================================================+class TestRecordMetrics:+ def test_token_usage_has_type_dimension(self):+ from openlit.instrumentation.claude_agent_sdk.utils import _record_metrics++ metrics = {+ "genai_client_operation_duration": MagicMock(),+ "genai_client_usage_tokens": MagicMock(),+ }+ _record_metrics(+ metrics, SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,+ 1.5, "test", "test_app",+ input_tokens=500, output_tokens=200,+ )++ token_calls = metrics["genai_client_usage_tokens"].record.call_args_list+ assert len(token_calls) == 2++ input_call_attrs = token_calls[0][0][1]+ assert input_call_attrs[SemanticConvention.GEN_AI_TOKEN_TYPE] == SemanticConvention.GEN_AI_TOKEN_TYPE_INPUT++ output_call_attrs = token_calls[1][0][1]+ assert output_call_attrs[SemanticConvention.GEN_AI_TOKEN_TYPE] == SemanticConvention.GEN_AI_TOKEN_TYPE_OUTPUT++ def test_metrics_include_gen_ai_system(self):+ from openlit.instrumentation.claude_agent_sdk.utils import _record_metrics++ metrics = {"genai_client_operation_duration": MagicMock()}+ _record_metrics(+ metrics, SemanticConvention.GEN_AI_OPERATION_TYPE_AGENT,+ 1.0, "test", "test_app",+ )++ call_attrs = metrics["genai_client_operation_duration"].record.call_args[0][1]+ assert call_attrs[GEN_AI_SYSTEM_ATTR] == "anthropic"+++if __name__ == "__main__":+ pytest.main([__file__, "-v"])