SDK

Python SDK

Track AI events, feedback, and traces in your Python app.

Installation

pip


pip install introspection-sdk

uv


uv add introspection-sdk

poetry


poetry add introspection-sdk

Optional extras for specific integrations:


pip install 'introspection-sdk[openai-agents]'
pip install 'introspection-sdk[langfuse]'
pip install 'introspection-sdk[braintrust]'
pip install 'introspection-sdk[arize]'

Integration	Extra dependency
Claude Agent SDK	`pip install claude-agent-sdk`
LangChain / LangGraph	`pip install langchain-core`
Langfuse / Braintrust / Arize	Install the matching extras above

Configuration


from introspection_sdk import IntrospectionClient
 
client = IntrospectionClient()

The client reads credentials from the environment by default. You can also pass them explicitly:


client = IntrospectionClient(
    token="intro_xxx",
    service_name="my-app",
    base_url="https://otel.introspection.dev",
    flush_interval_ms=5000,
    max_batch_size=100,
)

Option	Type	Default	Description
`token`	`str`	`INTROSPECTION_TOKEN` env var	API token
`service_name`	`str`	`INTROSPECTION_SERVICE_NAME` or `"introspection-client"`	Service name for trace attribution
`base_url`	`str`	`INTROSPECTION_BASE_URL` or `"https://otel.introspection.dev"`	API endpoint
`flush_interval_ms`	`int`	`5000`	How often buffered events are sent (ms)
`max_batch_size`	`int`	`100`	Max events per batch

Quick Start

Track an event, identify a user, and send feedback:


from introspection_sdk import IntrospectionClient
 
client = IntrospectionClient()
 
# Identify a user
with client.identify("user_123", traits={"plan": "pro", "name": "Jane"}):
    # Track a product event
    client.track("query_submitted", {"source": "chat"})
 
# Send feedback tied to a conversation
with client.set_user_id("user_123"):
    with client.set_conversation("conv_456", previous_response_id="msg_123"):
        client.feedback("thumbs_down", comments="This answer was incorrect")
 
# Shut down before process exit
client.shutdown()

Identifying Users

Use identify as a context manager to attach traits to a user:


with client.identify("user_123", traits={"plan": "pro", "name": "Jane"}):
    client.track("page_viewed", {"path": "/dashboard"})

Use set_user_id to set the user context for a block of code:


with client.set_user_id("user_123"):
    client.track("page_viewed", {"path": "/dashboard"})
    client.feedback("thumbs_up")

Tracking Events


client.track("query_submitted", {"source": "chat", "model": "gpt-4o"})

Feedback


client.feedback("thumbs_down", comments="Answer was off-topic")

Use set_conversation to tie feedback to a specific conversation and message:


with client.set_conversation("conv_456", previous_response_id="msg_789"):
    client.feedback("thumbs_up")

OpenAI Agents

Use IntrospectionTracingProcessor for OpenAI Agents:


from agents import Agent, Runner, set_trace_processors
from introspection_sdk import IntrospectionTracingProcessor
 
processor = IntrospectionTracingProcessor()
set_trace_processors([processor])
 
agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant. Be concise.",
)
 
result = Runner.run_sync(agent, "Say hello in one sentence.")
print(result.final_output)
 
processor.shutdown()

Claude Agent SDK

Use ClaudeTracingProcessor.configure() for Claude Agent SDK:


from introspection_sdk import ClaudeTracingProcessor
 
processor = ClaudeTracingProcessor()
processor.configure()
 
# All ClaudeSDKClient instances are now automatically traced
processor.shutdown()

configure() patches the SDK globally. All sessions created after this call are automatically instrumented.

LangChain / LangGraph


from introspection_sdk import IntrospectionCallbackHandler
 
handler = IntrospectionCallbackHandler(service_name="my-app")
response = model.invoke("Hello!", config={"callbacks": [handler]})
handler.shutdown()

OpenAI Conversations

Use IntrospectionConversationsSession when you need OpenAI Conversations continuity and want reasoning items normalized automatically:


from introspection_sdk import IntrospectionConversationsSession
 
session = IntrospectionConversationsSession(conversation_id="conv_123")
result = await Runner.run(agent, "Hello!", session=session)

Tracing

Use IntrospectionSpanProcessor when you already have OpenTelemetry-compatible tracing. This is the most flexible integration path.


import openai
from openinference.instrumentation.openai import OpenAIInstrumentor
from opentelemetry.sdk.trace import TracerProvider
from introspection_sdk import IntrospectionSpanProcessor
 
provider = TracerProvider()
provider.add_span_processor(IntrospectionSpanProcessor())
 
OpenAIInstrumentor().instrument(tracer_provider=provider)
 
client = openai.OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)

If you already export traces to another backend (Langfuse, Braintrust, Arize, etc.), you can add IntrospectionSpanProcessor as an additional processor alongside your existing one. See Dual Export for details.

Shutdown

Call shutdown() before your process exits to flush any buffered events:


client.shutdown()

You can also flush manually without shutting down:


client.flush(timeout_ms=30000)

For integrations that expose their own processor (e.g. IntrospectionTracingProcessor, ClaudeTracingProcessor), call shutdown() on the processor instance instead.

Error Handling

The SDK is designed to never raise in your application’s hot path. Events are buffered and sent asynchronously. If a request fails, the SDK retries internally and logs the failure.