struct-sdk 0.3.2__tar.gz → 0.4.13__tar.gz

{struct_sdk-0.3.2 → struct_sdk-0.4.13}/.gitignore

@@ -118,3 +118,6 @@ struct-agent-key.json
 
 # Local/CI test result artifacts
 **/test-results/
+
+# Generated agent session project ledgers (data, HTML and local helper state)
+.project-ledgers/

{struct_sdk-0.3.2 → struct_sdk-0.4.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: struct-sdk
-Version: 0.3.2
+Version: 0.4.13
 Summary: Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry
 Project-URL: Homepage, https://struct.ai
 Project-URL: Documentation, https://struct.ai/docs
@@ -24,6 +24,7 @@ Requires-Python: >=3.10
 Requires-Dist: opentelemetry-api>=1.45.1
 Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0
 Requires-Dist: opentelemetry-sdk>=1.27.0
+Requires-Dist: wrapt>=1.16.0
 Provides-Extra: anthropic
 Requires-Dist: anthropic>=0.30.0; extra == 'anthropic'
 Provides-Extra: auto
@@ -69,6 +70,9 @@ Requires-Dist: opentelemetry-instrumentation-urllib; extra == 'auto'
 Requires-Dist: opentelemetry-instrumentation-urllib3; extra == 'auto'
 Requires-Dist: opentelemetry-instrumentation>=0.51b0; extra == 'auto'
 Requires-Dist: opentelemetry-resource-detector-containerid; extra == 'auto'
+Provides-Extra: autogen
+Requires-Dist: autogen-agentchat>=0.7.0; extra == 'autogen'
+Requires-Dist: autogen-ext[openai]>=0.7.0; extra == 'autogen'
 Provides-Extra: azure
 Requires-Dist: azure-core-tracing-opentelemetry>=1.0.0b11; extra == 'azure'
 Provides-Extra: claude-agent-sdk
@@ -88,10 +92,20 @@ Requires-Dist: pytest>=9.0.3; extra == 'dev'
 Requires-Dist: ruff>=0.5; extra == 'dev'
 Provides-Extra: exceptions
 Requires-Dist: opentelemetry-instrumentation-exceptions; extra == 'exceptions'
+Provides-Extra: google-genai
+Requires-Dist: google-genai>=1.12.1; extra == 'google-genai'
 Provides-Extra: langchain
 Requires-Dist: langchain-core>=1.3.3; extra == 'langchain'
+Provides-Extra: litellm
+Requires-Dist: litellm[mcp]>=1.70.0; extra == 'litellm'
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.13.0; extra == 'llamaindex'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.28.1; extra == 'mcp'
 Provides-Extra: openai
 Requires-Dist: openai>=1.66.0; extra == 'openai'
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.20.0; extra == 'openai-agents'
 Provides-Extra: pydantic-ai
 Requires-Dist: pydantic-ai-slim>=2.53.0; extra == 'pydantic-ai'
 Provides-Extra: structlog
@@ -103,9 +117,9 @@ Description-Content-Type: text/markdown
 # struct-sdk
 
 OpenTelemetry instrumentation for AI agents in Python. Captures spans,
-token usage, and message events from the Anthropic SDK, the OpenAI SDK
-(Responses API), pydantic-ai, the Claude Agent SDK, and LangChain /
-LangGraph, and exports them to [struct.ai](https://struct.ai) for observability.
+token usage, and message content from the Anthropic SDK, the OpenAI SDK
+(Responses API), google-genai (Gemini), LiteLLM, pydantic-ai, the OpenAI Agents SDK, MCP clients, the Claude Agent SDK,
+LangChain / LangGraph, LlamaIndex, CrewAI, Microsoft AutoGen, and AG2, and exports them to [struct.ai](https://struct.ai) for observability.
 
 A TypeScript version is available as
 [`@struct-ai/sdk`](https://www.npmjs.com/package/@struct-ai/sdk). Both
@@ -120,8 +134,13 @@ pip install struct-sdk
 pip install anthropic
 pip install openai
 pip install pydantic-ai-slim
+pip install openai-agents
+pip install mcp
+pip install google-genai
+pip install "litellm[mcp]"   # LiteLLM needs mcp for calls with tools
 pip install claude-agent-sdk
 pip install langchain-core langgraph
+pip install llama-index-core llama-index-llms-openai   # or the provider integration you use
 ```
 
 Requires Python 3.10+.
@@ -164,8 +183,16 @@ async with struct.agent(name="checkout"):
 | Library | Span type | Notes |
 |---|---|---|
 | `anthropic` | `chat {model}` | Cache-token accounting; streaming chats with tool-use reconstruction. Bedrock and Vertex variants supported if installed. |
-| `openai` (Responses API) | `chat {model}` | Non-streaming `responses.create` on sync and async clients (Azure clients included). Cached-token accounting from `usage.input_tokens_details`. Streaming and `chat.completions` calls pass through untraced. Message-content capture at parity with the Anthropic integration: per-message events (`gen_ai.system/user/assistant/tool.message`) and `gen_ai.choice`, plus `gen_ai.input.messages` / `gen_ai.output.messages` in span-content mode. Reasoning items are skipped (`encrypted_content` is never emitted). |
+| `openai` (Responses and Chat Completions) | `chat {model}` | `responses.create` and `chat.completions.create` on sync and async clients, streaming or not, including the `.stream()` helpers (Azure and OpenAI-compatible clients such as vLLM, Groq, DeepSeek and xAI included). Raw `create(stream=True)` spans end exactly once on exhaustion, `close()`, `with` exit, error, cancellation or garbage collection; every loop over a stream shares one iteration (LiteLLM starts one per chunk), so a `break` ends the span when it releases the stream. Helper streams that exit early end when the helper is released. Chat Completions streamed usage is recorded when you pass `stream_options={"include_usage": True}`; Responses records terminal usage without that option. The SDK never changes your request. Cached-token accounting from the usage details. Message-content capture at parity with the Anthropic integration: in event modes, one `gen_ai.client.inference.operation.details` record per call (one output message per choice; for a stream, written when the stream ends); in span modes, `gen_ai.input.messages` / `gen_ai.output.messages` on the span. Reasoning items are skipped (`encrypted_content` is never emitted). `chat.completions.parse()` and `responses.parse()` calls are not traced. |
 | `pydantic_ai` | `invoke_agent {agent}`, `chat {model}`, `execute_tool {tool}` | pydantic-ai's own instrumentation, turned on with Struct's tracer provider. See [pydantic-ai](#pydantic-ai). |
+| `agents` (OpenAI Agents SDK) | `invoke_agent {workflow}`, `invoke_agent {agent}`, `chat {model}`, `execute_tool {tool}` | A `TracingProcessor` added next to the host's: every run, agent, model call (Responses, Chat Completions and LiteLLM models, streamed or not), function tool and handoff. See [OpenAI Agents SDK](#openai-agents-sdk). |
+| `mcp` (`ClientSession.call_tool`) | `tools/call {tool}` | One CLIENT span per MCP tool call (`gen_ai.operation.name = execute_tool`), with the trace context sent in `params._meta`. See [MCP](#mcp). |
+| `google.genai` | `generate_content {model}` | `client.models.generate_content` and `client.aio.models.generate_content` (Gemini API → `gcp.gemini`, Vertex AI → `gcp.vertex_ai`), usage with cached and thinking tokens. Streams pass through untraced. Google ADK's own spans own its model calls. See [Gemini and Google ADK](#gemini-and-google-adk). |
+| `litellm` | `chat {model}` | Non-streaming `litellm.completion` / `litellm.acompletion`, including each `Router` attempt. Model without LiteLLM's `provider/` prefix; `gen_ai.provider.name` in GenAI naming (`aws.bedrock`, `gcp.vertex_ai`, `azure.ai.openai`, …). Usage with cache reads, cache writes and reasoning tokens. Streams get no LiteLLM span (on LiteLLM's OpenAI provider the `openai` patch traces them). See [LiteLLM](#litellm). |
+| `llama_index` | `invoke_agent`, `chat`, `execute_tool`, `retrieval` | Workflow agent runs (`FunctionAgent`, `ReActAgent`, `AgentWorkflow`), LLM chats (sync, async, streamed), tool calls and retrievers, through LlamaIndex's instrumentation dispatcher. The provider SDK span under a LlamaIndex chat is suppressed. See [LlamaIndex](#llamaindex). |
+| `crewai` (1.15.13+) | `invoke_agent`, `chat`, `execute_tool` | Crew kickoffs and agent executions, model calls (native providers or LiteLLM) and tool calls, from CrewAI's event bus. The provider SDK span under a CrewAI model call is suppressed. See [CrewAI](#crewai). |
+| `autogen_ext` (AutoGen 0.7+) | `chat {model}` | AutoGen traces its own agents and tools; Struct adds a `chat` span for each non-streaming call through the OpenAI-family clients (`OpenAIChatCompletionClient`, Azure, OpenAI-compatible endpoints). In owned full-app mode, Struct also stamps the `struct.agent()` session on AutoGen's spans. AutoGen's Anthropic client is covered by the `anthropic` integration. See [AutoGen](#autogen). |
+| `autogen` (AG2 0.x) | `chat {model}`, `execute_tool {name}` | Every `OpenAIWrapper.create` model call and `ConversableAgent` tool execution. AG2's own instrumentation, when you turn it on, owns those calls instead. See [AG2](#ag2). |
 | `claude_agent_sdk` | `agent`, `chat`, `execute_tool` | Telemetry comes from Claude Code itself in the subprocess; ingest credentials are propagated to it via `ClaudeAgentOptions`. Subagents inherit the configuration. |
 | `langchain_core` `BaseChatModel` | `chat {model}` | When the underlying provider SDK is also instrumented (e.g. `ChatAnthropic` + `anthropic`), the provider's span is suppressed, so there is a single span. |
 | `langchain_core` `BaseTool` | `execute_tool {name}` | `tool_call_id` extracted from the LangChain ToolCall when present. |
@@ -227,10 +254,9 @@ calls your code makes while reading a stream keep their spans). During agent
 runs, Struct guards telemetry faults and caps content. Realtime sessions and
 direct `InstrumentedModel` exception recording are outside this guarantee.
 
-- **Content** goes on span attributes only (pydantic-ai has no message
-  events): `span_only` / `span_and_event` include prompts, answers and tool
-  arguments; `event_only` and `none` do not. Tool definitions are always
-  recorded.
+- **Content:** in event modes, each chat call's messages go to one
+  `operation.details` event. Span modes keep chat content on spans. Tool
+  arguments and results remain on `execute_tool` spans in every mode but `none`.
 - **Sessions:** on Struct's provider, a `struct.agent(session_id=...)`
   around the run wins; otherwise pydantic-ai's `conversation_id` is used.
   Instrumentation configured on your own provider keeps its conversation IDs.
@@ -240,6 +266,185 @@ direct `InstrumentedModel` exception recording are outside this guarantee.
   `Agent.instrument_all(False)` before `struct.init()` is pydantic-ai's
   initial value, so it does not keep pydantic-ai off.
 
+#### OpenAI Agents SDK
+
+```python
+from struct_sdk import struct
+struct.init(ingest_key="pk-...", service_name="support-agents")
+
+from agents import Agent, Runner, RunConfig
+result = await Runner.run(triage_agent, "Refund order 42",
+                          run_config=RunConfig(group_id=conversation_id))
+```
+
+`struct.init()` adds a tracing processor to the Agents SDK
+(`add_trace_processor`), so OpenAI's own trace upload keeps working. Each
+run is one trace:
+
+```
+invoke_agent Agent workflow          # the run (RunConfig.workflow_name)
+├── invoke_agent Triage              # each agent that ran
+│   ├── chat gpt-5.4-mini            # each model call, with usage
+│   ├── execute_tool get_weather     # each function tool, with its call id
+│   └── execute_tool transfer_to_billing   # a handoff is a tool call
+└── invoke_agent Billing
+    └── chat gpt-5.4-mini
+```
+
+- **Sessions.** `RunConfig(group_id=...)` becomes `gen_ai.conversation.id`.
+  Wrapping the run in `struct.agent(session_id=...)` makes that span the
+  run's root instead (no separate `invoke_agent Agent workflow`) and its
+  session wins.
+- **One span per model call.** The processor owns `chat` spans, including
+  streamed runs; the OpenAI patch makes no span of its own while it does,
+  only recording the requested model, which the Agents SDK's Responses
+  spans do not carry. Non-streamed Chat Completions and LiteLLM model spans
+  have no response id or model (the Agents SDK records only the message).
+- **Nesting.** While a tool or model call runs, its span is the current
+  OpenTelemetry span, so your own spans inside a tool (and HTTP client
+  spans in full-app mode) nest under it.
+- **Content** needs both switches on: the Agents SDK's
+  `trace_include_sensitive_data` (on by default) and a Struct
+  `content_capture` mode other than `none`. Usage is always recorded.
+- **Turning Agents tracing off** (`OPENAI_AGENTS_DISABLE_TRACING=1`,
+  `RunConfig(tracing_disabled=True)`) also removes Struct's agent and tool
+  spans; only the OpenAI patch's `chat` spans for non-streamed calls
+  remain. To stop only the upload to OpenAI, replace the processor list
+  and keep Struct's:
+
+  ```python
+  from agents import set_trace_processors
+  from struct_sdk.openai_agents import get_tracing_processor
+  set_trace_processors([get_tracing_processor()])  # after struct.init()
+  ```
+
+#### Gemini and Google ADK
+
+```python
+from struct_sdk import struct
+struct.init(ingest_key="pk-...", service_name="planner")
+
+from google import genai
+client = genai.Client()  # or genai.Client(vertexai=True, project=..., location=...)
+response = client.models.generate_content(model="gemini-3.1-flash-lite", contents="Plan my day")
+```
+
+Each `generate_content` call (sync or `client.aio`) is a
+`generate_content {model}` span. Wrap your loop in `struct.agent()` and
+your tools in `struct.tool()` as for the other LLM SDKs.
+
+Google ADK traces itself (agents, tools and model calls) through the
+global OpenTelemetry provider, which Struct owns or attaches to in the
+default full-app mode, so ADK runs need no extra setup; Struct adds no
+second span for a model call ADK already traces. With
+`auto_instrument=False` and no host OpenTelemetry, Struct sees ADK's
+model calls but not its agent and tool spans. ADK puts message content in its spans by default; set
+ADK's own `ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false` to stop that.
+
+If you install `opentelemetry-instrumentation-google-genai` yourself,
+Struct leaves google-genai to it. Default full-app mode also leaves Datadog-owned
+google-genai bindings alone; explicit AI-only mode retains Struct’s isolated
+instrumentation.
+
+#### LlamaIndex
+
+```python
+from struct_sdk import struct
+struct.init(ingest_key="pk-...", service_name="my-agent")
+
+from llama_index.core.agent.workflow import FunctionAgent
+from llama_index.llms.openai import OpenAI
+
+llm = OpenAI(
+    model="gpt-4.1-mini",
+    # Streamed calls report token usage only when asked to.
+    additional_kwargs={"stream_options": {"include_usage": True}},
+)
+agent = FunctionAgent(name="weather", tools=[...], llm=llm)
+result = await agent.run(user_msg="Weather in Paris?")
+```
+
+Each run is an `invoke_agent` span with its model calls (`chat`), tool
+calls (`execute_tool`) and retrievals (`retrieval`) under it, even though
+LlamaIndex runs workflow steps on separate tasks. Wrap the run in
+`struct.agent(session_id=...)` to group runs into a conversation.
+Completions, embeddings and query engines are not spans of their own;
+their LLM and retriever calls are.
+
+#### CrewAI
+
+```python
+from struct_sdk import struct
+struct.init(ingest_key="pk-...", service_name="my-crew")
+
+from crewai import Agent, Crew, Task
+crew = Crew(name="weather-crew", agents=[...], tasks=[...])
+with struct.agent(name="support", session_id=conversation_id):
+    crew.kickoff()
+```
+
+The crew and each agent execution are `invoke_agent` spans, with the
+agent's model calls (`chat`) and tool calls (`execute_tool`) under it,
+across the threads CrewAI runs agents and async tasks on. Agent spans are
+named by the role as configured; the resolved goal (with kickoff inputs)
+is recorded only when content is captured. A cancelled `akickoff()` (or an
+interrupted `kickoff()`) ends the run's spans as errors. Requires
+CrewAI 1.15.13 or later (older releases are left alone); there is no
+`struct-sdk[crewai]` extra. Install CrewAI separately as you already do;
+the SDK activates the integration when it is present.
+
+#### AutoGen
+
+```python
+from struct_sdk import struct
+struct.init(ingest_key="pk-...", service_name="my-agent")  # full-app mode, the default
+
+from autogen_agentchat.agents import AssistantAgent
+from autogen_ext.models.openai import OpenAIChatCompletionClient
+
+agent = AssistantAgent(name="weather", model_client=OpenAIChatCompletionClient(model="gpt-4.1-mini"), tools=[...])
+async with struct.agent(name="support", session_id=conversation_id):
+    await agent.run(task="Weather in Paris?")
+```
+
+AutoGen (0.7+) traces its agents and tools through the global
+OpenTelemetry provider, which Struct owns or attaches to in the default
+full-app mode; with `auto_instrument=False` only Struct's `chat` spans
+arrive. The `struct.agent()` session reaches AutoGen's own spans only when
+Struct owns the provider (owned full-app mode); attached to your provider,
+only Struct's `chat` spans carry it. Streamed model calls
+(`model_client_stream=True`) get no AutoGen span; the `openai` integration
+traces them. This is Microsoft AutoGen (`autogen-agentchat`), not AG2.
+
+#### AG2
+
+```python
+from struct_sdk import struct
+struct.init(ingest_key="pk-...", service_name="my-agents")
+
+from autogen import ConversableAgent
+with struct.agent(name="support", session_id=conversation_id):
+    user.initiate_chat(assistant, message="Weather in Paris?")
+```
+
+AG2 0.x (`pip install "ag2[openai]<1"`, imported as `autogen`) gets a
+`chat` span per model call and an `execute_tool` span per tool call;
+wrap the conversation in `struct.agent()` for an agent span and a
+session. The `chat` span describes the request AG2 actually sent (the
+client that answered, its merged config, instantiated templates), for
+streamed calls and the V2 clients too; Anthropic and OpenAI (Responses
+and Chat Completions) calls that are not streamed keep the provider's
+cache counts. Async chats (`a_initiate_chat`)
+run model calls on an executor thread. OTel thread instrumentation carries
+trace parentage; the wrapper can recover the session from a carried current
+Struct span. Owned full-app mode enables that instrumentor when installed;
+a host can also supply it. Without thread-context propagation, model spans
+start new traces without the session. AG2's own
+OpenTelemetry (`autogen.opentelemetry` in 0.x, `TelemetryMiddleware` in
+1.x) also works: pass it `trace.get_tracer_provider()` (Struct's in owned
+mode, yours when Struct attaches to it) and Struct stamps the session on
+its spans and adds no duplicates under them.
+
 #### LangChain / LangGraph (with an agent or graph)
 
 ```python
@@ -252,6 +457,18 @@ from langgraph.prebuilt import create_react_agent
 # execute_tool spans. BaseRetriever.invoke gets retrieval spans.
 ```
 
+- Sub-graphs and `create_agent` sub-agents nest under their parent graph;
+  `configurable.thread_id` is the session, so a run resumed after an
+  `interrupt()` stays in the same session.
+- `interrupt()` and `Command(graph=Command.PARENT)` are control flow: the
+  tool or graph span is not marked as an error.
+- While a tool runs, its `execute_tool` span is the current span: your own
+  spans inside the tool, and full-app database/HTTP spans, nest under it.
+  Cancellation restores the caller’s context even when LangChain skips its
+  end/error callbacks. Plain function nodes get no Struct span; their work
+  inherits existing host or `struct.agent()` context. Automatic graph spans
+  end on interrupt; resume starts a separate trace only without an enclosing span.
+
 ##### Recommended pattern: wrap LangChain entry points in `struct.agent`
 
 For multi-turn HTTP-style usage (every request continues the same
@@ -343,6 +560,34 @@ result = await registry[block.name](**block.input)   # arguments + result captur
 `anthropic.Anthropic`, `anthropic.AsyncAnthropic`, and the bedrock/vertex
 clients are all auto-instrumented for chat spans.
 
+#### MCP
+
+```python
+from struct_sdk import struct
+struct.init(ingest_key="pk-...", service_name="support-agent")
+
+from mcp import ClientSession
+async with struct.agent(name="support", session_id=conversation_id):
+    result = await session.call_tool("get_weather", {"city": "Paris"})
+```
+
+Every `ClientSession.call_tool` (mcp 1.x and 2.x, including the OpenAI
+Agents SDK's MCP servers) becomes a `tools/call get_weather` CLIENT span
+with `mcp.method.name`, `gen_ai.operation.name = execute_tool` and the
+request's `jsonrpc.request.id`. Its trace context is added
+to the request's `params._meta` (`traceparent`, `tracestate`, `baggage`),
+so an instrumented MCP server continues the same trace. On mcp 1.x, trace
+keys you pass in `meta` win; mcp 2.x writes the trace keys again itself on
+every transport but its in-process `Client`, from its own `MCP send`
+span when your global tracer provider records (that span is a child of
+Struct's, so the server stays in the trace). mcp before 1.19 has no `meta`
+parameter: those calls get the span without propagation.
+
+The first MCP call inside a `struct.tool()` scope is recorded on that tool
+span, including its outcome; later calls get child spans. An `isError`
+result is `error.type = tool_error`; a JSON-RPC error records its code in
+`error.type` and `rpc.response.status_code`.
+
 #### Parallel tool calls — pass `tool_call_id` explicitly
 
 When you execute an assistant turn's tool calls **sequentially** — one
@@ -396,6 +641,30 @@ When you do use `ChatAnthropic` *and* have the `anthropic` SDK installed,
 the chat span comes from the LangChain layer (single span); the Anthropic
 instrumentation skips its own to avoid duplicates.
 
+#### LiteLLM
+
+```python
+from struct_sdk import struct
+struct.init(ingest_key="pk-...", service_name="my-agent")
+
+import litellm  # wrapped on import; a `completion` imported before init() is not traced
+
+async with struct.agent(name="my-agent"):
+    response = await litellm.acompletion(model="anthropic/claude-sonnet-5", messages=[...])
+    async with struct.tool(name="search"):
+        ...
+```
+
+Each call is one `chat {model}` span, whichever provider LiteLLM routes
+to. A framework that owns the call (LangChain, pydantic-ai, the OpenAI
+Agents SDK) keeps its own span and LiteLLM adds none. LiteLLM's own
+`litellm.callbacks = ["otel"]` would add a second, LiteLLM-shaped span;
+leave it off when Struct is on. `struct.init()` does not import LiteLLM
+(its import fetches the model cost map over the network): it wraps
+`litellm.completion` and `litellm.acompletion` when your code imports
+`litellm`. `pip install "struct-sdk[litellm]"` installs LiteLLM with its
+`mcp` extra, which recent LiteLLM releases need for calls that pass `tools`.
+
 ## Content capture
 
 The SDK supports four capture modes controlling how prompt/response
@@ -411,9 +680,10 @@ struct.init(
 )
 ```
 
-- **`EVENT_ONLY`**: per-message content lands on OTel log
-  records (`gen_ai.{user,assistant,system,tool}.message`,
-  `gen_ai.choice`). Spans carry metadata only.
+- **`EVENT_ONLY`**: each model call's content lands on one OTel log record,
+  `gen_ai.client.inference.operation.details` (input and output messages,
+  system instructions, tool definitions, as structured values). Spans carry
+  metadata only.
 - **`SPAN_ONLY`**: content on span attributes (`gen_ai.input.messages`,
   `gen_ai.output.messages`).
 - **`SPAN_AND_EVENT`**: both.
@@ -484,13 +754,15 @@ Emits attributes per the OTel GenAI semantic conventions:
 
 The OTel conventions ask instrumentations to document the error values
 they report ("Instrumentations SHOULD document the list of errors they
-report"). This SDK emits exactly two kinds of value, both alongside
+report"). This SDK emits exactly four kinds of value, all alongside
 span `StatusCode.ERROR`:
 
 | Value | When | Meaning |
 | --- | --- | --- |
 | exception class name (e.g. `RuntimeError`, `httpx.ConnectError`) | the instrumented call raised | We failed to execute the request. Also records an OTel exception event. |
-| `tool_error` | an `execute_tool` span whose result signalled failure **in band** — Anthropic `tool_result` blocks with `is_error: true`, MCP `CallToolResult.isError`, or a LangChain `ToolMessage` with `status="error"` | The tool ran and reported a failure back to the model (bad arguments, a domain "no"), so the model can self-correct. No exception object exists, so no class name is available. |
+| `tool_error` | an `execute_tool` span whose result signalled failure **in band** — Anthropic `tool_result` blocks with `is_error: true`, MCP `CallToolResult.isError` (also on MCP `tools/call` spans), or a LangChain `ToolMessage` with `status="error"` | The tool ran and reported a failure back to the model (bad arguments, a domain "no"), so the model can self-correct. No exception object exists, so no class name is available. |
+| JSON-RPC error code (e.g. `-32602`) | an MCP `tools/call` span whose request got a JSON-RPC error response | Also in `rpc.response.status_code`; the status carries the error's message (MCP semantic conventions). |
+| `_OTHER` | an OpenAI Agents SDK span the Agents SDK marked as failed (a model call, tool, agent or the whole run), or one still open when its trace ended | The Agents SDK reports the failure as a message, not an exception, so no class name is available. `_OTHER` is the semantic conventions' fallback value. The message goes in the span status. |
 
 `tool_error` is a deliberate low-cardinality sentinel, which the
 `error.type` convention explicitly permits ("another low-cardinality