Getting started with LangGraph and AgentControl configs

Overview

This guide shows how to integrate LangGraph agent workflows with LaunchDarkly AgentControl. Using AgentControl configs with LangGraph lets you manage agent instructions, model configuration, and parameters outside of your application code.

This guide uses agent mode for LangGraph workflows. Agent mode uses a single instructions string rather than a messages array, which maps directly to LangGraph’s agent prompts. To learn more, read Agents.

Prerequisites

To complete this guide, you must have the following prerequisites:

• A LaunchDarkly account, including:
  • A LaunchDarkly SDK key for your environment.
  • A member role that allows AgentControl actions. The LaunchDarkly project admin, maintainer, and developer project roles, as well as the admin and owner base roles, include this ability. To learn more about LaunchDarkly roles, read Roles.
• A Python 3.10+ or Node.js 20+ development environment.
• LangGraph installed in your application.
• An API key for your chosen model provider (OpenAI, Anthropic, or another supported provider).

Concepts

Before you begin, review these key concepts.

LangGraph agents

LangGraph provides a framework for building agent workflows as directed graphs. The create_react_agent function creates a ReAct-style agent that can use tools and maintain state across conversation turns. Agents receive a system prompt that defines their behavior and capabilities.

Agent mode AgentControl configs

Agent mode AgentControl configs use an instructions field instead of a messages array. This single instruction string serves as the system prompt for your agent. Agent mode is ideal for:

• Multi-step agent workflows
• Tool-using agents
• Persistent agent sessions

The agent_config function

The agent_config function retrieves the AgentControl config variation for a given context. It returns an AIAgentConfig object that includes the customized instructions, model configuration, and a create_tracker() (Python) or createTracker() (Node.js) factory method that returns a tracker for recording metrics. Call agent_config each time you create an agent so LaunchDarkly can evaluate targeting and return the current configuration.

Step 1: Install dependencies

Install the LaunchDarkly SDKs and LangGraph packages.

$
pip install "launchdarkly-server-sdk-ai>=0.20.0" "launchdarkly-server-sdk-ai-langchain>=0.7.0" langgraph langchain langchain-core python-dotenv

Install the LangChain provider package for your model. Common provider packages include:

• langchain-openai for OpenAI models
• langchain-anthropic for Anthropic models
• langchain-google-genai for Google Gemini models

Step 2: Create an AgentControl config in LaunchDarkly

Create an AgentControl config in agent mode to store your agent configuration.

To create an AgentControl config:

1. In the left navigation, click Create and select AgentControl config.
2. In the “Create AgentControl config” dialog, select Agent.
3. Enter a name for your AgentControl config, for example, “LangGraph Agent.”
4. Click Create.

Then, create a variation:

1. On the Variations tab, replace “Untitled variation” with a variation name, such as “GPT-4o Agent”.
2. Click Select a model and choose the gpt-4o OpenAI model.
3. Click Parameters and set temperature to 0.7 and max_tokens to 2000.
4. In the Instructions field, enter your agent’s system prompt:

You are a helpful assistant that can perform calculations and check weather. Use the available tools to provide accurate information. Always explain your reasoning step by step.

5. Click Review and save.

Step 3: Set up targeting rules

Configure targeting rules to control which users receive the AgentControl config variation.

To set up the default rule:

1. Select the Targeting tab for your AgentControl config.
2. In the “Default rule” section, click Edit.
3. Configure the default rule to serve your variation, such as “GPT-4o Agent”.
4. Click Review and save.

The AgentControl config is enabled by default. After you add the integration code to your application, LaunchDarkly serves the configured variation to your users.

Step 4: Integrate LangGraph with AgentControl configs

The integration involves these key steps:

1. Define the tools your agent can call.
2. Initialize the LaunchDarkly SDK and AI client.
3. Get the agent config using agent_config() (Python) or aiClient.agentConfig() (Node.js).
4. Build a LangChain model from the AgentControl config using the LaunchDarkly LangChain provider.
5. Create a LangGraph ReAct agent with a MemorySaver checkpointer.
6. Invoke the agent and track metrics with the config’s tracker.

