SDK quick linksThe SDKs are open source. In addition to this reference guide, we provide source, API reference documentation, and sample applications.
| Resource | Location |
|---|---|
| SDK API documentation | SDK API docs |
| GitHub repository | go-ai-sdk |
| Published module | pkg.go.dev |
| Sample applications | examples |
Get started
LaunchDarkly AI SDKs interact with AgentControl configs. Configs are the LaunchDarkly resources that manage model configurations and messages for your generative AI applications.Try the QuickstartThis reference guide describes working specifically with the Go AI SDK. For a complete introduction to LaunchDarkly AI SDKs and how they interact with configs, read Quickstart for AgentControl.
Prerequisites
To use the Go AI SDK, you need:- Go 1.26 or later.
- A LaunchDarkly account where you have completed the Quickstart for AgentControl.
- An existing AgentControl config.
Install the SDK
First, install the AI SDK as a dependency in your application. The SDK requires Go 1.26 or later. How you install it depends on what dependency management system you are using.- If you are using the standard Go modules system, import the SDK packages in your code and
go buildautomatically downloads them. - Otherwise, use the
go getcommand and specify the SDK version, such asgo get github.com/launchdarkly/go-ai-sdk/aiserver@v1.0.0.
aiserver package is the core client. Add one handler package for each model provider you use. Installing aiserver also installs the LaunchDarkly Go SDK and the OpenTelemetry modules that it depends on.
Here is how:
Shell
Go AI SDK
Choose a provider handler
A handler calls a model provider on behalf of the SDK. The provider name and mode on the config variation decide which handler runs. A config in completion mode uses a messages handler, and a config in agent mode uses an agent handler.| Package | Provider | Mode | Description |
|---|---|---|---|
claudemessages | Anthropic | messages | Anthropic Messages API. Runs function tools in a local tool loop. |
claudeagents | Anthropic | agent | In-process agent loop on the Anthropic Messages API, with the Claude Code built-in tools. |
openaimessages | OpenAI | messages | OpenAI Responses API. |
openaiagents | OpenAI | agent | In-process agent loop on the OpenAI Responses API, with handoffs. |
bedrockmessages | Amazon Bedrock | messages | Amazon Bedrock Converse API. |
bedrockagents | Amazon Bedrock | agent | Amazon Bedrock agent handler. |
langchainmessages | Any provider (*) | messages | LangChain-style handler. The fallback when no other handler names the provider. |
langchainagents | Any provider (*) | agent | LangChain-style agent handler. The fallback when no other handler names the provider. |
| Package | Description |
|---|---|
aiserver | The core client. Includes Config, Graph, ResolveGraph, InspectConfig, the registry, lifecycle functions, judges, and telemetry. |
skills | Agent skills. Reads skills that configs reference, verifies them, and writes them to disk. |
evaluations | Evaluations from code. Runs a dataset through a handler, scores each output, and reports the verdict. |
llms | The chat-model interface, plus built-in OpenAI, Anthropic, and Bedrock models for the LangChain handlers. |
ANTHROPIC_API_KEY, OPENAI_API_KEY, or the AWS credential chain and AWS_BEARER_TOKEN_BEDROCK. You can also inject your own provider client through the handler options.
The agent handlers run their own agent loopGo has no official OpenAI Agents SDK or Claude Agent SDK.
openaiagents and claudeagents run their own agent loop on the official provider SDKs. LangChain publishes no official Go SDK. langchainmessages and langchainagents use the llms package and state-graph runner that ship with this SDK.Initialize the client
After you install and import the SDK, initialize the AI client. The AI client is how you interact with configs. Specify the SDK key to authorize your application to connect to a particular environment within LaunchDarkly.The Go AI SDK uses an SDK keyThe Go 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.
Go AI SDK
- Lazy initialization. The first call to
Config,Graph,ResolveGraph, orInspectConfigcallsInitClientwith empty options, which means every setting comes from environment variables. - Explicit initialization. Call
InitClient(ctx, opts)to pass options or to fail fast at startup. - Bring your own client. Call
InitWithClient(ctx, ldClient, opts)with any value that satisfiesaiserver.LDClient. Any*ld.LDClientsatisfies the requirement. To build one, importgithub.com/launchdarkly/go-server-sdk/v7asldand callld.MakeClient.
InitClient and InitWithClient return the installed client. Call Shutdown first to switch clients. Shutdown exports pending spans, flushes events, and closes the LaunchDarkly client, including a client you passed to InitWithClient. InitOptions.WaitFor sets the initialization timeout. A zero or negative value means the 10 second default.
A failed initialization is not cached. The next call tries again. If you rely on lazy initialization while LaunchDarkly is unreachable, each call can wait up to the timeout before it fails. To keep an outage from adding that wait to every request, call InitClient at startup and handle its error there.
Initializing the client also sets up OpenTelemetry tracing
InitClient and InitWithClient register a global OpenTelemetry tracer provider. To learn what the SDK exports, read Record metrics and traces.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 is how:Go AI SDK
ldcontext and ldvalue packages from github.com/launchdarkly/go-sdk-common/v3.
Protect private attributes
Anonymous contexts and private attributes work the same way as in the Go server SDK. The AI SDK sends its events through the Go server SDK, which applies its usual handling of anonymous contexts and private attributes. Spans carry only context kinds and keys, never attribute values. The SDK records them asfeature_flag.context.id, feature_flag.contextKeys, and context.contextKeys.<kind>.
Prompt templates are the exception. The full context, including private attributes, is available to templates as ldContext.
Customize a config and call your model
Then, useConfig to customize a config and call your model. 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 in. You set the mode for a config when you create it in the LaunchDarkly UI.
The customization process within the AI SDK is similar to evaluating flags in one of the LaunchDarkly client-side, server-side, or edge SDKs, in that the SDK completes the customization without a separate network call. After it customizes the config, the SDK routes the call to the handler that matches the variation’s provider and mode, and returns the response.
Config takes a config key and the handlers that can serve it. Invoke takes the input, the context, and optional call options. Use WithVariables to fill template variables in the config’s messages, and WithHistory to pass earlier messages in the conversation.
Here is how:
Go AI SDK
resp.Text() returns the response as text, whether the model returned a string or structured output.
Use a convenience function
If you use one provider in one mode, a convenience function builds the handler and makes the call in one step. Each handler package has one, such asopenaimessages.OpenAIMessages, claudemessages.ClaudeMessages, and openaiagents.OpenAIAgents. Pass the config key, the user input, the context, and optional InvokeOptions. The options hold Variables for template variables, ToolHandlers, Registry, SkipJudges, and Handler, which sets the handler options.
Here is how:
Go AI SDK
Config and Invoke with several handlers instead.
Handle a disabled or unavailable config
A call can fail before it reaches a model. The SDK has no fallback value. Instead,Invoke and Stream return an error that you match with errors.Is, and your application decides what to do next.
ErrConfigDisabledmeans the config variation is turned off.ErrConfigNotFoundmeans the flag returned no config. The flag is missing, has the wrong type, or could not be evaluated, for example because the client is not ready. The error wraps the reason from the LaunchDarkly Go SDK, soerrors.Iscan match that cause too.
Stream a response
UseStream to receive the response as the model generates it. Stream returns an iterator. Each event has a type, and chunk events carry text.
Here is how:
Go AI SDK
launchdarkly.stream.abandoned and tracks neither a success nor an error. If a handler panics, the SDK tracks a generation error and then the panic continues to your code. A panic in your own loop body counts as abandonment.
Use structured output
A config can return structured output that conforms to a JSON schema, rather than plain text. Use structured output when another system, database, or function consumes the model’s response, or when you need to extract specific information, such as a severity or category. Set the output format on the config variation in the LaunchDarkly UI. The variation’sOutputFormat holds the schema. When a variation has an output format, resp.Text() returns the structured output as a JSON string, which you can unmarshal into your own type.
Here is how:
Go AI SDK
Use more than one provider
Pass several handlers to serve variations that use different providers. The variation’s provider name and mode pick the handler. A handler with the provider*, such as the LangChain handlers, is the fallback when no other handler names the provider.
Here is how:
Go AI SDK
ErrNoHandler.
Write a custom handler
If you use a provider that has no handler package, or you want to call an internal endpoint, useaiserver.CreateHandler to build your own handler. A custom handler works with Config routing and registries in the same way as the built-in handlers.
CreateHandler takes four arguments:
- A
ProvidesForvalue, which holds the provider name and mode that the handler serves. - An invoke function, which receives a
HandlerRequestand returns aHandlerResult. - An optional stream function. If you pass nil,
Streamfalls back to the invoke function. - A
ContentCapturesetting for the handler’s spans.
HandlerRequest holds the customized config, the user input, the tool handlers, the variables, and the conversation history. Return the model’s answer in the result’s Output, and its token counts in Usage, with keys such as input_tokens and output_tokens.
Here is how:
Go AI SDK
* serves any provider that no other handler names, which makes it a fallback.
Share handlers and tools with a registry
If your application calls several configs, build the handlers and tools once, then share them with a registry. Tool keys must match the keys in the variation’s tools map exactly. The SDK never offers a tool with no registered function to the model. Here is how:Go AI SDK
*Registry and pass it explicitly. If you want one registry for the whole process, keep it in a variable in your own package.
Use built-in provider tools
Some handlers include built-in tools that run natively, rather than a function you write. Built-in tools are*aiserver.NativeTool values. To use one, assign it as the implementation for a LaunchDarkly tool key in place of a function. The SDK tracks a built-in tool call like any other tool call.
The claudeagents package exports these built-in tools:
ClaudeWebSearchandClaudeWebFetch, which map to Anthropic server tools. Anthropic runs them.ClaudeBash,ClaudeRead,ClaudeEdit,ClaudeWrite,ClaudeGlob,ClaudeGrep,ClaudeTodoWrite, andClaudeNotebookEdit, which run on your host. To learn about the risks, read Choose a provider handler.
Go AI SDK
Read a config without calling a model
UseInspectConfig to read the variation that a context receives, without calling a model. This is useful if you want to call your provider yourself.
InspectConfig returns an InspectResult and an error. A turned-off variation returns Enabled as false and a nil error. Initialization, evaluation, and parse failures return an error and a zero result.
The InspectResult has the following fields:
Enabled: Whether the variation is turned on.Config: The config variation, as an*AiConfig. This is nil when the variation is turned off.Meta: Metadata about the variation, as a*VariationMeta. It hasVariationKey,Version,Mode,ModelKey, andModelVersion.
Config holds everything you need to call a provider yourself. It has Instructions, Messages, Model, Provider, Tools, JudgeConfiguration, EvaluationMetricKey, and OutputFormat. Each message has a Role and Text. The model has a Name, Parameters, and Custom values, and the provider has a Name.
Consider the following before you call a provider directly:
- The SDK returns messages as templates, without filling in their variables. Use
aiserver.ParseTemplateto fill them. - LaunchDarkly records no metrics for a provider call that you make yourself.
Go AI SDK
Run agent graphs
An agent graph links multiple agent configs together into nodes and edges. UseGraph to run a graph. The SDK routes each node to the handler that matches the node’s provider and mode. Pass agent handlers.
Here is how:
Go AI SDK
Invoke and Stream on a graph take optional CallOption values. Use WithVariables to pass template variables.
If the graph, or a node that it references, is turned off, the call returns ErrGraphDisabled. Other failures, such as an initialization or evaluation error, return a different error.
Stream on a graph yields node start, chunk, node done, handoff, and done events. A node’s own judge scores are on its node done event, and the done event holds only the graph-level judge scores. To collect every score, read each node done event.
Here is how:
Go AI SDK
openaiagents.OpenAIGraph, claudeagents.ClaudeGraph, bedrockagents.BedrockGraph, and langchainagents.LangChainGraph.
Here is how:
Go AI SDK
ResolveGraph to read the topology and node configs. If the graph is turned off, ResolveGraph returns a disabled definition and a nil error. Check def.Enabled before you run it. The agent handler packages include adapters that take the result, such as ToClaudeAgents, ToOpenAIAgents, and ToLangGraph. This example reuses the tools map from the previous example.
Here is how:
Go AI SDK
Evaluate output with judges
Judges are AgentControl configs that score the output of another config. You attach judges to a variation in the LaunchDarkly UI, and each attachment has a sampling percentage. To learn more, read Judges. The SDK runs the attached judges after the call returns, and includes the results in the response. In an agent graph, each node can have its own judges, and a graph-level judge scores the final answer. A judge needs a handler for its own provider. If no handler covers the judge’s provider, the SDK skips that judge. If the judge’s own config is missing or turned off, the SDK skips that judge and logs the skip. If a judge’s provider call fails,Invoke returns both the response and the error. The answer is still usable. Check the response before you treat the error as fatal.
Run judges later
By default,Invoke returns the judge results with the response. To keep response time low, set SkipJudges on ConfigArgs, or on the InvokeOptions of a convenience function. The response then carries JudgeTasks instead of results. Each task is JSON-serializable, which means you can queue it. Pass each task and your handlers to RunJudge when you are ready to run it, for example on your own goroutine.
RunJudge returns a *JudgeRunResult and an error. The result has Score, Response, Usage, and TrackData. RunJudge returns an error only when the judge’s provider call fails. It returns a nil result and a nil error when no handler serves the judge’s provider, or when the judge returns no numeric score.
RunJudge does not send the evaluation metric. To record the score, call aiserver.Track with the task’s evaluation metric key, the task’s context, the result’s TrackData, and the score.
Here is how:
Go AI SDK
go runJudgeWorker(ctx, task, handlers). Pass handlers that cover each judge’s provider. If you use a registry, pass registry.Handlers().
Record metrics and traces
The SDK records metrics around each call without extra code. It sends LaunchDarkly$ld:ai:* events for token usage, latency, and errors, and it creates OpenTelemetry spans for handler calls, tool calls, and judge evaluations.
Version 1.0 of the Go AI SDK does not record user feedback, such as a thumbs up or down on a response. It has no feedback event and no resumption tokens.
Configure tracing
InitClient registers a global OpenTelemetry tracer provider. It exports spans over OpenTelemetry Protocol (OTLP)/HTTP with gzip compression. The SDK uses the endpoint from InitOptions.OTLPEndpoint, then OTEL_EXPORTER_OTLP_ENDPOINT, then the default endpoint.
The tracer provider sets these resource attributes.
| Attribute | Value |
|---|---|
launchdarkly.project_id | Set from the SDK key, from InitOptions.SDKKey or LD_SDK_KEY. |
service.name | LD_SERVICE_NAME, or go-sdk if unset. |
deployment.environment | LD_ENVIRONMENT, when set. |
gen_ai.conversation.id to every span that starts under that context.
Here is how:
Go AI SDK
Control what the SDK records on spans
By default, spans include content. Handler spans carry the prompt and completion text, tool spans carry the tool arguments and results, and judge spans carry the judge’s explanation. The SDK always records the model, provider, token usage, status, and tool names. You can turn content capture off for one handler, or for the whole process. A handler setting takes precedence over the process setting, and the process setting takes precedence over the default, which is on. Here is how:Go AI SDK
Configure accepts only options that have the same effect, and otherwise returns ErrConfigureLocked. Shutdown resets this setting.
Use Agent skills
Agent skills are skill files that AgentControl configs reference. Theskills package reads those skills, verifies their content, and writes them to disk as <root>/<key>/SKILL.md. Your agent can then load them. Writing skills to disk works on POSIX systems only.
Install the package with go get github.com/launchdarkly/go-ai-sdk/skills.
The following example keeps a directory in sync with LaunchDarkly. When you revoke a skill, the SDK’s watcher removes it from disk within 500 milliseconds. Add .launchdarkly-skills.json to your .gitignore file, because the SDK writes a manifest with that name.
Here is how:
Go AI SDK
Run evaluations from code
Theevaluations package runs a dataset through your own handler, scores each output with AgentControl judges or local scorers, and reports the results to LaunchDarkly. Use it as a gate in continuous integration.
Install the package with go get github.com/launchdarkly/go-ai-sdk/evaluations, plus the handler package that runs your generation step.
Running evaluations from code needs more credentials than the other features. In LaunchDarkly, the API access token is called the Eval API key. To generate your credentials, click Evaluations in the side navigation, click Run evaluations, then choose From code. If you create the token yourself, assign a role that allows reading datasets and tools, and creating evaluations and evaluation runs, in the target project. The Writer role works.
| Variable | Required | Description |
|---|---|---|
LD_PROJECT_KEY | Yes, unless you set InitEvaluationsOptions.ProjectKey | The project that holds the evaluations, runs, tools, datasets, and judges. |
LD_API_TOKEN | Yes, unless you set InitEvaluationsOptions.APIToken | A LaunchDarkly API access token. It authorizes every management API request. |
LD_SDK_KEY | Yes, unless you set InitEvaluationsOptions.SDKKey or already initialized a client | The server-side SDK key for the client that sends result events. |
LD_API_BASE_URI | No | The management API host. The default is https://app.launchdarkly.com. The SDK never uses LD_BASE_URI for this. |
LD_UI_BASE_URI | No | The host of the run link in the result. The default is https://app.launchdarkly.com. |
Go AI SDK
res.Verdict as EvalVerdictPass or EvalVerdictFail. When LaunchDarkly returns a verdict, Passed follows it. Otherwise, Passed is true only if no row errored or failed.
To learn more, read Evaluations from code.
Reference
This section lists the environment variables that configure the SDK, the errors that it returns, and its main functions.Configuration
Each environment variable fills the matchingInitOptions field only if that field is empty. A field that you set wins over its variable, and a blank value counts as unset.
| Variable | InitOptions field | Required | Description |
|---|---|---|---|
LD_SDK_KEY | SDKKey | Yes, unless you set the field or use InitWithClient | The server-side SDK key. |
LD_BASE_URI | BaseURI | No | The polling base URI, for non-production environments. |
LD_STREAM_URI | StreamURI | No | The streaming URI. |
LD_EVENTS_URI | EventsURI | No | The events URI. |
OTEL_EXPORTER_OTLP_ENDPOINT | OTLPEndpoint | No | The OTLP/HTTP trace endpoint. The SDK appends /v1/traces. The default is https://otel.observability.app.launchdarkly.com. |
LD_SERVICE_NAME | ServiceName | No | The service.name resource attribute. The default is go-sdk. |
LD_ENVIRONMENT | Environment | No | The deployment.environment resource attribute. Omitted if unset. |
LD_ENVIRONMENT_ID | None | No | The LaunchDarkly environment ID. The SDK sends it as environmentId on every $ld:ai:* event and as feature_flag.set.id on handler spans, so that AgentControl monitoring can correlate traces. Omitted if unset. |
Errors
Match errors witherrors.Is. Each error is wrapped with the key or provider that it concerns, and keeps the LaunchDarkly SDK’s own reason if there is one.
| Error | Meaning |
|---|---|
ErrNotInitialized | You called GetClient before InitClient or InitWithClient. |
ErrConfigNotFound | The flag returned no config. It is missing, the wrong type, or could not be evaluated, for example because the client is not ready. |
ErrConfigDisabled | The config variation is turned off. |
ErrNoHandler | No handler serves the variation’s provider and mode. |
ErrGraphDisabled | The graph, or a node that it references, is turned off. |
ErrConfigureLocked | You called Configure with a different effect after the first handler call. |
API reference
For the full API, read the SDK API docs. The following table lists the main functions in theaiserver package, and the convenience functions in the handler packages.
| Function | Purpose |
|---|---|
Config(ConfigArgs) | Binds a config key. Use Invoke and Stream on the result. |
Graph(key, GraphOptions) | Binds an agent graph. Use Invoke and Stream on the result. |
ResolveGraph(ctx, key, ldctx, GraphOptions) | Returns the topology and node configs for framework-native runners, and an error for resolution failures. |
InspectConfig(ctx, key, ldctx) | Reads a variation without calling a model. Returns an error for initialization, evaluation, and parse failures. |
Configure(SDKOptions) | Sets the process-wide content capture default. |
RunJudge | Runs a judge task from a call with SkipJudges set, for example on your own goroutine. |
InitClient, InitWithClient, GetClient, Shutdown | Manage the client lifecycle. |
SetLogger | Sets the SDK logger. The default is slog.Default(). |
OpenAIMessages, ClaudeMessages, OpenAIAgents, and others | Convenience functions in the handler packages. Build the handler and call Config().Invoke in one step. |
OpenAIGraph, ClaudeGraph, BedrockGraph, LangChainGraph | Graph wrappers in the agent handler packages. Bind a handler to Graph. |
Supported features
This SDK supports the following features:- Agent skills
- Anonymous contexts
- Context configuration
- Customizing AgentControl configs
- Evaluations from code
- Private attributes
- Tracking AI metrics
What’s next
Now that you can call models with the Go AI SDK, explore these next steps:- Create configs to set up your own AgentControl configs in the LaunchDarkly UI.
- Agent graphs to build multi-agent workflows.