Getting started with Strands and AgentControl configs

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

This guide uses AgentControl’s agent mode. Agent mode uses a single instructions string, which maps directly to Strands’ system_prompt. To learn more, read Agents in AgentControl.

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.
• Strands Agents installed in your application.
• An API key for your chosen model provider.

Concepts

Before you begin, review these key concepts.

Strands agents

Strands provides a minimal, provider-agnostic framework for building tool-using agents. The Agent class accepts a model, a system_prompt, a list of tools, and an optional conversation_manager. It exposes invoke_async to run a single turn. The SlidingWindowConversationManager keeps the last N messages in memory so followup turns automatically reference earlier context without passing a thread or session ID.

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 tracker property for recording metrics. Call this function each time you create an agent so LaunchDarkly can evaluate targeting and return the current configuration.

Provider dispatch

Unlike LangChain, Strands does not currently have a first-party LaunchDarkly provider package. Each Strands model class is provider-specific and uses provider-specific names: AnthropicModel for Anthropic, OpenAIModel for OpenAI, and so on. To serve different providers from a single AgentControl config, dispatch on agent_config.provider.name and construct the matching Strands model class. This guide includes a create_strands_model helper that does this for you.

Step 1: Install dependencies

Install the LaunchDarkly SDKs and Strands packages.

$
pip install launchdarkly-server-sdk launchdarkly-server-sdk-ai strands-agents strands-agents-tools anthropic openai boto3 python-dotenv

Step 2: Create an AgentControl config in LaunchDarkly

Create an AgentControl config in agent mode to store your agent configuration. This guide creates two variations, one backed by OpenAI and one backed by Anthropic, to show you how Strands dispatches to different providers from the same AgentControl config key.

To create an AgentControl config:

1. In the left sidebar, click Create and select AgentControl config.
2. In the “Create AgentControl config” dialog, select Agent.
3. Enter a name for your AgentControl config and set the key to strands-agent.
4. Click Create. The new AgentControl config appears.

Then, create the first variation:

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

You are a helpful order-status assistant. Use the get_order_status tool to look up orders by their ID. Always explain your reasoning and summarize results clearly.

5. Click Review and save.

Add a second variation:

1. Click Add variation and name the new variation “Claude Sonnet agent”.
2. Click Select a model and choose the claude-sonnet-4 Anthropic model.
3. Click Parameters and set max_tokens to 2000.
4. Use the same instructions as the first variation.
5. Click Review and save.

Step 3: Set up targeting rules

Configure targeting rules to control which users receive which variation. Serve the “GPT-5 agent” variation as the default so the Node.js example runs without changes, and target specific users or segments to the “Claude Sonnet agent” variation.

To create 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 the “GPT-5 agent” variation.
4. Click Review and save.

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

Step 4: Integrate Strands with AgentControl configs

With the AgentControl config and targeting in place, integrate Strands with the LaunchDarkly AI SDK so your application fetches the current model, instructions, and parameters on every request instead of reading hardcoded values. Because Strands does not currently have a first-party LaunchDarkly provider package, the integration involves mapping the AgentControl config payload to the matching Strands model class yourself.

Complete these steps in order, since each depends on the previous one.

The integration involves these key steps:

1. Define the tools your agent can call using the Strands @tool decorator (Python) or tool() helper (Node.js).
2. Build a provider dispatcher that maps agent_config.provider.name to the matching Strands model class.
3. Initialize the LaunchDarkly base SDK client with your SDK key.
4. Initialize the LaunchDarkly AI client from the base client.
5. Get the agent config using agent_config() (Python) or aiClient.agentConfig() (Node.js).
6. Build a Strands Agent with a SlidingWindowConversationManager for short-term memory.
7. Invoke the agent and track metrics with the AgentControl config’s tracker.

The following example defines a get_order_status tool that looks up a customer order by its ID. The tool handler returns the order status text your agent will summarize in its reply. In Python, the @tool decorator reads the function’s type hints and docstring to generate the JSON schema Strands passes to the model. In Node.js, the tool() helper takes the name, description, and an explicit Zod input schema.

