> ## Documentation Index
> Fetch the complete documentation index at: https://launchdarkly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Customizing AgentControl configs

<View title="Developer" />

<View title="Federal docs" />

<View title="EU docs" />

This topic explains how to customize an AgentControl config using LaunchDarkly AI SDKs.

Customizing a config evaluates the configuration for a given context and returns the appropriate variation based on targeting rules. Customization requires a config key, a context, a fallback value, and optional variables for substitution.

In completion mode, the customized variation includes the model configuration and messages for the context. In agent mode, the customized variation includes the instructions for the context. In both cases, you must customize the config each time you generate content from your AI model.

## Customize messages

Customizing a config substitutes context attributes and optional variables into the messages or instructions defined in the config variation. If a variation includes multiple messages, all messages are customized and returned.

If the SDK cannot retrieve the variation, such as when the config key does not exist or LaunchDarkly is unreachable, the SDK returns the fallback value.

### Syntax for customization

When you create a message or instruction in a config variation, use the following syntax to substitute context attributes or other variables.

* Use double curly braces to indicate variables provided by your application. For example:
  * Enter `This is an {{ example }}` in the message or instruction in the LaunchDarkly UI. Variable names cannot include a period (`.`).
  * In the SDK, pass a dictionary or key-value pair with the key `example` and the value to substitute.

* Use double curly braces with the `ldctx` prefix and dot (`.`) notation to reference [context attributes](/docs/home/flags/context-attributes). For example:
  * Enter `Describe the typical weather in {{ ldctx.city }}` to substitute the `city` attribute from each context that encounters the config.
  * Context attribute names cannot include a period (`.`). To reference nested attributes, use dot notation in the message or instruction. For example, if the context includes an `address` object with a `city` field, use `{{ ldctx.address.city }}`.
  * In the SDK, the context is a required parameter. You do not need to pass additional variables when using `ldctx`.

### Customization is based on context