Define the agent’s tools.

1
from langchain_core.tools import tool
2
3
4
@tool
5
def get_order_status(order_id: str) -> str:
6
    """Look up the status of a customer order by order ID."""
7
    orders = {
8
        "ORD-123": "Shipped — arrives Thursday",
9
        "ORD-456": "Processing — estimated ship date: tomorrow",
10
        "ORD-789": "Delivered on Monday",
11
    }
12
    return orders.get(order_id, f"No order found with ID {order_id}")

Initialize the LaunchDarkly SDK and AI client, fetch the agent config, build the LangChain model with create_langchain_model (Python) or createLangChainModel (Node.js), and create the ReAct agent.

The provider reads the model name, provider, and all parameters (temperature, max tokens, and others) from the variation, maps LaunchDarkly provider names to LangChain equivalents — for example, "gemini" to "google_genai" — and returns a configured chat model. The same AgentControl config key can serve OpenAI, Anthropic, or any other provider-backed variation from the same code path.

1
import os
2
import ldclient
3
from ldclient import Context
4
from ldclient.config import Config
5
from ldai import LDAIClient
6
from ldai.tracker import TokenUsage
7
from ldai_langchain import create_langchain_model, get_ai_metrics_from_response
8
from langchain_core.tools import tool
9
from langgraph.prebuilt import create_react_agent
10
from langgraph.checkpoint.memory import MemorySaver
11
12
13
ldclient.set_config(Config(os.environ.get("LAUNCHDARKLY_SDK_KEY")))
14
15
ai_client = LDAIClient(ldclient.get())
16
17
context = Context.builder("user-123").kind("user").name("Sandy").build()
18
19
# Pass a default for improved resiliency when the AgentControl config is unavailable
20
# or LaunchDarkly is unreachable; omit for a disabled default.
21
# Example:
22
#   from ldai import AIAgentConfigDefault
23
#   default = AIAgentConfigDefault(
24
#       enabled=True,
25
#       model={"name": "gpt-5"},
26
#       provider={"name": "openai"},
27
#       instructions="You are a helpful assistant.",
28
#   )
29
#   agent_config = ai_client.agent_config("langgraph-agent", context, default)
30
agent_config = ai_client.agent_config("langgraph-agent", context)
31
32
# create_langchain_model reads agent_config.model.name / .parameters and picks the
33
# right chat model class (OpenAI, Anthropic, …) with no per-provider branching.
34
llm = create_langchain_model(agent_config)
35
36
# MemorySaver gives the ReAct agent short-term memory per thread_id —
37
# follow-up turns on the same thread see the earlier conversation.
38
checkpointer = MemorySaver()
39
agent = create_react_agent(
40
    llm,
41
    [get_order_status],
42
    prompt=agent_config.instructions,
43
    checkpointer=checkpointer,
44
)
45
46
tracker = agent_config.create_tracker()

Invoke the agent and track metrics. The Python example uses a track_langgraph_metrics helper that calls tracker.track_duration_of, then iterates over every message in the result and calls get_ai_metrics_from_response to aggregate token counts before calling tracker.track_tokens. The Node.js example uses tracker.trackMetricsOf with a langgraphMetrics converter that sums token counts across all messages the agent produced, with multiple fallback field names to handle different provider response shapes.

1
from ldai.tracker import TokenUsage
2
from ldai_langchain import get_ai_metrics_from_response
3
4
5
async def track_langgraph_metrics(tracker, func):
6
    """Track a LangGraph agent run. Aggregates token usage across every message
7
    the agent produced (get_ai_metrics_from_response per message), wrapping
8
    track_duration_of + manual success/tokens/error tracking."""
9
    try:
10
        result = await tracker.track_duration_of(func)
11
        tracker.track_success()
12
        total_in = total_out = total = 0
13
        for message in result.get("messages", []):
