Fiddler LangGraph SDK

Auto-instrument LangGraph agents with Fiddler's native SDK

Auto-instrument your LangGraph agent applications with OpenTelemetry-based tracing for comprehensive agentic observability. The Fiddler LangGraph SDK provides automatic monitoring of complex multi-agent workflows, capturing every step from thought to action to execution.

What You'll Need

Fiddler account (cloud or on-premises)
Python 3.10, 3.11, 3.12, or 3.13
LangGraph or LangChain application
Fiddler API key and application ID

Quick Start

Get monitoring in 3 steps:

# Step 1: Install
pip install fiddler-langgraph

# Step 2: Initialize the Fiddler client
from fiddler_langgraph import FiddlerClient
from fiddler_langgraph.tracing.instrumentation import LangGraphInstrumentor

fdl_client = FiddlerClient(
    api_key='your-api-key',
    application_id='your-app-id',  # Must be valid UUID4
    url='https://your-instance.fiddler.ai'
)

# Step 3: Instrument your application
instrumentor = LangGraphInstrumentor(fdl_client)
instrumentor.instrument()

# Your existing LangGraph code runs normally
# Traces will automatically be sent to Fiddler

That's it! Your agent traces are now flowing to Fiddler.

What Gets Monitored

The LangGraph SDK automatically captures:

Hierarchical Tracing

Application Level - Overall system performance and health
Session Level - User interaction and conversation flows
Agent Level - Individual agent behavior and decisions
Span Level - Tool calls, LLM requests, state transitions

Agent Lifecycle Stages

Every agent operation is tracked through five observable stages:

Thought - Data ingestion, context retrieval, information interpretation
Action - Planning processes, tool selection, decision-making
Execution - Task performance, API calls, external integrations
Reflection - Self-evaluation, learning signals, adaptation
Alignment - Trust validation, safety checks, policy enforcement

Captured Data

Agent state transitions and decision points
Tool invocations with inputs and outputs
LLM API calls with prompts and responses
Execution times and latency metrics
Error traces and exception handling
Custom metadata and tags

Application Setup

Before instrumenting your application, you must create an application in Fiddler and obtain your Application ID:

1. Create Your Application in Fiddler

GenAI applications list page with add application modal

2. Copy Your Application ID

After creating your application, copy the Application ID from the application details page. This must be a valid UUID4 format (for example, 550e8400-e29b-41d4-a716-446655440000). You'll need this for initialization.

GenAI applications list page showing copy app ID

3. Get Your Access Token

Go to Settings > Credentials and copy your access token. You'll need this for initialization.

Fiddler Settings- Credentials tab showing admin's access token

Detailed Setup

Installation

pip install fiddler-langgraph

Framework Compatibility:

LangGraph: >= 0.3.28 and <= 1.0.2 OR LangChain: >= 0.3.28 and <= 1.0.2
Python: 3.10, 3.11, 3.12, or 3.13

Configuration

Direct Initialization (Recommended)

from fiddler_langgraph import FiddlerClient
from fiddler_langgraph.tracing.instrumentation import LangGraphInstrumentor

fdl_client = FiddlerClient(
    api_key='your-api-key',              # Required
    application_id='your-app-id',        # Required (UUID4 format)
    url='https://your-instance.fiddler.ai'  # Required
)

instrumentor = LangGraphInstrumentor(fdl_client)
instrumentor.instrument()

Using Environment Variables

You can use environment variables instead of hardcoding credentials:

import os
from fiddler_langgraph import FiddlerClient
from fiddler_langgraph.tracing.instrumentation import LangGraphInstrumentor

fdl_client = FiddlerClient(
    api_key=os.getenv("FIDDLER_API_KEY"),
    application_id=os.getenv("FIDDLER_APPLICATION_ID"),
    url=os.getenv("FIDDLER_URL")
)

instrumentor = LangGraphInstrumentor(fdl_client)
instrumentor.instrument()

Environment Variables Reference:

Variable

Description

Example

FIDDLER_API_KEY

Your Fiddler API key

fid_...

