fiddler-strands 0.4.0

Fiddler SDK for Strands Agent instrumentation with OpenTelemetry

Fiddler Strands SDK

OpenTelemetry instrumentation SDK for Strands AI agents, providing automatic observability and monitoring capabilities through Fiddler's platform.

Features

• 🎯 Automatic Instrumentation: Zero-code instrumentation of Strands agents using OpenTelemetry
• 🔍 Built-in Observability: Automatic logging hooks for agent interactions
• 📊 Fiddler Integration: Custom span processors for enhanced trace analysis
• 🛠️ Extensible: Easy to add custom hooks and processors
• 🚀 Production Ready: Built on OpenTelemetry standards

Installation

Using uv (Recommended)

# Install the SDK
uv add fiddler-strands

Using pip

pip install fiddler-strands

Quick Start

Prerequisites

Before using the SDK, ensure you have:

• Fiddler platform access with API credentials
• OpenAI API key (if using OpenAI models)
• Configure environment variables:
  • FIDDLER_ENDPOINT: Your Fiddler platform URL
  • FIDDLER_TOKEN: Your Fiddler API token
  • FIDDLER_APPLICATION_UUID: Your application UUID from Fiddler

See the full documentation for detailed configuration steps.

Basic Usage

import os
from strands import Agent
from strands.models.openai import OpenAIModel
from strands.telemetry import StrandsTelemetry
from fiddler_strandsagents import StrandsAgentInstrumentor

strands_telemetry = StrandsTelemetry()
strands_telemetry.setup_otlp_exporter()
strands_telemetry.setup_console_exporter()
# Enable automatic instrumentation
StrandsAgentInstrumentor(strands_telemetry).instrument()

# Create your agent as usual - LoggingHook will be automatically injected
model = OpenAIModel(api_key=os.getenv("OPENAI_API_KEY"))
agent = Agent(model=model, system_prompt="You are a helpful assistant")

# Use your agent - all interactions will be automatically instrumented
response = agent("Hello, how are you?")

Note: The OTLP exporter requires Fiddler credentials to be configured as environment variables.

API Reference

StrandsAgentInstrumentor

The main instrumentor class for automatic agent instrumentation.

from fiddler_strandsagents import StrandsAgentInstrumentor

instrumentor = StrandsAgentInstrumentor()

# Enable instrumentation
instrumentor.instrument()

# Check if instrumentation is active
is_active = instrumentor.is_instrumented_by_opentelemetry

# Disable instrumentation
instrumentor.uninstrument()

Helper Functions

The SDK provides helper functions to add custom metadata to your telemetry spans:

set_conversation_id(agent, conversation_id)

Set a unique conversation ID for tracking related interactions:

from fiddler_strandsagents import set_conversation_id

set_conversation_id(agent, 'session_1234567890')

set_session_attributes(agent, **kwargs)

Add custom session-level attributes to track business context:

from fiddler_strandsagents import set_session_attributes

set_session_attributes(agent,
    role='customer_support',
    cost_center='travel_desk',
    region='us-west'
)

set_span_attributes(obj, **kwargs)

Add custom attributes to specific components (agents, models, or tools):

from fiddler_strandsagents import set_span_attributes

# Add attributes to a model
set_span_attributes(model, model_id='gpt-4o-mini', temperature=0.7)

# Add attributes to a tool
set_span_attributes(tool, department='search', version='2.0')

set_llm_context(model, context)

Set additional context for LLM interactions:

from fiddler_strandsagents import set_llm_context

set_llm_context(model, 'Available options: Option A, Option B, Option C...')

Getter Functions

Retrieve previously set metadata:

from fiddler_strandsagents import (
    get_conversation_id,
    get_session_attributes,
    get_span_attributes
)

conversation_id = get_conversation_id(agent)
attributes = get_session_attributes(agent)
span_attrs = get_span_attributes(model)

License

This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.

Support

• 📧 Email: [e-mail]
• 📖 Documentation: https://docs.fiddler.ai/api/fiddler-strands-sdk/strands
• 🐛 Issues: https://github.com/fiddler-labs/fiddler-strands-sdk/issues

Examples and Development

For example scripts and development information, please visit the GitHub repository.