14
            metrics = get_ai_metrics_from_response(message)
15
            if metrics.tokens:
16
                total_in += metrics.tokens.input
17
                total_out += metrics.tokens.output
18
                total += metrics.tokens.total
19
        if total > 0:
20
            tracker.track_tokens(TokenUsage(input=total_in, output=total_out, total=total))
21
    except Exception:
22
        tracker.track_error()
23
        raise
24
    return result
25
26
27
async def run_turn(agent, tracker, user_input, thread_id):
28
    try:
29
        result = await track_langgraph_metrics(
30
            tracker,
31
            lambda: agent.ainvoke(
32
                {"messages": [{"role": "user", "content": user_input}]},
33
                config={"configurable": {"thread_id": thread_id}},
34
            ),
35
        )
36
        messages = result.get("messages", [])
37
        if messages:
38
            print(f"Agent: {messages[-1].content}")
39
    except Exception as e:
40
        print(f"Error: {e}")
41
42
43
thread_id = "demo-thread"
44
await run_turn(agent, tracker, "What's the status of order ORD-123?", thread_id)
45
await run_turn(agent, tracker, "What about ORD-456?", thread_id)
46
await run_turn(agent, tracker, "Summarize both orders for me.", thread_id)

The fallback argument to agent_config / agentConfig is optional. When omitted, LaunchDarkly returns a disabled config if the flag is off or the SDK is unreachable. Pass an explicit fallback to keep the agent running during outages.

Complete example

Here is a complete working example that combines all the steps.

1
import asyncio
2
import os
3
import ldclient
4
from ldclient import Context
5
from ldclient.config import Config
6
from ldai import LDAIClient
7
from ldai.tracker import TokenUsage
8
from ldai_langchain import create_langchain_model, get_ai_metrics_from_response
9
from langchain_core.tools import tool
10
from langgraph.prebuilt import create_react_agent
11
from langgraph.checkpoint.memory import MemorySaver
12
from dotenv import load_dotenv
13
14
load_dotenv()
15
16
SDK_KEY = os.environ.get("LAUNCHDARKLY_SDK_KEY")
17
AGENT_CONFIG_KEY = "langgraph-agent"
18
19
20
@tool
21
def get_order_status(order_id: str) -> str:
22
    """Look up the status of a customer order by order ID."""
23
    orders = {
24
        "ORD-123": "Shipped — arrives Thursday",
25
        "ORD-456": "Processing — estimated ship date: tomorrow",
26
        "ORD-789": "Delivered on Monday",
27
    }
28
    return orders.get(order_id, f"No order found with ID {order_id}")
29
30
31
async def track_langgraph_metrics(tracker, func):
32
    """Track a LangGraph agent run. Aggregates token usage across every message
33
    the agent produced (get_ai_metrics_from_response per message), wrapping
34
    track_duration_of + manual success/tokens/error tracking."""
35
    try:
36
        result = await tracker.track_duration_of(func)
37
        tracker.track_success()
38
        total_in = total_out = total = 0
39
        for message in result.get("messages", []):
40
            metrics = get_ai_metrics_from_response(message)
41
            if metrics.tokens:
42
                total_in += metrics.tokens.input
43
                total_out += metrics.tokens.output
44
                total += metrics.tokens.total
45
        if total > 0:
46
            tracker.track_tokens(TokenUsage(input=total_in, output=total_out, total=total))
47
    except Exception:
48
        tracker.track_error()
49
        raise
50
    return result
51
52
53
async def run_turn(agent, tracker, user_input, thread_id):
54
    try:
55
        result = await track_langgraph_metrics(
56
            tracker,
57
            lambda: agent.ainvoke(
58
                {"messages": [{"role": "user", "content": user_input}]},
59
                config={"configurable": {"thread_id": thread_id}},
60
            ),
61
        )
62
        messages = result.get("messages", [])
63
        if messages:
64
            print(f"Agent: {messages[-1].content}")
65
    except Exception as e:
66
        print(f"Error: {e}")
