eldros-sdk 0.2.0

OpenTelemetry-native tracing SDK for Eldros AI agents

eldros-sdk

OpenTelemetry-native tracing SDK for Eldros AI agents. One init() call resolves your trace config from the Eldros platform, wires up OpenTelemetry, and auto-instruments your LLM provider clients. Drop a @trace decorator on your handler and you get a root span per call.

You need exactly one thing: an Eldros API key (agt_...). The SDK resolves trace config from the Eldros platform at startup — you never configure the trace backend directly.

Install

pip install eldros-sdk              # core
pip install "eldros-sdk[claude-agent-sdk]"    # + Claude Agent SDK instrumentation via LangSmith
pip install "eldros-sdk[openai]"    # + OpenAI auto-instrumentation
pip install "eldros-sdk[anthropic]" # + Anthropic auto-instrumentation
pip install "eldros-sdk[all]"       # everything

Quick start

export ELDROS_API_KEY=agt_...

from eldros_sdk import init, trace

init()   # api_key is read from ELDROS_API_KEY

@trace
async def handle_conversation(user_message: str) -> str:
    # OpenAI / Anthropic calls in here are auto-instrumented as child spans.
    ...

init() blocks briefly at startup to call the Eldros platform and fetch your trace config — call it before starting your event loop (e.g. at module import time or in your if __name__ == "__main__" block).

Configuration

Every argument can come from an environment variable. Explicit init(...) kwargs win over env vars.

init() arg	Env var	Default
api_key	ELDROS_API_KEY	— (required)
api_base_url	ELDROS_API_BASE_URL	— (required until official domain is live)
traffic_type / env	ELDROS_TRAFFIC_TYPE	prod
instrument_claude_agent_sdk	ELDROS_INSTRUMENT_CLAUDE_AGENT_SDK	auto-detected (True if claude_agent_sdk installed)
instrument_openai	ELDROS_INSTRUMENT_OPENAI	auto-detected (True if [openai] extra installed)
instrument_anthropic	ELDROS_INSTRUMENT_ANTHROPIC	auto-detected (True if [anthropic] extra installed)
capture_content	ELDROS_CAPTURE_CONTENT	true
debug	ELDROS_TRACE_DEBUG	false
enabled	ELDROS_TRACE_ENABLED	true

• enabled=False makes the whole SDK a no-op — safe to leave in any environment.
• debug=True (or ELDROS_TRACE_DEBUG=true) also prints spans to the console.
• capture_content=False strips prompt/response text from OpenAI and Anthropic spans. Note: for Claude Agent SDK, LangSmith always captures content regardless of this setting.

Decorator options

@trace(name="checkout", capture_io=True, attributes={"tier": "pro"})
def run(payload: dict) -> dict:
    ...

@trace supports sync functions, coroutines, sync generators, and async generators (the span stays open across the whole generation).

Claude Agent SDK instrumentation

Install the [claude-agent-sdk] extra — instrumentation is automatic:

pip install "eldros-sdk[claude-agent-sdk]"

import eldros_sdk

eldros_sdk.init()  # auto-detects claude-agent-sdk and instruments it

init() is the single entry point. LangSmith patches ClaudeSDKClient and routes spans through the global TracerProvider — alongside @trace and LLM spans. Requires ClaudeSDKClient (not the module-level query()).

To opt out: init(instrument_claude_agent_sdk=False).

If LANGSMITH_API_KEY is also set, traces go to both your LangSmith account and Eldros's trace backend simultaneously (hybrid mode).

Lifecycle

from eldros_sdk import flush, shutdown

flush()      # force-export buffered spans (e.g. end of a serverless invocation)
shutdown()   # flush + tear down the provider

Testing the SDK

# Verify credential resolution
ELDROS_API_KEY=agt_... python3 -c "
import eldros_sdk
cfg = eldros_sdk.init()
print('has_trace_config:', cfg.has_trace_config)
"

# Verify a span reaches your trace backend
ELDROS_API_KEY=agt_... python3 -c "
import eldros_sdk
eldros_sdk.init(debug=True)

@eldros_sdk.trace
def hello():
    return 'world'

hello()
eldros_sdk.flush()
print('done — check your trace backend')
"

Design notes

• Credential resolution. On init(), the SDK calls GET {api_base_url}/resolve with your ELDROS_API_KEY in the X-Client-API-Key header and receives {endpoint, headers, project, backend}. The SDK applies these blindly to the OTLP exporter — no backend-specific logic.
• OTLP/HTTP. No vendor SDK dependency — spans are exported as OTel protobuf over HTTP.
• Additive OTel. If a TracerProvider already exists (Datadog, etc.) the SDK attaches its exporter to it instead of replacing it — spans flow to both destinations. Call init() before any other tracing setup so the SDK's provider is detected first.
• Claude Agent SDK spans use the global provider. LangSmith detects the global TracerProvider set by init() and routes all Claude Agent SDK OTel spans through it. This means any SpanProcessor you add to the global provider also receives those spans — you can route to your own trace backend or any OTel backend alongside ours.
• Auto-instrumentation is optional. Provider instrumentors are extras; if a provider library isn't installed the SDK logs and continues.
• Safe by default. Spans are non-recording until init() runs, so @trace never breaks code even if init() is missing.