FIDDLER_APPLICATION_ID

Your application UUID4

550e8400-e29b-41d4-a716-446655440000

FIDDLER_URL

Your Fiddler instance URL

https://your-instance.fiddler.ai

Advanced Usage

Adding Context and Metadata

Enrich traces with custom context and conversation tracking:

from fiddler_langgraph.tracing.instrumentation import set_llm_context, set_conversation_id
import uuid

# Set descriptive context for LLM processing
set_llm_context(model, 'Customer support conversation')

# Set conversation ID for tracking multi-turn conversations
conversation_id = str(uuid.uuid4())
set_conversation_id(conversation_id)

Custom Span and Session Attributes

Add custom attributes to individual spans or entire sessions:

from fiddler_langgraph.tracing.instrumentation import add_span_attributes, add_session_attributes

# Add attributes to specific spans
add_span_attributes({
    "user_id": "user_123",
    "request_type": "billing_inquiry"
})

# Add attributes that persist across all spans in a session
add_session_attributes({
    "session_type": "premium",
    "feature_flags": ["new_ui", "advanced_mode"]
})

Sampling Configuration

Control trace sampling for high-volume applications:

from opentelemetry.sdk.trace import sampling
from fiddler_langgraph import FiddlerClient
from fiddler_langgraph.tracing.instrumentation import LangGraphInstrumentor

# Sample 10% of traces
sampler = sampling.TraceIdRatioBased(0.1)

fdl_client = FiddlerClient(
    api_key="your-api-key",
    application_id="your-app-id",
    url="https://your-instance.fiddler.ai",
    sampler=sampler
)

instrumentor = LangGraphInstrumentor(fdl_client)
instrumentor.instrument()

For production deployments, consider these sampling strategies:

High-volume applications: Sample 5-10% (TraceIdRatioBased(0.05))
Development/testing: Sample 100% (default - no sampler specified)
Cost optimization: Sample 1-5% (TraceIdRatioBased(0.01))

Production Configuration

For high-volume production applications, configure span limits and batch processing:

import os
from opentelemetry.sdk.trace import SpanLimits, sampling
from opentelemetry.exporter.otlp.proto.http.trace_exporter import Compression
from fiddler_langgraph import FiddlerClient
from fiddler_langgraph.tracing.instrumentation import LangGraphInstrumentor

# Configure batch processing BEFORE initializing FiddlerClient
os.environ['OTEL_BSP_MAX_QUEUE_SIZE'] = '500'         # Increased from default 100
os.environ['OTEL_BSP_SCHEDULE_DELAY_MILLIS'] = '500'  # Faster export than default 1000ms
os.environ['OTEL_BSP_MAX_EXPORT_BATCH_SIZE'] = '50'   # Larger batches than default 10

# Increase span limits to capture more data
production_limits = SpanLimits(
    max_events=128,                   # Default: 32
    max_span_attributes=128,          # Default: 32
    max_span_attribute_length=8192,   # Default: 2048
)

# Sample 5-10% of traces
production_sampler = sampling.TraceIdRatioBased(0.05)

fdl_client = FiddlerClient(
    api_key=os.getenv("FIDDLER_API_KEY"),
    application_id=os.getenv("FIDDLER_APPLICATION_ID"),
    url=os.getenv("FIDDLER_URL"),
    span_limits=production_limits,
    sampler=production_sampler,
    compression=Compression.Gzip,
)

instrumentor = LangGraphInstrumentor(fdl_client)
instrumentor.instrument()

Example Applications

Multi-Agent Travel Planner

from langgraph.graph import StateGraph, END
from langchain_openai import ChatOpenAI
from typing import TypedDict
from fiddler_langgraph import FiddlerClient
from fiddler_langgraph.tracing.instrumentation import LangGraphInstrumentor

# Initialize Fiddler monitoring
fdl_client = FiddlerClient(
    api_key="your-api-key",
    application_id="your-app-id",
    url="https://your-instance.fiddler.ai"
)
instrumentor = LangGraphInstrumentor(fdl_client)
instrumentor.instrument()

