> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://launchdarkly.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://launchdarkly.com/docs/_mcp/server.

# Ruby AI SDK reference

> This topic documents how to get started with the Ruby AI SDK, and links to reference information on all of the supported features.

This topic documents how to get started with the Ruby AI SDK, and links to reference information on all of the supported features.

The Ruby AI SDK is designed for use with AgentControl. It is in a pre-1.0 release and the API may change based on feedback. Active feature development is ongoing in the [Python](/sdk/ai/python) and [Node.js](/sdk/ai/node-js) AI SDKs, so this SDK receives new features at a slower pace. You can follow development or contribute on [GitHub](https://github.com/launchdarkly/ruby-server-sdk-ai).

#### SDK quick links

LaunchDarkly's SDKs are open source. In addition to this reference guide, we provide source, API reference documentation, and sample applications:

<table class="fern-table">
  <tr>
    <th>
      Resource
    </th>

    <th>
      Location
    </th>
  </tr>

  <tr>
    <td>
      SDK API documentation
    </td>

    <td>
      [SDK API docs](https://launchdarkly.github.io/ruby-server-sdk-ai/)
    </td>
  </tr>

  <tr>
    <td>
      GitHub repository
    </td>

    <td>
      [ruby-server-sdk-ai](https://github.com/launchdarkly/ruby-server-sdk-ai)
    </td>
  </tr>

  <tr>
    <td>
      Sample application
    </td>

    <td>
      [Using Bedrock](https://github.com/launchdarkly/ruby-server-sdk-ai/tree/main/examples/chatbot/aws-bedrock)

      , 

      [Using OpenAI](https://github.com/launchdarkly/ruby-server-sdk-ai/tree/main/examples/chatbot/openai)
    </td>
  </tr>

  <tr>
    <td>
      Published module
    </td>

    <td>
      [RubyGems](https://rubygems.org/gems/launchdarkly-server-sdk-ai)
    </td>
  </tr>
</table>

## Get started

LaunchDarkly AI SDKs interact with [AgentControl configs](/home/getting-started/vocabulary#agentcontrol-config). Configs are the LaunchDarkly resources that manage model configurations and messages for your generative AI applications.

#### Try the Quickstart

This reference guide describes working specifically with the Ruby AI SDK. For a complete introduction to LaunchDarkly AI SDKs and how they interact with configs, read [Quickstart for AgentControl](/home/agentcontrol/quickstart).

You can use the Ruby AI SDK to customize your config based on the [context](/home/getting-started/vocabulary#context) that you provide. This means both the messages and the model evaluation in your generative AI application are specific to each end user, at runtime. You can also use the AI SDKs to record metrics from your AI model generation, including duration and tokens.

Follow these instructions to start using the Ruby AI SDK in your application.

### Understand version compatibility

The LaunchDarkly Ruby AI SDK is compatible with Ruby 3.0 and higher.

### Install the SDK

First, install the AI SDK as a dependency in your application using your application's dependency manager. If you want to depend on a specific version, refer to the [SDK releases page](https://github.com/launchdarkly/ruby-server-sdk-ai/releases) to identify the latest version.

Here's how:

#### Shell

```bash
gem install launchdarkly-server-sdk
gem install launchdarkly-server-sdk-ai
```

Next, import the LaunchDarkly `LaunchDarkly::Server::AI::Client` into your application code:

#### Ruby

```ruby
require 'launchdarkly-server-sdk'
require 'launchdarkly-server-sdk-ai'
```

### Initialize the client

After you install and import the AI SDK, create a single, shared instance of `LaunchDarkly::Server::AI::Client`. Specify your SDK key here to authorize your application to connect to a particular environment within LaunchDarkly.

#### The Ruby AI SDK uses an SDK key

The Ruby AI SDK uses an SDK key. Keys are specific to each project and environment. They are available on the **SDK keys** page under **Settings**. To learn more about key types, read [Keys](/sdk/concepts/client-side-server-side#keys-and-credentials).

Here's how:

#### Ruby

```ruby
ld_client = LaunchDarkly::LDClient.new("YOUR_SDK_KEY")
ai_client = LaunchDarkly::AI::LDAIClient.new(ld_client)
```

### Configure the context

Next, configure the context that will use the config, that is, the context that will encounter generated AI content in your application. The context attributes determine which variation of the config LaunchDarkly serves to the end user, based on the targeting rules in your config. If you are using template variables in the messages in your config's variations, the context attributes also fill in values for the template variables.

Here's how:

#### Ruby AI SDK

```ruby
context = LaunchDarkly::LDContext.create({
    key: "example-user-key",
    kind: "user",
    firstName: "Sandy",
    lastName: "Smith",
    email: "sandy@example.com",
    groups: ["Acme", "Global Health Services"]
})
```

### Customize a config

Then, use `Config` to customize the config. Customization means that any variables you include in the messages when you define the config variation have their values set to the context attributes and variables you pass to `Config`. You need to call `Config` each time you generate content from your AI model.

The customization process within the AI SDK is similar to [evaluating flags](/sdk/features/) in one of LaunchDarkly's client-side, server-side, or edge SDKs, in that the SDK completes the customization without a separate network call. The `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. If it cannot perform the evaluation or LaunchDarkly is unreachable, it returns the fallback value. For example, you might use an empty, disabled `AIConfig` as a fallback value, or a fully configured default. Either way, you should make sure to check for this case and handle it appropriately in your application.

After you call `config`, you can pass the customized messages directly to your AI.

Here's how:

#### Ruby AI SDK

```ruby
fallback_value = LaunchDarkly::AI::AIConfig.new(enabled: false)

ai_config = ai_client.config('example-config-key', context, fallback_value, { 'example_custom_variable' => 'example_custom_value' })
```

To learn more, read [Customizing AgentControl configs](/sdk/features/agentcontrol-config#ruby-ai).

### Call provider, record metrics from AI model generation

Finally, use one of the `track_[model]_metrics` functions to make a request to your generative AI provider and record metrics from your AI model generation. The Ruby AI SDK provides specific `track_[model]_metrics` functions using completions from common AI model families. Make sure to check whether the returned `config` is enabled, and handle the disabled case appropriately in your application.

Here's how:

#### Using OpenAI model

```ruby
if ai_config.enabled
  # Pass in the result of the OpenAI operation.
  # When calling the OpenAI operation, use details from ai_config.
  # For instance, you can pass ai_config.model.name
  # and ai_config.messages to your specific OpenAI operation.
  #
  # CAUTION: If the call inside of track_openai_metrics throws an exception,
  # the SDK will re-throw that exception

  completion = ai_config.tracker.track_openai_metrics(
      openai_client.chat.completions.create(
          model: ai_config.model.name,
          messages: ai_config.messages.map(&:to_h)
      )
  )
else
  # Application path to take when the ai_config is disabled
end
```

#### Using Bedrock model

```ruby
if ai_config.enabled
  # Pass in the result of the Bedrock Converse command.
  # When calling the Bedrock Converse command, use details from ai_config.
  # For instance, you can pass ai_config.model.name
  # and ai_config.messages to your specific Bedrock Converse command.

  completion = ai_config.tracker.track_bedrock_converse_metrics(
      bedrock_client.converse(
          map_converse_arguments(
            ai_config.model.name,
            ai_config.messages
          )
      )
  )
else
  # Application path to take when the ai_config is disabled
end
```

#### Bedrock helper function

```ruby maxLines=0
# The map_converse_arguments helper function transforms the messages
# to fit the Bedrock SDK

  def map_converse_arguments(model_id, messages)
    args = {
      model_id: model_id,
    }

    mapped_messages = []
    user_messages = messages.select { |msg| msg.role == 'user' }
    mapped_messages << { role: 'user', content: user_messages.map { |msg| { text: msg.content } } } unless user_messages.empty?

    assistant_messages = messages.select { |msg| msg.role == 'assistant' }
    mapped_messages << { role: 'assistant', content: assistant_messages.map { |msg| { text: msg.content } } } unless assistant_messages.empty?
    args[:messages] = mapped_messages unless mapped_messages.empty?

    system_messages = messages.select { |msg| msg.role == 'system' }
    args[:system] = system_messages.map { |msg| { text: msg.content } } unless system_messages.empty?

    args
  end
```

Alternatively, you can use the SDK's other `track*` functions to record these metrics manually. You may need to do this if you are using a model for which the SDK does not provide a convenience `track_[model]_metrics` function. The `track_[model]_metrics` functions are expecting a response, so you may also need to do this if your application requires streaming.

Make sure to call `config` each time you generate content from your AI model:

#### Using OpenAI model, next request to provider

```ruby
ai_config = ai_client.config('example-config-key', context, fallback_value, { 'example_custom_variable' => 'example_custom_value' })

completion = ai_config.tracker.track_openai_metrics(...)
```

#### Using Bedrock model, next request to provider

```ruby
ai_config = ai_client.config('example-config-key', context, fallback_value, { 'example_custom_variable' => 'example_custom_value' })

completion = ai_config.tracker.track_bedrock_converse_metrics(...)
```

To learn more, read [Tracking AI metrics](/sdk/features/ai-metrics#python-ai).

## Supported features

This SDK supports the following features:

* [Anonymous contexts](/sdk/features/anonymous#ruby-ai)
* [Context configuration](/sdk/features/context-config#ruby-ai)
* [Customizing AgentControl configs](/sdk/features/agentcontrol-config#ruby-ai)
* [Private attributes](/sdk/features/private-attributes#ruby-ai)
* [Tracking AI metrics](/sdk/features/ai-metrics#ruby-ai)