1
from strands 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}")
13
14
15
# Map tool keys (matching the LaunchDarkly tool keys) to local handlers. The agent
16
# build step resolves the active tool list from `agent_config.tools` so detaching
17
# `get_order_status` from the variation in LaunchDarkly takes effect on the next
18
# agent invocation, with no code change.
19
TOOL_REGISTRY = {"get_order_status": get_order_status}

Build a provider dispatcher. Strands model classes are provider-specific, so read agent_config.provider.name and construct the matching class. LaunchDarkly surfaces attached tools via a flat parameters.tools shape in the variation payload. Drop that key before passing parameters through, because Strands receives tools from the Agent constructor.

1
import os
2
from strands.models.anthropic import AnthropicModel
3
from strands.models.openai import OpenAIModel
4
from strands.models.bedrock import BedrockModel
5
6
7
def create_strands_model(agent_config):
8
    """Map an LDAIAgentConfig to the matching Strands model class by provider."""
9
    provider = (agent_config.provider.name if agent_config.provider else "").lower()
10
    model_id = agent_config.model.name
11
    params = dict(agent_config.model.to_dict().get("parameters") or {})
12
    # LaunchDarkly surfaces attached tools from `parameters.tools` in its own flat shape.
13
    # Drop the key here. Strands receives tools from the Agent constructor.
14
    params.pop("tools", None)
15
16
    is_bedrock = provider == "bedrock" or model_id.startswith(
17
        ("us.", "eu.", "apac.", "anthropic.", "amazon.", "meta.")
18
    )
19
20
    if is_bedrock:
21
        region = (
22
            params.pop("region_name", None)
23
            or os.environ.get("AWS_REGION")
24
            or "us-west-2"
25
        )
26
        known = {
27
            k: params.pop(k)
28
            for k in ("max_tokens", "temperature", "top_p", "stop_sequences")
29
            if k in params
30
        }
31
        if "max_tokens" not in known:
32
            known["max_tokens"] = 1024
33
        return BedrockModel(
34
            model_id=model_id,
35
            region_name=region,
36
            additional_request_fields=params or None,
37
            **known,
38
        )
39
    if provider == "anthropic":
40
        # AnthropicModel requires max_tokens as a kwarg, not in params.
41
        max_tokens = int(params.pop("max_tokens", None) or params.pop("maxTokens", None) or 1024)
42
        return AnthropicModel(model_id=model_id, max_tokens=max_tokens, params=params or None)
43
    if provider == "openai":
44
        # Pass parameters through unchanged. GPT-5 wants `max_completion_tokens`,
45
        # GPT-4o wants `max_tokens`. Keep that choice in the AgentControl config variation.
46
        return OpenAIModel(model_id=model_id, params=params)
47
    raise ValueError(f"Unsupported provider for Strands: {provider!r}")

Initialize the LaunchDarkly SDK and AI client, fetch the agent config, build the Strands model with create_strands_model (Python) or createStrandsModel (Node.js), and create the agent.

1
import os
2
import ldclient
3
from ldclient import Context
4
from ldclient.config import Config
5
from ldai import LDAIClient
6
from strands import Agent
7
from strands.agent.conversation_manager.sliding_window_conversation_manager import (
8
    SlidingWindowConversationManager,
9
)
10
11
12
ldclient.set_config(Config(os.environ.get("LAUNCHDARKLY_SDK_KEY")))
13
if not ldclient.get().is_initialized():
14
    raise RuntimeError("LaunchDarkly SDK failed to initialize")
15
16
ai_client = LDAIClient(ldclient.get())
17
18
context = Context.builder("user-123").kind("user").name("Sandy").build()
19
20
# Pass a default for improved resiliency when the AgentControl config is unavailable
21
# or LaunchDarkly is unreachable. Omit it to disable the default.
22
# Example:
23
#   from ldai import AIAgentConfigDefault
24
#   default = AIAgentConfigDefault(
25
#       enabled=True,
26
#       model={"name": "gpt-5"},
27
#       provider={"name": "openai"},
28
#       instructions="You are a helpful assistant.",
29
#   )
30
#   agent_config = ai_client.agent_config("strands-agent", context, default)
31
agent_config = ai_client.agent_config("strands-agent", context)
32
if not agent_config.enabled:
33
    raise RuntimeError("Agent Config is disabled")
