Supercharge Your LangGraph Workflows with Freeplay

LangGraph gives developers the power to define complex, multi-step agent workflows with stateful orchestration. But as your graph grows, so does the challenge of managing prompts, tracking behavior across nodes, and evaluating whether your system is getting better or worse in collaboration with your team. That’s where Freeplay comes in.

Freeplay connects directly to your LangGraph application, giving you full-stack visibility and control over every LLM interaction inside your graph. You get centralized prompt management, built-in evals tailored to your product, and powerful observability that makes debugging and iteration feel like a feature, not a fire drill.

This guide walks through how to integrate Freeplay with your LangGraph application, how to monitor and evaluate your graph in production, and how to scale your prompt engineering process without drowning in complexity.

This guide will walk you through:

1. Setting up the Freeplay client in your code - Installing dependencies and configuring your environment
2. Getting your prompts into Freeplay - Migrating prompt and model configurations to Freeplay and accessing them in your app
3. Integrating observability - Adding Freeplay logging to your LangGraph nodes for comprehensive data capture and agent tracing

Let's get started!

Prerequisites

Before you begin, make sure you have:

• A Freeplay account with an active project
• Python 3.8 or higher installed
• Basic familiarity with LangGraph and LangChain

Installation

Install the Freeplay LangGraph SDK along with your preferred LLM provider:

# Install Freeplay SDK
pip install freeplay-python-langgraph

# Install your LLM provider (choose one or more)
pip install langchain-openai
pip install langchain-anthropic
pip install langchain-google-vertexai

Configuration

Set Up Your Credentials

Configure your Freeplay credentials using environment variables:

export FREEPLAY_API_URL="https://app.freeplay.ai/api"
export FREEPLAY_API_KEY="fp_..."
export FREEPLAY_PROJECT_ID="proj_..."

You can find your API key and Project ID in your Freeplay project settings.

Initialize the SDK

Create a FreeplayLangGraph instance in your application:

from freeplay_python_langgraph import FreeplayLangGraph

# Using environment variables
freeplay = FreeplayLangGraph()

# Or pass credentials directly
freeplay = FreeplayLangGraph(
    freeplay_api_url="https://app.freeplay.ai/api",
    freeplay_api_key="fp_...",
    project_id="proj_...",
)

With this setup, your LangGraph application is now automatically instrumented with OpenTelemetry, sending traces and spans to Freeplay for observability.

Using Freeplay-Hosted Prompts

One of Freeplay's most powerful features is centralized prompt management. Instead of hardcoding prompts in your application, call them from Freeplay with version control and environment management.

Basic Prompt Invocation

The SDK automatically instantiates the correct model based on your Freeplay prompt configuration:

from freeplay_python_langgraph import FreeplayLangGraph

freeplay = FreeplayLangGraph()

# Invoke a Freeplay-hosted prompt
response = freeplay.invoke(
    prompt_name="customer-support-agent",
    variables={"customer_issue": "I can't log into my account"},
    environment="production"
)

print(response.content)

Using Freeplay-hosted prompts gives you the ability to iterate on prompts, test different versions, and deploy changes without modifying your code. This separation of concerns helps you move faster and reduces deployment risk.

Using Custom Models

If you need more control over model configuration, provide your own pre-configured LangChain model:

from langchain_openai import ChatOpenAI
from freeplay_python_langgraph import FreeplayLangGraph

freeplay = FreeplayLangGraph()

# Configure your own model with custom parameters
model = ChatOpenAI(
    model="gpt-4",
    temperature=0.7,
    max_tokens=1000
)

response = freeplay.invoke(
    prompt_name="customer-support-agent",
    variables={"customer_issue": "Billing question"},
    model=model
)

Building Multi-Turn Conversations

LangGraph excels at building stateful, multi-turn conversational agents. Freeplay integrates seamlessly with LangGraph's MessagesState pattern to maintain conversation history.

Conversation History Example

from langchain_core.messages import HumanMessage, AIMessage
from freeplay_python_langgraph import FreeplayLangGraph

freeplay = FreeplayLangGraph()

# Build conversation context with message history
history = [
    HumanMessage(content="I need help resetting my password"),
    AIMessage(content="I can help with that. What's your email address?"),
    HumanMessage(content="It's [email protected]")
]

# The prompt has full context of the conversation
response = freeplay.invoke(
    prompt_name="customer-support-agent",
    variables={"account_email": "[email protected]"},
    history=history,
    environment="production"
)

print(response.content)

By passing conversation history to Freeplay, your prompts can maintain context across multiple turns, creating more natural and effective conversational experiences.

Integrating Tools with LangGraph

LangGraph applications often need to call external tools and APIs. Freeplay supports binding LangChain tools to your prompts, enabling agentic workflows.

Tool Binding Example

from langchain_core.tools import tool
from freeplay_python_langgraph import FreeplayLangGraph

@tool
def check_account_status(email: str) -> str:
    """Check the status of a customer account by email."""
    # Your account lookup logic here
    return f"Account for {email} is active"

@tool
def reset_password(email: str) -> str:
    """Send a password reset email to the customer."""
    # Your password reset logic here
    return f"Password reset email sent to {email}"

freeplay = FreeplayLangGraph()

response = freeplay.invoke(
    prompt_name="customer-support-agent",
    variables={"customer_email": "[email protected]"},
    tools=[check_account_status, reset_password]
)

When you bind tools to your prompts, the LLM can decide when and how to call them based on the conversation context. This enables sophisticated agentic behavior while keeping your code clean and maintainable.

Tracking Test Runs and Evaluations

Freeplay helps you systematically evaluate your LangGraph applications by tracking test runs and test cases. This is essential for regression testing and measuring improvements as you iterate on your prompts and logic.

Test Execution Tracking

from freeplay_python_langgraph import FreeplayLangGraph

freeplay = FreeplayLangGraph()

# Track this invocation as part of a test run
response = freeplay.invoke(
    prompt_name="customer-support-agent",
    variables={"customer_issue": "Cannot access account"},
    test_run_id="test_run_123",
    test_case_id="test_case_456",
    environment="staging"
)

By associating invocations with test runs and test cases, you can analyze performance across your test suite, identify regressions, and measure the impact of prompt changes in Freeplay's evaluation dashboard.

Automatic Observability

Once initialized, the Freeplay SDK automatically instruments your LangGraph application with OpenTelemetry. This means every LangChain and LangGraph operation is traced and sent to Freeplay without any additional code.

What Gets Tracked

Freeplay automatically captures:

• LLM Interactions: Prompt version, inputs, provider, model name, tokens used, latency
• Tool executions: Which tools were called and their results
• Conversation flows: Multi-turn interactions and state transitions
• Errors and exceptions: Failed invocations with stack traces

You can view all of this data in the Freeplay dashboard, making it easy to debug issues, optimize performance, and understand how your application behaves in production.

Supported LLM Providers

Freeplay's LangGraph SDK supports automatic model instantiation for multiple providers. Install the corresponding LangChain integration package for your provider:

The SDK will automatically detect which provider your Freeplay prompt is configured to use and instantiate the appropriate model with the correct parameters.

Next Steps

Now that you've integrated Freeplay with your LangGraph application, you can:

• Create and manage prompts in the Freeplay dashboard with version control
• Set up environments to test changes in staging before deploying to production
• Build evaluation datasets to systematically test your application's performance
• Analyze traces to identify bottlenecks and optimize your LangGraph workflows
• Collaborate with your team on prompt engineering and application improvements

Visit the Freeplay documentation to learn more about advanced features like prompt experiments, A/B testing, and custom evaluation metrics.