67
68
69
async def async_main():
70
    ldclient.set_config(Config(SDK_KEY))
71
    if not ldclient.get().is_initialized():
72
        print("LaunchDarkly SDK failed to initialize")
73
        return
74
75
    ai_client = LDAIClient(ldclient.get())
76
77
    context = Context.builder("user-123").kind("user").name("Sandy").build()
78
79
    # Pass a default for improved resiliency when the AgentControl config is unavailable
80
    # or LaunchDarkly is unreachable; omit for a disabled default.
81
    # Example:
82
    #   from ldai import AIAgentConfigDefault
83
    #   default = AIAgentConfigDefault(
84
    #       enabled=True,
85
    #       model={"name": "gpt-5"},
86
    #       provider={"name": "openai"},
87
    #       instructions="You are a helpful assistant.",
88
    #   )
89
    #   agent_config = ai_client.agent_config(AGENT_CONFIG_KEY, context, default)
90
    agent_config = ai_client.agent_config(AGENT_CONFIG_KEY, context)
91
92
    if not agent_config.enabled:
93
        print("Agent Config is disabled — run the notebook to set up the config")
94
        return
95
96
    # create_langchain_model reads agent_config.model.name / .parameters and picks the
97
    # right chat model class (OpenAI, Anthropic, …) with no per-provider branching.
98
    llm = create_langchain_model(agent_config)
99
100
    # MemorySaver gives the ReAct agent short-term memory per thread_id —
101
    # follow-up turns on the same thread see the earlier conversation.
102
    checkpointer = MemorySaver()
103
    agent = create_react_agent(
104
        llm,
105
        [get_order_status],
106
        prompt=agent_config.instructions,
107
        checkpointer=checkpointer,
108
    )
109
110
    tracker = agent_config.create_tracker()
111
112
    # Three turns on one thread: first fires the tool, second reuses memory
113
    # to answer a follow-up that reuses the tool, third summarizes — no tool.
114
    thread_id = "demo-thread"
115
    await run_turn(agent, tracker, "What's the status of order ORD-123?", thread_id)
116
    await run_turn(agent, tracker, "What about ORD-456?", thread_id)
117
    await run_turn(agent, tracker, "Summarize both orders for me.", thread_id)
118
119
    # Always flush events before closing — trailing events are at risk of being
120
    # lost otherwise, in short-lived scripts and long-running services alike.
121
    ldclient.get().flush()
122
    ldclient.get().close()
123
124
125
def main():
126
    asyncio.run(async_main())
127
128
129
if __name__ == "__main__":
130
    main()

Step 5: Monitor results

View metrics for your AgentControl config in the LaunchDarkly UI.

To monitor results:

1. In LaunchDarkly, navigate to your AgentControl config.
2. Select the Monitoring tab.

LaunchDarkly displays metrics including:

• Generation count
• Token usage (input, output, total)
• Time to generate
• Error rate

Use these metrics to compare agent performance, identify cost differences, and make data-driven decisions about which configuration to use for different user segments. To learn more, read Monitor AgentControl configs.

To view aggregated metrics across all your AgentControl configs, navigate to Insights in the left navigation under the AI section. The Insights overview page displays cost, latency, error rate, invocation counts, and model distribution across your organization. To learn more, read about AI insights.

Agent mode vs completion mode

Conclusion

In this guide, you learned how to integrate LangGraph agent workflows with LaunchDarkly AgentControl to manage agent configuration outside of your application code.

You can now:

• Change agent models and instructions without redeploying your application
• Target different agent configurations to different users based on context attributes
• Track and compare agent performance across variations
• Maintain conversation state with LangGraph checkpointing
• Coordinate multi-agent workflows with centralized configuration

To explore additional capabilities, read:

• Run experiments with AgentControl to compare agent variations using statistical analysis
• Config targeting to serve different agents to different user segments
• Agent graphs to orchestrate multi-agent workflows

For more AgentControl examples, read the other AgentControl guides in this section.