34
35
model = create_strands_model(agent_config)
36
37
# Resolve the agent's tool list from the LaunchDarkly variation. AIAgentConfig.tools
38
# is the typed surface in SDK 0.20+ (a dict of name -> LDTool) — no more digging
39
# through model.parameters.
40
ld_tool_names = list(agent_config.tools or {})
41
resolved_tools = [TOOL_REGISTRY[n] for n in ld_tool_names if n in TOOL_REGISTRY]
42
43
# SlidingWindowConversationManager gives the agent short-term memory across turns.
44
conversation_manager = SlidingWindowConversationManager(window_size=40)
45
46
agent = Agent(
47
    name="order-assistant",
48
    model=model,
49
    system_prompt=agent_config.instructions,
50
    tools=resolved_tools,
51
    conversation_manager=conversation_manager,
52
)

Invoke the agent and track metrics. Each turn is one execution as far as the tracker is concerned: the SDK assigns a fresh runId per create_tracker() or createTracker() call and enforces at-most-once tracking for success, error, tokens, and duration. Build a new tracker inside run_turn for each invocation.

Strands returns an AgentResult whose metrics.accumulated_usage (Python) or metrics.accumulatedUsage (Node.js) aggregates token counts across every provider call in the turn, including any round trips to call tools. The Python example uses tracker.track_metrics_of_async with an extractor that returns an LDAIMetrics carrying token usage and the per-tool call list reconstructed from metrics.tool_metrics. The @tool handler stays a pure business function and the SDK fires one track_tool_call event per invocation when the turn completes. The Node.js example uses tracker.trackMetricsOf with a converter that returns the usage shape the tracker expects; tool calls are recorded from a trackToolCall call inside the tool callback, with the active tracker referenced via a module-level binding.

1
from ldai.tracker import TokenUsage
2
from ldai.providers import LDAIMetrics
3
4
5
def strands_metrics_extractor(result):
6
    """Pull token usage and tool calls off a Strands AgentResult into an LDAIMetrics.
7
8
    Strands' EventLoopMetrics records every tool invocation in `tool_metrics`
9
    (keyed by tool name, with a per-tool `call_count`). Flattening that map into
10
    a list of tool keys lets the LaunchDarkly SDK fire one `track_tool_call`
11
    per invocation without the @tool body needing access to the tracker.
12
    """
13
    usage = getattr(result.metrics, "accumulated_usage", {}) or {}
14
    input_tokens = usage.get("inputTokens", 0)
15
    output_tokens = usage.get("outputTokens", 0)
16
    total = usage.get("totalTokens", 0) or (input_tokens + output_tokens)
17
18
    tool_calls = []
19
    for tool_name, tm in (result.metrics.tool_metrics or {}).items():
20
        tool_calls.extend([tool_name] * tm.call_count)
21
22
    return LDAIMetrics(
23
        success=True,
24
        tokens=TokenUsage(input=input_tokens, output=output_tokens, total=total) if total > 0 else None,
25
        tool_calls=tool_calls or None,
26
    )
27
28
29
async def run_turn(agent, user_input):
30
    # Each tracker is one execution (its own runId, at-most-once for
31
    # success/error/tokens/duration/tool_call). Build a fresh tracker per turn.
32
    tracker = agent_config.create_tracker()
33
    try:
34
        result = await tracker.track_metrics_of_async(
35
            strands_metrics_extractor,
36
            lambda: agent.invoke_async(user_input),
37
        )
38
        print(f"Agent: {result.message['content'][0]['text']}")
39
    except Exception as e:
40
        print(f"Error: {e}")
