# LangChain SDK Quick Start
Instrument your LangChain V1 application with the Fiddler LangChain SDK in under 10 minutes.
## What You'll Learn
By completing this quick start, you'll:
* Set up monitoring for a LangChain V1 (`langchain.agents.create_agent`) application
* Send your first traces to Fiddler
* Verify data collection in the Fiddler dashboard
* Understand basic conversation tracking
Prerequisites
**Before you begin, ensure you have**:
* **Python 3.10** or higher (up to Python 3.14)
* **Valid Fiddler account** with access to your instance
* **A LangChain V1 application** built with `langchain.agents.create_agent`
* **Network connectivity** to your Fiddler instance
Version Compatibility
**Supported Python Versions:**
* Python 3.10-3.14
**Framework Compatibility:**
* **LangChain V1:** `langchain >= 1.0` (the `create_agent` / middleware API)
**Core Dependencies:**
The SDK automatically installs these OpenTelemetry components:
* `opentelemetry-api`
* `opentelemetry-sdk`
* `opentelemetry-instrumentation`
* `opentelemetry-exporter-otlp-proto-http`
* `fiddler-otel` (transitive — provides `FiddlerClient`)
{% stepper %}
{% step %}
**Set Up Your Fiddler Application**
1. **Create your application in Fiddler**
Log in to your Fiddler instance and navigate to **GenAI Applications**, then click **Add Application** and follow the onboarding wizard to create your application.
2. **Copy your Application ID**
After creating your application, copy the **Application ID** from the GenAI Applications page using the copy icon next to the ID. This must be a valid UUID4 format (for example, `550e8400-e29b-41d4-a716-446655440000`). You'll need this for Step 3.
3. **Get Your Access Token**
Go to **Settings** > **Credentials** and copy your access token. You'll need this for Step 3. Refer to the [documentation](https://github.com/fiddler-labs/fiddler/blob/release/26.10/docs/documentation/reference/administration/settings.md#credentials) for more details.
{% endstep %}
{% step %}
**Install the Fiddler LangChain SDK**
For the stable release, install the Fiddler LangChain SDK using pip:
```bash
pip install fiddler-langchain
```
{% endstep %}
{% step %}
**Instrument Your Application**
Add the Fiddler LangChain SDK to your application with just a few lines of code. The instrumentor patches `langchain.agents.create_agent` so every agent created afterwards is traced automatically — no per-agent middleware configuration is required.
```python
import langchain.agents
from fiddler_otel import FiddlerClient
from fiddler_langchain import FiddlerLangChainInstrumentor
# Initialize the FiddlerClient. Replace the placeholder values below.
fdl_client = FiddlerClient(
application_id='', # Application ID copied from UI in Step 1
api_key='', # Your access token
url='', # https://your-instance.fiddler.ai
)
# Instrument LangChain V1 — must run BEFORE you call create_agent()
instrumentor = FiddlerLangChainInstrumentor(client=fdl_client)
instrumentor.instrument()
# Use the module attribute so the patched create_agent is called.
# (If you prefer `from langchain.agents import create_agent`, call
# `instrument()` BEFORE that import.)
agent = langchain.agents.create_agent(
model="openai:gpt-4o-mini",
tools=[...],
name="my_agent", # used as the root span label in traces
)
# Your existing LangChain code runs normally
# Traces will automatically be sent to Fiddler
```
**Add Context and Conversation Tracking**
The main goal of context setting is to enrich the telemetry data sent to Fiddler:
```python
from fiddler_langchain import set_llm_context, set_conversation_id
import uuid
# Attach descriptive context to a specific model — appears on its LLM spans.
set_llm_context(model, 'Customer support conversation')
# Set a conversation ID for tracking multi-turn conversations
set_conversation_id(str(uuid.uuid4()))
```
{% hint style="info" %}
**Manual middleware alternative.** If you prefer not to use the auto-instrumentor, pass `middleware=[FiddlerAgentMiddleware(client=client, agent_name="my_agent")]` directly to each `create_agent()` call. See the [FiddlerAgentMiddleware](https://github.com/fiddler-labs/fiddler/blob/release/26.10/docs/sdk-api/langchain/fiddler-agent-middleware.md) reference for details.
{% endhint %}
{% hint style="success" %}
**Need more control?** This Quick Start uses auto-instrumentation, which traces every `create_agent`-based agent automatically. The SDK also supports per-component span attributes (`add_span_attributes`) and session attributes (`add_session_attributes`) for fine-grained metadata tagging.
{% endhint %}
{% endstep %}
{% step %}
**Run a Complete Example**
{% hint style="info" %}
This example requires an OpenAI API key. You can create or find your key on the [API keys page](https://platform.openai.com/api-keys) of your OpenAI account.
{% endhint %}
Here's a complete working example to verify your setup:
```python
import os
import uuid
import langchain.agents
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from fiddler_otel import FiddlerClient
from fiddler_langchain import (
FiddlerLangChainInstrumentor,
set_conversation_id,
set_llm_context,
)
# Initialize the FiddlerClient. Replace the placeholder values below.
fdl_client = FiddlerClient(
application_id='', # Application ID copied from UI in Step 1
api_key='', # Your access token
url='', # https://your-instance.fiddler.ai
)
# Instrument LangChain V1 — must run BEFORE create_agent()
instrumentor = FiddlerLangChainInstrumentor(client=fdl_client)
instrumentor.instrument()
# Build a simple agent
model = ChatOpenAI(model="gpt-4o-mini")
@tool
def echo(text: str) -> str:
"""Echo back the input text."""
return text
agent = langchain.agents.create_agent(
model=model,
tools=[echo],
name="quickstart_agent",
)
# Set descriptive context for this interaction
set_llm_context(model, "Quick start example conversation")
# Generate and set a conversation ID
conversation_id = str(uuid.uuid4())
set_conversation_id(conversation_id)
# Run your agent — automatically instrumented
result = agent.invoke({
"messages": [{"role": "user", "content": "Hello! How are you?"}]
})
print("Response received:", result)
print("Conversation ID:", conversation_id)
```
{% hint style="info" %}
**Short-lived scripts:** The SDK batches spans in memory and exports them on a schedule. If your script exits before the batch is sent, call `fdl_client.shutdown()` (or use `with FiddlerClient(...) as client:`) to flush pending spans. Long-running servers handle this automatically via `atexit`.
{% endhint %}
{% endstep %}
{% step %}
**Verify Monitoring is Working**
1. **Run your application** using the example above or your own instrumented code
2. **Check the Fiddler dashboard:** Navigate to **GenAI Applications** in your Fiddler instance
3. **Confirm active status:** If Fiddler successfully receives telemetry, your application will show as **Active**
**Success Criteria**
You should see:
* Application status changed to **Active** in the Fiddler dashboard
* Trace data appearing within 1-2 minutes of running your example
* Context labels match what you set in your code
* Conversation ID visible in the trace details
**Expected trace hierarchy** for `create_agent`:
```
[Span] quickstart_agent (Agent root - TYPE=agent)
├── [Span] gpt-4o-mini (LLM call - TYPE=llm)
├── [Span] echo (Tool call - TYPE=tool)
└── [Span] gpt-4o-mini (LLM call - TYPE=llm)
```
{% endstep %}
{% endstepper %}
## Grant Team Access (optional)
Provide access to other users by assigning teams and users to the project that contains your applications. Managing permissions through Teams is recommended as a best practice. For more access control details, refer to the [Teams and Users Guide](https://github.com/fiddler-labs/fiddler/blob/release/26.10/docs/documentation/reference/administration/settings.md#access) and the [Role-based Access Guide](https://github.com/fiddler-labs/fiddler/blob/release/26.10/docs/documentation/reference/access-control/role-based-access.md).
1. Open the Settings page and select the Access tab
2. For both Users and Teams, select the "Edit" option to the right of the name
3. Add appropriate team members with the required permission levels
## Configuration Options
### Basic Configuration
```python
from fiddler_otel import FiddlerClient
fdl_client = FiddlerClient(
application_id="your-app-id", # Must be valid UUID4
api_key="your-api-key",
url="https://your-instance.fiddler.ai",
)
```
### Advanced Configuration
#### Customize Limits for High-Volume Applications
Set limits for your events, spans, and associated attributes. This is helpful for tuning reporting data to manageable numbers for highly attributed and/or high-volume applications.
```python
from opentelemetry.sdk.trace import SpanLimits
from fiddler_otel import FiddlerClient
custom_limits = SpanLimits(
max_events=64, # Default: 32
max_links=64, # Default: 32
max_span_attributes=64, # Default: 32
max_event_attributes=64, # Default: 32
max_link_attributes=64, # Default: 32
max_span_attribute_length=4096, # Default: 2048
)
client = FiddlerClient(
application_id="your-app-id",
api_key="your-api-key",
url="https://your-instance.fiddler.ai",
span_limits=custom_limits,
)
```
#### Sampling Traffic
Set a specific sampling percentage for incoming data.
```python
from opentelemetry.sdk.trace import sampling
from fiddler_otel import FiddlerClient
sampler = sampling.TraceIdRatioBased(0.1) # Sample 10% of traces
client = FiddlerClient(
application_id="your-app-id",
api_key="your-api-key",
url="https://your-instance.fiddler.ai",
sampler=sampler,
)
```
#### Environment Variables for Batch Processing
Adjust the following environment variables that the FiddlerClient will use when processing the OpenTelemetry traffic.
```python
import os
os.environ['OTEL_BSP_MAX_QUEUE_SIZE'] = '500' # Default: 100
os.environ['OTEL_BSP_SCHEDULE_DELAY_MILLIS'] = '500' # Default: 1000
os.environ['OTEL_BSP_MAX_EXPORT_BATCH_SIZE'] = '50' # Default: 10
os.environ['OTEL_BSP_EXPORT_TIMEOUT'] = '10000' # Default: 5000
```
#### Compression Options
The SDK supports data compression to help reduce the overall data volume transmitted over the network. This can help improve network latency.
```python
from opentelemetry.exporter.otlp.proto.http.trace_exporter import Compression
from fiddler_otel import FiddlerClient
# Enable gzip compression (default, recommended for production)
client = FiddlerClient(
application_id="your-app-id",
api_key="your-api-key",
url="https://your-instance.fiddler.ai",
compression=Compression.Gzip,
)
```
### Environment Variables Reference
Configure OpenTelemetry batch processor behavior through environment variables:
| Variable | Default | Description |
| -------------------------------- | ------- | ------------------------------------------------------ |
| `OTEL_BSP_MAX_QUEUE_SIZE` | `100` | Maximum spans in queue before export |
| `OTEL_BSP_SCHEDULE_DELAY_MILLIS` | `1000` | Delay between batch exports (milliseconds) |
| `OTEL_BSP_MAX_EXPORT_BATCH_SIZE` | `10` | Maximum spans exported per batch |
| `OTEL_BSP_EXPORT_TIMEOUT` | `5000` | Export timeout (milliseconds) |
| `FIDDLER_API_KEY` | - | Your Fiddler API key (recommended for production) |
| `FIDDLER_APPLICATION_ID` | - | Your application UUID4 (recommended for production) |
| `FIDDLER_URL` | - | Your Fiddler instance URL (recommended for production) |
### Adding Custom Attributes
`fiddler-langchain` exposes two helpers for tagging traces with business metadata:
```python
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from fiddler_langchain import add_session_attributes, add_span_attributes
# Session attributes — appear on every span in the current invocation
add_session_attributes("user_id", "alice@example.com")
add_session_attributes("environment", "production")
# Span attributes — only appear on spans for this specific component
model = ChatOpenAI(model="gpt-4o-mini")
add_span_attributes(model, department="AI_Engineering", agent_role="flight_assistant")
@tool
def book_flight(from_airport: str, to_airport: str) -> str:
"""Book a flight between two airports."""
return f"Booked {from_airport} -> {to_airport}"
add_span_attributes(book_flight, third_party="acme_air", reward_points=10.2)
```
| Helper | Scope | Span attribute format |
| ------------------------------------- | --------------------------------------- | ---------------------------- |
| `add_session_attributes(key, value)` | All spans in the invocation | `fiddler.session.user.{key}` |
| `add_span_attributes(node, **kwargs)` | Spans for that model / tool / retriever | `fiddler.span.user.{key}` |
## Async Agents
The instrumentation fully supports async agents. Use `agent.ainvoke()` instead of `agent.invoke()` — no additional configuration is needed:
```python
import asyncio
import langchain.agents
from langchain_openai import ChatOpenAI
from fiddler_langchain import FiddlerLangChainInstrumentor
from fiddler_otel import FiddlerClient
client = FiddlerClient(api_key="...", application_id="...", url="...")
FiddlerLangChainInstrumentor(client=client).instrument()
agent = langchain.agents.create_agent(
model=ChatOpenAI(model="gpt-4o-mini"),
tools=[...],
name="my_agent",
)
async def main():
result = await agent.ainvoke({"messages": [{"role": "user", "content": "Hello!"}]})
print(result)
asyncio.run(main())
```
## Troubleshooting
### Common Installation Issues
**Problem**: `ModuleNotFoundError: No module named 'fiddler_langchain'`
* **Solution**: Install the package: `pip install fiddler-langchain`
**Problem**: Version conflicts with existing packages
* **Solution**: Use a virtual environment or update conflicting packages
### Common Configuration Issues
**Problem**: `ValueError: application_id must be a valid UUID4`
* **Solution**: Ensure your Application ID is a valid UUID4 format (e.g., `550e8400-e29b-41d4-a716-446655440000`)
**Problem**: `ValueError: URL must have a valid scheme and netloc`
* **Solution**: Ensure your URL includes the protocol (e.g., `https://your-instance.fiddler.ai`)
**Problem**: Agents are created but no spans appear in Fiddler
* **Solution**: Confirm `instrumentor.instrument()` is called **before** `langchain.agents.create_agent()`. The instrumentor patches the module attribute, so agents created prior to instrumentation are not traced. If you use `from langchain.agents import create_agent`, the local name binds to the *unpatched* function — either call `instrument()` before that import, or invoke the function as `langchain.agents.create_agent(...)`.
**Problem**: Debugging trace generation
* **Solution**: Enable console tracer for local debugging:
```python
fdl_client = FiddlerClient(
application_id="your-app-id",
api_key="your-api-key",
url="https://your-instance.fiddler.ai",
console_tracer=True # Also prints spans to console; OTLP export to Fiddler still active
)
```
{% hint style="info" %}
`console_tracer=True` is **additive** — span data is printed to stdout **and** continues to be exported to Fiddler via OTLP. Setting this to `True` does **not** disable or suppress the OTLP export to Fiddler.
{% endhint %}
### Verification Issues
**Problem**: Application not showing as "Active" in Fiddler
* **Solution**: Check the following:
1. Ensure your application executes instrumented code (the agent must be invoked)
2. Verify that your Fiddler access token and application ID are correct
3. Check network connectivity to your Fiddler instance
4. Enable `console_tracer=True` to see if spans are being generated locally
## Next Steps
Now that your application is instrumented:
1. **Explore the data:** Check your Fiddler dashboard for traces, metrics, and performance insights
2. **Review the SDK reference:** Check the [Fiddler LangChain SDK Reference](/integrations/agentic-ai-and-llm-frameworks/agentic-ai/langchain-sdk.md) for complete documentation
3. **Optimize for production:** Review [configuration options](#configuration-options) for high-volume applications
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.fiddler.ai/developers/agentic-ai-monitoring/langchain-sdk-quick-start.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.