struct-sdk 0.2.27

The release of struct-sdk version 0.2.27 marks a significant advancement in the integration of OpenTelemetry instrumentation specifically tailored for AI agents in Python. This SDK is designed to capture critical performance metrics, including spans, token usage, and message events from various AI frameworks such as the Anthropic SDK, the OpenAI SDK (Responses API), the Claude Agent SDK, and LangChain/LangGraph. The captured data is subsequently exported to struct.ai, enhancing observability for developers and technologists working with AI systems.

Key Features of struct-sdk 0.2.27

One of the standout features of struct-sdk is its compatibility with both Python and TypeScript environments. The TypeScript version, available as @struct-ai/sdk, ensures that both SDKs produce structurally identical traces. This uniformity allows developers to mix languages within a single agent system without losing a coherent view of the performance data, thereby streamlining the development and debugging processes across different programming environments.

To begin using struct-sdk, developers must obtain an ingest key from app.struct.ai/settings?tab=ingest-keys. The initialization process is straightforward: developers need to call struct.init() once during the startup phase of their application. This function requires the ingest_key as a mandatory parameter, while the service_name and environment are recommended for better context. It is crucial to call struct.init() early, ideally before importing any instrumented libraries, to ensure comprehensive data capture from the outset.

The SDK is designed to accommodate both agent frameworks, which have built-in concepts of agents and tools, and direct interactions with LLM SDKs that primarily handle chat completions. While the SDK automatically instruments both types of frameworks, it is important to note that only agent frameworks will generate full spans for agents and tools without additional configuration. When using LLM SDKs directly, developers must explicitly define the boundaries of agents and tools to ensure accurate data capture.

For developers engaged in multi-turn HTTP-style interactions, struct-sdk provides a robust solution. By wrapping the request handler in struct.agent(session_id=conversation_id), developers can maintain conversation context seamlessly. This method serves as a native replacement for previous context management techniques and offers enhanced tracking capabilities that go beyond what configurable.thread_id can provide. Additionally, struct.agent() can function as a synchronous context manager, which is beneficial for non-async request handlers.

When integrating with LLM SDKs directly, developers will find that only chat spans are emitted automatically. To capture agent and tool boundaries effectively, it is necessary to wrap the agent loop in struct.agent() and each tool execution in struct.tool(). This requirement ensures that the SDK properly associates spans with their respective agents and tools, preventing the occurrence of uncontextualized chat spans.

The SDK also supports dynamic dispatch, allowing LLMs to select tools from a registry at runtime. Developers can apply the struct.tool() decorator during runtime, simplifying the instrumentation process. However, it is advisable to use the decorator for actual tool calls, as using struct.tool() as a context manager does not automatically capture arguments or results.

Instrumentation and Error Handling

The struct-sdk 0.2.27 incorporates sophisticated error handling mechanisms. It emits two distinct types of error values alongside the span StatusCode.ERROR: tool_error and a general exception class name. This differentiation allows monitoring systems to focus on genuine execution failures while filtering out recoverable errors that the model may encounter. Such a design choice enhances the reliability of the monitoring process, ensuring that developers can trust the performance metrics being reported.

Furthermore, the SDK is built to be non-disruptive to existing applications. It utilizes an isolated TracerProvider and LoggerProvider, meaning that any existing OpenTelemetry setup remains unaffected. The SDK is designed to handle exceptions gracefully, logging the first failure at each site at a WARN level and subsequent failures at a DEBUG level. The shutdown process is also optimized to prevent slow or unreachable ingest endpoints from causing application hangs, running in a background thread to ensure smooth operation.

In terms of provenance, struct-sdk adheres to the standards set by PyPI, providing verifiable records of build and publishing details through attestations. This feature enhances trust in the artifacts being used, as it allows developers to confirm the origins of the SDK they are implementing.

Why it matters

The release of struct-sdk 0.2.27 is particularly significant for creators and technologists in the AI space. As AI systems become increasingly complex, the need for robust observability tools becomes paramount. This SDK not only simplifies the process of capturing performance metrics but also enhances the ability to monitor and debug AI agents across different programming languages. By providing a unified approach to instrumentation, struct-sdk empowers developers to build more reliable and efficient AI applications, ultimately fostering innovation in the field. The seamless integration with existing frameworks and the emphasis on error handling further solidify its value proposition, making it an essential tool for any developer working with AI agents.