41
42
43
# Three turns on the same agent instance: first fires the tool, second reuses
44
# conversation memory for a follow-up that reuses the tool, third summarizes
45
# without calling any tool.
46
await run_turn(agent, "What's the status of order ORD-123?")
47
await run_turn(agent, "What about ORD-456?")
48
await run_turn(agent, "Summarize both orders for me.")

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.providers import LDAIMetrics
9
from strands import Agent, tool
10
from strands.models.anthropic import AnthropicModel
11
from strands.models.openai import OpenAIModel
12
from strands.models.bedrock import BedrockModel
13
from strands.agent.conversation_manager.sliding_window_conversation_manager import (
14
    SlidingWindowConversationManager,
15
)
16
from dotenv import load_dotenv
17
18
load_dotenv()
19
20
SDK_KEY = os.environ.get("LAUNCHDARKLY_SDK_KEY")
21
AGENT_CONFIG_KEY = "strands-agent"
22
23
@tool
24
def get_order_status(order_id: str) -> str:
25
    """Look up the status of a customer order by order ID."""
26
    orders = {
27
        "ORD-123": "Shipped — arrives Thursday",
28
        "ORD-456": "Processing — estimated ship date: tomorrow",
29
        "ORD-789": "Delivered on Monday",
30
    }
31
    return orders.get(order_id, f"No order found with ID {order_id}")
32
33
34
# Map tool keys (matching the LaunchDarkly tool keys) to local handlers. The agent
35
# build step resolves the active tool list from `agent_config.tools` at runtime.
36
TOOL_REGISTRY = {"get_order_status": get_order_status}
37
38
39
def create_strands_model(agent_config):
40
    """Map an LDAIAgentConfig to the matching Strands model class by provider."""
41
    provider = (agent_config.provider.name if agent_config.provider else "").lower()
42
    model_id = agent_config.model.name
43
    params = dict(agent_config.model.to_dict().get("parameters") or {})
44
    # LaunchDarkly surfaces attached tools from `parameters.tools` in its own flat shape.
45
    # Drop the key here. Strands receives tools from the agent constructor.
46
    params.pop("tools", None)
47
48
    is_bedrock = provider == "bedrock" or model_id.startswith(
49
        ("us.", "eu.", "apac.", "anthropic.", "amazon.", "meta.")
50
    )
51
52
    if is_bedrock:
53
        region = (
54
            params.pop("region_name", None)
55
            or os.environ.get("AWS_REGION")
56
            or "us-west-2"
57
        )
58
        known = {
59
            k: params.pop(k)
60
            for k in ("max_tokens", "temperature", "top_p", "stop_sequences")
61
            if k in params
62
        }
63
        if "max_tokens" not in known:
64
            known["max_tokens"] = 1024
65
        return BedrockModel(
66
            model_id=model_id,
67
            region_name=region,
68
            additional_request_fields=params or None,
69
            **known,
70
        )
71
    if provider == "anthropic":
72
        # AnthropicModel requires max_tokens as a kwarg, not in params.
73
        max_tokens = int(params.pop("max_tokens", None) or params.pop("maxTokens", None) or 1024)
74
        return AnthropicModel(model_id=model_id, max_tokens=max_tokens, params=params or None)
75
    if provider == "openai":
76
        # Pass parameters through unchanged. GPT-5 wants `max_completion_tokens`,
77
        # GPT-4o wants `max_tokens`. Keep that choice in the LaunchDarkly variation.
78
        return OpenAIModel(model_id=model_id, params=params)
79
    raise ValueError(f"Unsupported provider for Strands: {provider!r}")
80
81
82
def strands_metrics_extractor(result):
83
    """Pull token usage and tool calls off a Strands AgentResult into an LDAIMetrics."""
84
    usage = getattr(result.metrics, "accumulated_usage", {}) or {}
85
    input_tokens = usage.get("inputTokens", 0)
86
    output_tokens = usage.get("outputTokens", 0)
87
    total = usage.get("totalTokens", 0) or (input_tokens + output_tokens)
88
89
    tool_calls = []
90
    for tool_name, tm in (result.metrics.tool_metrics or {}).items():
91
        tool_calls.extend([tool_name] * tm.call_count)
