Skip to main content

​
Python Integrations

Alpha — The Python tracing packages (v0.1.0) are implemented and tested but not yet published to PyPI. You can install them from source today. Public release is coming soon — star the MutagenT repository to get notified.
MutagenT provides first-class Python support for tracing AI applications. The Python ecosystem consists of a core tracing SDK and framework-specific adapters that automatically instrument your LLM calls.

​
Architecture

​
Requirements

​
Package Status

PackageVersionStatusDescription
mutagent-tracing0.1.0Alpha (source only)Core SDK — spans, context propagation, batch transport
mutagent-openai0.1.0Alpha (source only)Automatic tracing for the OpenAI Python SDK
mutagent-langchain0.1.0Alpha (source only)Callback handler for LangChain
mutagent-langgraph0.1.0Alpha (source only)Graph tracer for LangGraph workflows

​
Quick Setup

1

Install the core SDK

Once published to PyPI, install with:
pip install mutagent-tracing
Until then, install from source (requires uv):
git clone https://github.com/mutagent/mutagent.git
cd mutagent/mutagent-integrations/python
uv sync
2

Install a framework adapter

pip install mutagent-openai     # For OpenAI
pip install mutagent-langchain  # For LangChain
pip install mutagent-langgraph  # For LangGraph
3

Initialize tracing

from mutagent_tracing import init_tracing

init_tracing(api_key="your-mutagent-api-key")

​
Environment Variables

You can configure tracing via environment variables instead of passing arguments directly:
VariableDescriptionDefault
MUTAGENT_API_KEYYour MutagenT API keyRequired
MUTAGENT_API_URLMutagenT API endpointhttps://api.mutagent.io
import os
from mutagent_tracing import init_tracing

init_tracing(
    api_key=os.environ["MUTAGENT_API_KEY"],
    endpoint=os.environ.get("MUTAGENT_API_URL", "https://api.mutagent.io"),
)

​
Configuration Options

The init_tracing function accepts the following parameters:
ParameterTypeDefaultDescription
api_keystrRequiredMutagenT API key
endpointstrhttps://api.mutagent.ioAPI endpoint URL
environmentstr | NoneNoneEnvironment name (e.g., production, staging)
batch_sizeint10Number of spans to buffer before flushing
flush_interval_msint5000Flush interval in milliseconds
debugboolFalseEnable debug logging
sourcestr"sdk"Source identifier for traces (internal use)

​
Core SDK: Manual Spans

The mutagent-tracing package also exposes a low-level API for creating custom spans when you need fine-grained control: 
from mutagent_tracing import (
    init_tracing,
    start_span,
    end_span,
    SpanOptions,
    SpanEndOptions,
    SpanKind,
    SpanStatus,
    SpanIO,
    SpanMetrics,
)

init_tracing(api_key="your-mutagent-api-key")

# Start a span
span = start_span(SpanOptions(
    kind=SpanKind.CHAIN,
    name="my-pipeline",
    input=SpanIO(text="input data"),
))

# Do work...

# End the span
if span:
    end_span(span, SpanEndOptions(
        status=SpanStatus.OK,
        output=SpanIO(text="output result"),
        metrics=SpanMetrics(
            model="gpt-4",
            provider="openai",
            input_tokens=150,
            output_tokens=50,
            total_tokens=200,
        ),
    ))

​
Available Span Kinds

KindValueUse Case
LLM_CHATllm.chatChat completions
LLM_COMPLETIONllm.completionText completions
LLM_EMBEDDINGllm.embeddingEmbedding generation
CHAINchainSequential pipelines
AGENTagentAgent execution
GRAPHgraphGraph workflows
NODEnodeGraph nodes
EDGEedgeGraph edges
WORKFLOWworkflowMulti-step workflows
MIDDLEWAREmiddlewareMiddleware layers
TOOLtoolTool invocations
RETRIEVALretrievalRAG retrieval
RERANKrerankReranking operations
GUARDRAILguardrailSafety checks
CUSTOMcustomCustom operations

​
Shutdown

Always call shutdown_tracing() before your application exits to flush remaining spans: 
from mutagent_tracing import shutdown_tracing

# At application shutdown
shutdown_tracing()
The SDK registers an atexit handler that flushes remaining spans automatically. Calling shutdown_tracing() explicitly is recommended for long-running applications or serverless functions.

​
Framework Guides

OpenAI

Automatic tracing for the OpenAI Python SDK

LangChain

Callback handler for LangChain chains and agents

LangGraph

Graph tracer for LangGraph workflows

​
TypeScript Equivalents

If you are using TypeScript/Node.js, see the TypeScript integration guides for the equivalent packages:
Python PackageTypeScript Equivalent
mutagent-tracing@mutagent/sdk
mutagent-openai@mutagent/openai
mutagent-langchain@mutagent/langchain
mutagent-langgraph@mutagent/langgraph