# Define your agent graph
class TravelState(TypedDict):
    destination: str
    budget: float
    itinerary: list

# Research agent
def research_agent(state: TravelState):
    # Agent logic - automatically traced
    return {"research_complete": True}

# Booking agent
def booking_agent(state: TravelState):
    # Agent logic - automatically traced
    return {"bookings": [...]}

# Build graph
graph = StateGraph(TravelState)
graph.add_node("research", research_agent)
graph.add_node("booking", booking_agent)
graph.add_edge("research", "booking")
graph.add_edge("booking", END)

# Run - traces automatically sent to Fiddler
app = graph.compile()
result = app.invoke({"destination": "Paris", "budget": 5000})

View complete example notebook →

Customer Support Agent with Tools

from langchain.tools import Tool
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
from fiddler_langgraph import FiddlerClient
from fiddler_langgraph.tracing.instrumentation import LangGraphInstrumentor

# Initialize Fiddler monitoring
fdl_client = FiddlerClient(
    api_key="your-api-key",
    application_id="your-app-id",
    url="https://your-instance.fiddler.ai"
)
instrumentor = LangGraphInstrumentor(fdl_client)
instrumentor.instrument()

# Define tools - calls automatically traced
tools = [
    Tool(name="search_kb", func=search_knowledge_base),
    Tool(name="create_ticket", func=create_support_ticket),
    Tool(name="escalate", func=escalate_to_human)
]

# Create agent - instrumentation is automatic
model = ChatOpenAI(model="gpt-4o")
agent = create_react_agent(model, tools)

# Run agent - full trace in Fiddler
response = agent.invoke({
    "messages": [{"role": "user", "content": "My order is delayed"}]
})

Viewing Your Data

After running your instrumented application:

Navigate to Fiddler UI - https://your-instance.fiddler.ai
Select "GenAI Apps" - View your application
Inspect traces - Drill down from application → session → agent → span
Analyze patterns - Use analytics to identify bottlenecks and errors

Key Metrics Tracked

Latency: P50, P95, P99 response times across agents
Error Rate: Percentage of failed agent executions
Token Usage: LLM token consumption per agent/session
Tool Calls: Frequency and success rate of tool invocations
State Transitions: Agent decision path analysis

Troubleshooting

Application Not Showing as "Active"

Check your configuration:

Ensure your application executes instrumented code
Verify your Fiddler access token and application ID are correct
Check network connectivity to your Fiddler instance

Enable console tracer for debugging:

fdl_client = FiddlerClient(
    api_key="your-api-key",
    application_id="your-app-id",
    url="https://your-instance.fiddler.ai",
    console_tracer=True  # Prints spans to console for debugging
)

When console_tracer=True, traces are printed locally and NOT sent to Fiddler. Use only for debugging.

Network Connectivity Issues

Verify connectivity to your Fiddler instance:

curl -I https://your-instance.fiddler.ai

Check firewall settings:

Ensure HTTPS traffic on port 443 is allowed
Verify your Fiddler instance URL is correct

Import Errors

Problem: ModuleNotFoundError: No module named 'fiddler_langgraph'

Solution: Ensure you've installed the correct package:

pip install fiddler-langgraph

Problem: ImportError: cannot import name 'LangGraphInstrumentor'

Solution: Ensure you have the correct import path:

from fiddler_langgraph.tracing.instrumentation import LangGraphInstrumentor

Version Compatibility Issues

Verify your versions match requirements:

python --version  # Should be 3.10, 3.11, 3.12, or 3.13
pip show langgraph  # Should be >= 0.3.28 and <= 1.0.2

If you have version conflicts:

pip install langgraph>=0.3.28,<=1.0.2

Invalid Application ID

Problem: ValueError: application_id must be a valid UUID4

Solution: Ensure your Application ID is in proper UUID4 format:

# ❌ This will fail
fdl_client = FiddlerClient(
    api_key="your-access-token",
    application_id="invalid-id",  # Not a valid UUID4
    url="https://instance.fiddler.ai"
)