Customization adds a [context](/docs/home/getting-started/vocabulary#context) to the **Contexts** list if a context with the same key does not already exist. Each SDK evaluates the config using only the context object you provide at runtime.

The SDK does not automatically use attributes shown on the **Contexts** list, and attributes are not synchronized across SDK instances. Provide all required attributes with each customization to ensure variables in messages or instructions are substituted correctly. To learn more, read [Context configuration](/docs/sdk/features/context-config).

## AI SDKs

This feature is available for the following AI SDKs:

* [.NET AI](#net-ai)
* [Go AI](#go-ai)
* [Node.js (server-side) AI](#nodejs-server-side-ai)
* [Node.js (server-side) AI (turnkey)](#nodejs-server-side-ai-turnkey)
* [Python AI](#python-ai)
* [Ruby AI](#ruby-ai)

### .NET AI

<Accordion title="Expand .NET AI SDK code sample">
  Use the `Config` function to customize an AgentControl config. Customization substitutes context attributes and variables into the prompt messages defined in the config variation. You must call `Config` each time you generate content from your AI model.

  The `Config` function takes the config key, a `Context`, a [fallback value](/docs/home/getting-started/vocabulary#fallback-value), and optional additional variables to substitute into your prompt. It performs the evaluation, then returns the customized prompt and model along with a tracker instance for recording prompt metrics. You can pass the customized prompt directly to your AI.

  The fallback value is the value of the config variation that your application should use in the event of an error, for example, if the config key is not valid, or if there is a problem connecting to LaunchDarkly. You can use `LdAiConfig.Disabled` as a fallback value and handle the disabled case in your application.

  Alternatively, you can create a custom `LdAiConfig` object using `LdAiConfig.New()`.

  Here is an example of calling the `Config` method:

  <CodeGroup>
    ```csharp title=".NET AI SDK" expandable lines wrap theme={null}
    var fallbackConfig = LdAiCompletionConfigDefault.New()
      .SetEnabled(false)
      .Build();

    var config = aiClient.Config(
      "example-config-key",
      context,
      fallbackConfig,
      new Dictionary<string, object> {
        { "exampleCustomVariable", "exampleCustomValue" }
      }
    );

    if (config.Enabled == true) {

      // Send a request to your AI provider, using the details from the customized config

    } else {

      // Application path to take when the config is disabled

    }

    ```
  </CodeGroup>

  After the function call, you can view the context that you provided to it on the **Contexts** list.

  To learn more, read [`Config`](https://launchdarkly.github.io/dotnet-core/pkgs/sdk/server-ai/api/LaunchDarkly.Sdk.Server.Ai.LdAiClient.html#LaunchDarkly_Sdk_Server_Ai_LdAiClient_Config_System_String_LaunchDarkly_Sdk_Context_LaunchDarkly_Sdk_Server_Ai_Config_LdAiConfig_System_Collections_Generic_IReadOnlyDictionary_System_String_System_Object__).
</Accordion>

### Go AI

<Accordion title="Expand Go AI SDK code sample">
  Use the `CompletionConfig()` function to customize an AgentControl config. Customization substitutes context attributes and variables into the prompt messages defined in the config variation.

  The `CompletionConfig()` function takes a config key, a context, and a [fallback value](/docs/home/getting-started/vocabulary#fallback-value). It performs the evaluation and returns an `AICompletionConfig` object with the customized messages and model. You can pass the customized messages directly to your AI. To capture performance metrics, call `CreateTracker()` on the returned config to obtain a `Tracker`.

  The fallback value is used when an error occurs, such as when the config key is invalid or LaunchDarkly is unreachable. You can use an empty, disabled default as a fallback value by calling `ldai.NewAICompletionConfigDefault().Disabled()` and handle the disabled case in your application. Alternatively, you can create a custom default using `NewAICompletionConfigDefault`.

  Here is an example of calling the `CompletionConfig()` method:

  <CodeGroup>
    ```go title="Go AI SDK" lines wrap theme={null}
    defaultValue := ldai.NewAICompletionConfigDefault().Disabled() // used when the config can't be evaluated

    cfg := aiClient.CompletionConfig("example-config-key", context, defaultValue, map[string]interface{}{"exampleCustomVariable": "exampleCustomValue"})
    tracker := cfg.CreateTracker()

    if cfg.Enabled() {

      // Send a request to your AI provider, using details from the customized cfg

    } else {

      // Application path to take when the cfg is disabled

    }

    ```
  </CodeGroup>

  After the function call, you can open or review the context that you provided to it on the **Contexts** list.

  To learn more, read [`AICompletionConfig`](https://pkg.go.dev/github.com/launchdarkly/go-server-sdk-ai/ldai#AICompletionConfig).
</Accordion>

### Java AI

<Accordion title="Expand Java AI SDK code sample">
  The `completionConfig`, `agentConfig`, and `agentConfigs` methods customize the AgentControl config at runtime. Customization substitutes context attributes and optional variables into the messages or instructions defined in the config variation.

  The customization behavior depends on whether the config uses completion mode or agent mode. You select the mode when you create the config in the LaunchDarkly UI.

  #### Customize configs in completion mode

  In completion mode, each config variation includes a single set of roles and messages used to prompt your generative AI model.

  In completion mode, use `completionConfig` to customize the config. The method takes an AgentControl config key, a context, a fallback value, and optional additional variables to substitute into your prompt. It performs the evaluation, then returns an `AICompletionConfig` object with the customized model, provider, and messages. Call `createTracker` on the returned object to get a tracker instance for recording metrics.

  The fallback value is used when an error occurs, such as when the config key is invalid or LaunchDarkly is unreachable. You can use an empty, disabled `AICompletionConfigDefault` as a fallback value and handle the disabled case in your application. Alternatively, you can construct a fully configured default.

  Here is an example of calling the `completionConfig` method:

  <CodeGroup>
    ```java title="Customize a config in completion mode" lines wrap theme={null}
    Map<String, Object> variables = new HashMap<>();
    variables.put("exampleCustomVariable", "exampleCustomValue");
     
    AICompletionConfig config = aiClient.completionConfig(
      "example-config-key",
      context,
      AICompletionConfigDefault.disabled(),
      variables
    );
     
    if (config.isEnabled()) {
     
      // Send a request to your AI provider, using the customized config
     
    } else {
     
      // Application path to take when the config is disabled
     
    }
    ```
  </CodeGroup>

  After the method call, you can view the context that you provided to it on the **Contexts** list.

  #### Customize configs in agent mode

  In agent mode, each config variation includes a set of instructions that enable multi-step workflows.

  In agent mode, use `agentConfig` to customize a single agent config, or `agentConfigs` to customize a batch of them in one call.

  The instructions returned by the SDK come directly from the instructions you define for the config variation in the LaunchDarkly UI.

  Customization requires a config key, a context, a fallback value, and optional variables. The method performs the evaluation and returns the customized instructions along with a tracker instance for recording metrics. If the SDK cannot perform the evaluation or LaunchDarkly is unreachable, it returns the fallback value.

  For example, you might use an empty, disabled `AIAgentConfigDefault` as a fallback value and handle the disabled case in your application.

  Here is an example of customizing a config in agent mode:

  <CodeGroup>
    ```java title="Customize a config in agent mode" lines wrap theme={null}
    Map<String, Object> variables = new HashMap<>();
    variables.put("exampleCustomVariable", "exampleCustomValue");
     
    AIAgentConfig agent = aiClient.agentConfig(
      "example-config-key",
      context,
      AIAgentConfigDefault.disabled(),
      variables
    );
    ```
  </CodeGroup>

  To retrieve multiple agent configs in one call, use `agentConfigs`. Each request pairs a config key with its own fallback value and variables, and is evaluated independently, so a failure in one request does not affect the others. The method returns a map keyed by config key.

  Here is an example of retrieving multiple agent configs at once:

  <CodeGroup>
    ```java title="Retrieve multiple agent configs" lines wrap theme={null}
    List<AIAgentConfigRequest> requests = List.of(
      AIAgentConfigRequest.builder("summarizer-agent")
        .defaultValue(AIAgentConfigDefault.disabled())
        .variables(variables)
        .build(),
      AIAgentConfigRequest.builder("validator-agent")
        .defaultValue(AIAgentConfigDefault.disabled())
        .variables(variables)
        .build()
    );

    Map<String, AIAgentConfig> agents = aiClient.agentConfigs(requests, context);

    AIAgentConfig summarizer = agents.get("summarizer-agent");
    AIAgentConfig validator = agents.get("validator-agent");
    ```
  </CodeGroup>
</Accordion>

### Node.js (server-side) AI

<Accordion title="Expand Node.js (server-side) AI SDK code sample">
  The `completionConfig()`, `agentConfig()`, and `agentConfigs()` functions customize the AgentControl config at runtime. Customization substitutes context attributes and optional variables into the messages or instructions defined in the config variation.

  The customization behavior depends on whether the config uses completion mode or agent mode. You select the mode when you create the config in the LaunchDarkly UI.

  #### Customize configs in completion mode

  In completion mode, each config variation includes a single set of roles and messages used to prompt your generative AI model.

  In `completion` mode, use `completionConfig()` to customize the config. The `completionConfig` function takes the config key, a `Context`, a [fallback value](/docs/home/getting-started/vocabulary#fallback-value), and optional additional variables to substitute into your prompt. It performs the evaluation, then returns the customized prompt and model along with a tracker instance for recording prompt metrics. You can pass the customized prompt directly to your AI.

  The fallback value is used when an error occurs, such as when the config key is invalid or LaunchDarkly is unreachable. You can use an empty, disabled configuration as a fallback value and handle the disabled case in your application. Alternatively, you can construct a fallback configuration using values from a config variation defined in the LaunchDarkly UI.

  Here is an example of calling the `completionConfig()` method:

  <CodeGroup>
    ```ts title="Customize a config in completion mode" lines wrap theme={null}
    const fallbackConfig = { enabled: false };

    const aiConfig: LDAIConfig = await aiClient.completionConfig(
      'example-config-key',
      context,
      fallbackConfig,
      { exampleCustomVariable: 'exampleCustomValue' },
    );

    if (aiConfig.enabled) {
      // Send a request to your AI provider using the customized config
    } else {
      // Application path to take when the config is disabled
    }
    ```
  </CodeGroup>

  #### Customize configs in agent mode

  In agent mode, each config variation includes a set of instructions that enable multi-step workflows.

  In `agent` mode, use `agentConfig()` or `agentConfigs()` to customize the config. The `agentConfig()` function customizes a single agent config, while the `agentConfigs()` function customizes an array of agent configurations.

  The instructions returned by the SDK come directly from the instructions you define for the config variation in the LaunchDarkly UI. The goal or task shown in the UI is delivered unchanged as the `instructions` field in the SDK.

  Customization requires a config key, a fallback value, optional variables, and a context. Both functions perform the evaluation and return the customized instructions along with a tracker instance for recording metrics. If the SDK cannot perform the evaluation or LaunchDarkly is unreachable, it returns the fallback value.

  For example, you might use an empty, disabled agent-mode configuration as a fallback value and handle the disabled case in your application.

  Here is an example of customizing a config in agent mode:

  <CodeGroup>
    ```ts title="Customize a config in agent mode" lines wrap theme={null}
    const fallbackConfig = { enabled: false };

    const agent: LDAIAgentConfig = await aiClient.agentConfig(
      'example-config-key',
      context,
      fallbackConfig,
      { 'exampleCustomVariable': 'exampleCustomValue' },
    );
    ```
  </CodeGroup>

  To learn more, read [agent](https://launchdarkly-python-sdk-ai.readthedocs.io/en/latest/api-main.html#ldai.client.LDAIClient.agent) and [agents](https://launchdarkly-python-sdk-ai.readthedocs.io/en/latest/api-main.html#ldai.client.LDAIClient.agents).
</Accordion>

### Node.js (server-side) AI (turnkey)

<Accordion title="Expand turnkey Node.js (server-side) AI SDK code sample">
  The turnkey Node.js (server-side) AI SDK replaces `completionConfig()`, `agentConfig()`, and `agentConfigs()` with a single set of entry points: `config()`, `graph()`, and the provider convenience functions. You do not customize a config and then call the model yourself. Instead, you call the model directly, and the SDK evaluates and customizes the config for you.

  You pass customization variables as the third argument to `invoke()`. The SDK substitutes them into the messages or instructions defined in the config variation, and it also injects the context under the `ldContext` key so templates can reference context attributes.

  Here is an example of customizing and invoking a config:

  <CodeGroup>
    ```ts title="Customize and call a config" lines wrap theme={null}
    import { config } from '@launchdarkly/ai-server';
    import { createOpenAIHandler } from '@launchdarkly/ai-openai-messages';

    const result = await config({
      key: 'example-config-key',
      handler: [createOpenAIHandler()],
    }).invoke(
      'What is feature flagging?',
      { kind: 'user', key: 'example-user-key' },
      { exampleCustomVariable: 'exampleCustomValue' },
    );

    console.log(result.response);
    ```
  </CodeGroup>

  To learn more, read [Call a model](/docs/sdk/ai/node-js#call-a-model) in the turnkey Node.js (server-side) AI SDK reference.
</Accordion>

### Python AI

<Accordion title="Expand Python AI SDK code sample">
  The `completion_config()`, `agent_config()`, and `agent_configs()` functions customize the AgentControl config at runtime. Customization substitutes context attributes and optional variables into the messages or instructions defined in the config variation.

  The customization behavior depends on whether the config uses completion mode or agent mode. You select the mode when you create the config in the LaunchDarkly UI.

  #### Customize configs in completion mode

  In completion mode, each config variation includes a single set of roles and messages used to prompt the generative AI model.

  In `completion` mode, use `completion_config()` to customize the config. The `completion_config()` function takes a config key, a context, and a fallback value. It performs the evaluation, then returns the customized messages and model along with a tracker instance for recording metrics.

  The fallback value is used when an error occurs, such as when the config key is invalid or LaunchDarkly is unreachable. You can use an empty, disabled configuration as a fallback value and handle the disabled case in your application. Alternatively, you can construct a fallback configuration using values from a config variation defined in the LaunchDarkly UI.

  Here is an example of calling the `completion_config()` method:

  <CodeGroup>
    ```python title="Customize a config in completion mode" expandable lines wrap theme={null}
    key = 'example-config-key'
    context = Context.builder('example-context-key') \
      .kind('user') \
      .set('name', 'Sandy') \
      .build()
    fallback_value = AICompletionConfigDefault(enabled=False)
    variables = { 'example_custom_variable': 'example_custom_value' }

    config = aiclient.completion_config(key, context, fallback_value, variables)

    if config.enabled:
      # Send a request to your AI provider using the customized config
      pass
    else:
      # Application path to take when the config is disabled
      pass
    ```
  </CodeGroup>

  After the function call, you can view the context that you provided to it on the **Contexts** list.

  To learn more, read [`config`](https://launchdarkly-python-sdk-ai.readthedocs.io/en/latest/api-main.html#ldai.client.LDAIClient.config).

  #### Customize configs in agent mode

  In agent mode, each config variation includes a set of instructions that enable multi-step workflows.

  In `agent` mode, use `agent_config()` or `agent_configs()` to customize the config. The `agent_config()` function customizes a single agent config, while the `agent_configs()` function customizes a list of them.

  The instructions returned by the SDK come directly from the instructions you define for the config variation in the LaunchDarkly UI. The goal or task shown in the UI is delivered unchanged as the `instructions` field in the SDK.

  Customization requires a config key, a fallback value, optional variables, and a context. Both functions perform the evaluation and return the customized instructions along with a tracker instance for recording metrics. If the SDK cannot perform the evaluation or LaunchDarkly is unreachable, it returns the fallback value.

  For example, you might use an empty, disabled agent-mode configuration as a fallback value and handle the disabled case in your application.

  Here is an example of customizing a config in agent mode:

  <CodeGroup>
    ```python title="Customize a config in agent mode" lines wrap theme={null}
    from ldai import AIAgentConfigDefault

    agent = aiclient.agent_config(
      'example-config-key',
      context,
      AIAgentConfigDefault(
        enabled=False
      ),
      { 'example_custom_variable': 'example_custom_value'}
    )
    ```
  </CodeGroup>
</Accordion>

### Ruby AI

<Accordion title="Expand Ruby AI SDK code sample">
  Use the `config` function to customize an AgentControl config. Customization substitutes context attributes and optional variables into the prompt messages defined in the config variation. You must call `config` each time you generate content from your AI model.

  The `config` function takes a config key, a `Context`, a [fallback value](/docs/home/getting-started/vocabulary#fallback-value), and optional variables for substitution. It performs the evaluation and returns the customized prompt and model along with a tracker instance for recording metrics. You can pass the customized prompt directly to your AI provider.

  The fallback value is used when an error occurs, such as when the config key is invalid or LaunchDarkly is unreachable. You can use an empty, disabled configuration as a fallback value and handle the disabled case in your application. Alternatively, you can construct a fallback configuration using values from a config variation defined in the LaunchDarkly UI.

  Here is an example of calling the `config` method:

  <CodeGroup>
    ```ruby lines wrap theme={null}
    key = 'example-config-key'
    context = LaunchDarkly::LDContext.create({ key: 'example-user-key', kind: 'user', name: 'Sandy' })
    fallback_value = LaunchDarkly::Server::AI::AIConfig.new(enabled: false)
    variables = { 'example_custom_variable' => 'example_custom_value' }

    ai_config = ai_client.config(key, context, fallback_value, variables)

    if ai_config.enabled
      # Send a request to your AI provider using the customized config
    else
      # Application path to take when the config is disabled
    end
    ```

    After the function call, you can view the context that you provided to it on the **Contexts** list.

    To learn more, read [`config`](https://launchdarkly.github.io/ruby-server-sdk-ai/LaunchDarkly/Server/AI/Client.html#config-instance_method).
  </CodeGroup>
</Accordion>