92
93
    return LDAIMetrics(
94
        success=True,
95
        tokens=TokenUsage(input=input_tokens, output=output_tokens, total=total) if total > 0 else None,
96
        tool_calls=tool_calls or None,
97
    )
98
99
100
async def async_main():
101
    ldclient.set_config(Config(SDK_KEY))
102
    if not ldclient.get().is_initialized():
103
        print("LaunchDarkly SDK failed to initialize")
104
        return
105
106
    ai_client = LDAIClient(ldclient.get())
107
108
    context = Context.builder("user-123").kind("user").name("Sandy").build()
109
110
    # Pass a default for improved resiliency when the AgentControl config is unavailable
111
    # or LaunchDarkly is unreachable. Omit it to disable the default.
112
    # Example:
113
    #   from ldai import AIAgentConfigDefault
114
    #   default = AIAgentConfigDefault(
115
    #       enabled=True,
116
    #       model={"name": "gpt-5"},
117
    #       provider={"name": "openai"},
118
    #       instructions="You are a helpful assistant.",
119
    #   )
120
    #   agent_config = ai_client.agent_config(AGENT_CONFIG_KEY, context, default)
121
    agent_config = ai_client.agent_config(AGENT_CONFIG_KEY, context)
122
123
    if not agent_config.enabled:
124
        print("Agent Config is disabled — run the notebook to set up the config")
125
        return
126
127
    model = create_strands_model(agent_config)
128
129
    # Resolve the agent's tool list from the LaunchDarkly variation. AIAgentConfig.tools
130
    # is the typed surface in SDK 0.20+ (a dict of name -> LDTool) — no more digging
131
    # through model.parameters.
132
    ld_tool_names = list(agent_config.tools or {})
133
    resolved_tools = [TOOL_REGISTRY[n] for n in ld_tool_names if n in TOOL_REGISTRY]
134
135
    # SlidingWindowConversationManager gives the agent short-term memory across turns.
136
    conversation_manager = SlidingWindowConversationManager(window_size=40)
137
138
    agent = Agent(
139
        name="order-assistant",
140
        model=model,
141
        system_prompt=agent_config.instructions,
142
        tools=resolved_tools,
143
        conversation_manager=conversation_manager,
144
    )
145
146
    async def run_turn(agent, user_input):
147
        # Fresh tracker per turn (each is one execution: own runId, at-most-once
148
        # for success/error/tokens/duration/tool_call). The extractor flattens
149
        # `result.metrics.tool_metrics` into the `tool_calls` field of LDAIMetrics,
150
        # which the SDK turns into one track_tool_call event per invocation.
151
        tracker = agent_config.create_tracker()
152
        try:
153
            result = await tracker.track_metrics_of_async(
154
                strands_metrics_extractor,
155
                lambda: agent.invoke_async(user_input),
156
            )
157
            print(f"Agent: {result.message['content'][0]['text']}")
158
        except Exception as e:
159
            print(f"Error: {e}")
160
161
    await run_turn(agent, "What's the status of order ORD-123?")
162
    await run_turn(agent, "What about ORD-456?")
163
    await run_turn(agent, "Summarize both orders for me.")
164
165
    # Always flush events before closing. Otherwise, trailing events are at risk of being
166
    # lost, in both short-lived scripts and long-running services.
167
    ldclient.get().flush()
168
    ldclient.get().close()
169
170
171
def main():
172
    asyncio.run(async_main())
173
174
175
if __name__ == "__main__":
176
    main()

Step 5: Monitor results

View metrics for your AgentControl config in the LaunchDarkly UI.

To monitor results, navigate to your AgentControl config and click 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 across the OpenAI and Anthropic variations, 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 sidebar 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.

Comparing agent mode and completion mode

Conclusion

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

You can now:

• Change agent models and instructions without redeploying your application
• Swap between Anthropic and OpenAI-backed variations from a single AgentControl config key
• Target different agent configurations to different users based on context attributes
• Track and compare agent performance across variations
• Maintain multi-turn conversation memory with SlidingWindowConversationManager
• Govern tools centrally in LaunchDarkly and attach them to variations

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
• Agents in AgentControl for a deeper look at agent mode

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