# ✅ Correct format
fdl_client = FiddlerClient(
    api_key="your-access-token",
    application_id="550e8400-e29b-41d4-a716-446655440000",  # Valid UUID4
    url="https://instance.fiddler.ai"
)

Copy the Application ID directly from the Fiddler dashboard to avoid formatting issues.

Agent Shows as "UNKNOWN_AGENT"

For LangChain applications, ensure you're setting the agent name in the config parameter:

from langchain_core.output_parsers import StrOutputParser

# Define your LangChain runnable
chat_app_chain = prompt | llm | StrOutputParser()

# Run with agent name configuration
response = chat_app_chain.invoke({
    "input": user_input,
    "history": messages,
}, config={"configurable": {"agent_name": "service_chatbot"}})

Note: LangGraph applications automatically extract agent names. This manual configuration is only needed for LangChain applications.

OpenTelemetry Compatibility

The LangGraph SDK is built on OpenTelemetry Protocol (OTLP). The SDK uses standard OpenTelemetry components, allowing you to:

Integrate with existing observability infrastructure
Export traces to multiple backends (with custom configuration)
Use custom OTEL collectors and processors

All telemetry data follows OpenTelemetry semantic conventions for AI/ML workloads.

Fiddler Evals SDK - Evaluate LangGraph agent quality offline
Python Client SDK - Additional monitoring capabilities

Migration Guides

From LangSmith

# Before (LangSmith)
import os
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_API_KEY"] = "ls_..."

# After (Fiddler - both can run simultaneously)
from fiddler_langgraph import FiddlerClient
from fiddler_langgraph.tracing.instrumentation import LangGraphInstrumentor

fdl_client = FiddlerClient(
    api_key="your-api-key",
    application_id="your-app-id",
    url="https://your-instance.fiddler.ai"
)
instrumentor = LangGraphInstrumentor(fdl_client)
instrumentor.instrument()

# Your LangGraph code remains unchanged

From Manual Tracing

If you've built custom tracing, migration is straightforward:

# Before (manual timing/logging)
import time
start = time.time()
result = my_agent.run()
duration = time.time() - start
log_to_system(duration, result)

# After (Fiddler SDK - automatic instrumentation)
# Initialize Fiddler client and instrumentor (once)
fdl_client = FiddlerClient(
    api_key="your-api-key",
    application_id="your-app-id",
    url="https://your-instance.fiddler.ai"
)
instrumentor = LangGraphInstrumentor(fdl_client)
instrumentor.instrument()

# Remove all manual timing/logging code
result = my_agent.run()  # Automatic instrumentation

API Reference

Full SDK documentation:

LangGraph SDK Reference - Complete class and method documentation

Next Steps

Now that your application is instrumented:

Explore the data: Check your Fiddler dashboard for traces, metrics, and performance insights
Learn advanced features: See our Advanced Usage Guide for complex multi-agent scenarios
Review the SDK reference: Check the Fiddler LangGraph SDK Reference for complete documentation
Optimize for production: Review configuration options for high-volume applications

PreviousAgentic AI Overview NextFiddler Strands SDK

Last updated 1 day ago

Was this helpful?

What You'll Need

Quick Start

What Gets Monitored

Hierarchical Tracing

Agent Lifecycle Stages

Captured Data

Application Setup

1. Create Your Application in Fiddler

2. Copy Your Application ID

3. Get Your Access Token

Detailed Setup

Installation

Configuration

Direct Initialization (Recommended)

Using Environment Variables

Advanced Usage

Adding Context and Metadata

Custom Span and Session Attributes

Sampling Configuration

Production Configuration

Example Applications

Multi-Agent Travel Planner

Customer Support Agent with Tools

Viewing Your Data

Key Metrics Tracked

Troubleshooting

Application Not Showing as "Active"

Network Connectivity Issues

Import Errors

Version Compatibility Issues

Invalid Application ID

Agent Shows as "UNKNOWN_AGENT"

OpenTelemetry Compatibility

Related Integrations

Migration Guides

From LangSmith

From Manual Tracing

API Reference

Next Steps