> ## 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.

# When to use Agent vs Completion mode for an AgentControl configuration

> Understand the difference between Agent and Completion mode in AgentControl configurations, and when to choose each with the LaunchDarkly AI SDK.

**Developer**

**Federal docs**

**EU docs**

*Published November 16, 2026*

Portrait of Eric Pietrowicz.

by Eric Pietrowicz

With the release of the new [LaunchDarkly AI SDK](https://github.com/launchdarkly/js-ai-sdk), choosing between Agent mode and Completion mode for an AgentControl configuration now decides which provider SDK runs your request.

You pick the mode when you create the configuration:

![The 'Create config' dialog in LaunchDarkly, with Completion mode selected and Agent and Judge mode as the other options.](https://mintcdn.com/launchdarkly/Sg_Gc9y0j1A3k1Il/images/tutorials/when-to-use-agent-vs-completion/ai-config.png?fit=max\&auto=format\&n=Sg_Gc9y0j1A3k1Il\&q=85\&s=4e0c6af4b56f32b39f4a01dbe00b1fde)

The 'Create config' dialog with the Completion, Agent, and Judge mode options.

With the new managed path, the mode you choose determines which large language model (LLM) provider SDK the LaunchDarkly AI SDK invokes under the hood. Here is how a request flows through the SDK:

![Diagram of the LaunchDarkly AI SDK routing a request through an Anthropic, OpenAI, or LangChain handler to the provider API, with metrics reported back to LaunchDarkly.](https://mintcdn.com/launchdarkly/Sg_Gc9y0j1A3k1Il/images/tutorials/when-to-use-agent-vs-completion/ac-call-stack.png?fit=max\&auto=format\&n=Sg_Gc9y0j1A3k1Il\&q=85\&s=6757964fc41cd7f2f315a74b16faaeb7)

A request flowing through the LaunchDarkly AI SDK to a foundation model provider.

The request flows as follows:

1. Your runtime receives a user request.
2. Use the LaunchDarkly AI SDK to retrieve the AgentControl configuration, including the system prompt, foundation model, tools, skills, and judges.
3. Call the provider's API using a provider handler, such as the Anthropic, OpenAI, or LangChain handler.
4. Review the metrics and observability data, such as latency, token count, tool use, and judge scores, that the SDK reports back to LaunchDarkly.
5. Return the response to the user from your runtime.

Here is an example that registers both Claude handlers (one for Agent mode and one for Completion mode):

```js theme={null}
globalRegistry.register({
  handlers: [
    createClaudeAgentsHandler(), // Invoked with an Agent mode configuration
    createClaudeMessagesHandler(), // Invoked with a Completion mode configuration
  ]
});

const instance = config({
  registry: globalRegistry, // Optional: lift handlers up into a global registry
  key: "my-config-key",
  toolHandlers: {
    "my-tool": myToolHandler
  }
});

const message = "hello world";
const response = await instance.invoke(message, getDefaultContext());
```

You do not handle the difference between Agent mode and Completion mode in your runtime code.

This just moves the question: what is the difference between `createClaudeAgentsHandler` and `createClaudeMessagesHandler`?

If we drill down into the library, we can see that `createClaudeAgentsHandler` wraps `@anthropic-ai/claude-agent-sdk`, and `createClaudeMessagesHandler` wraps `@anthropic-ai/sdk`.

Next question: what's the difference between `@anthropic-ai/claude-agent-sdk` and `@anthropic-ai/sdk`?

Looking at the npm pages for [`@anthropic-ai/sdk`](https://www.npmjs.com/package/@anthropic-ai/sdk) and [`@anthropic-ai/claude-agent-sdk`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk), we can see that `@anthropic-ai/claude-agent-sdk` ships all of Claude Code, Anthropic's agentic coding tool, as a library. By contrast, `@anthropic-ai/sdk` only calls the Claude API.

The OpenAI handlers follow the same split. `createOpenAIAgentHandler` wraps the OpenAI Agents SDK (`@openai/agents`), and `createOpenAIMessagesHandler` wraps the standard OpenAI client (`openai`). I encourage you to drill down into the other providers in the same way to map the differences.

Now we can start to build use cases for the two. For my money, I'm leaning on Completion mode most of the time, for API endpoints, lightweight batch jobs, and similar work, rather than spinning up all of Claude Code with `@anthropic-ai/claude-agent-sdk`.

## Tool loops and when an API request becomes agentic

Traditionally, when you call the Claude API (`@anthropic-ai/sdk`) directly, you have to manage tool loops yourself.

For example, your user asks, "How do I use the GitHub CLI?" You pass that along to the API, and it might respond with a `tool_use` block that attempts to call the `bash` tool, if you provided that tool as an option in the original request.

In that case, it's up to your runtime logic to go off and execute the `bash` tool, append the result to the message history, and call the API again with the additional context from the tool. This is the foundation of the ["agent loop"](https://code.claude.com/docs/en/agent-sdk/agent-loop).

But when you use the LaunchDarkly AI SDK, [all of that happens for you](https://github.com/launchdarkly/js-ai-sdk/blob/71e294a195659e6185e6aacfd386d76edcc09d4b/packages/claude-messages/src/handler.ts#L422). The SDK runs the tool loop with the functions you pass in `toolHandlers`.

## Compare Agent mode and Completion mode

Here is how the two modes compare for Claude:

| | Agent mode | Completion mode |
| - | - | - |
| Handler | `createClaudeAgentsHandler` | `createClaudeMessagesHandler` |
| Wraps | `@anthropic-ai/claude-agent-sdk` | `@anthropic-ai/sdk` |
| Good fit for | Agents that need Claude Code's harness | API endpoints, lightweight batch jobs, and most server-side request handling |

## Conclusion

Completion mode looks much more agentic with the SDK-managed tool loop. For most server-side applications, the whole Claude Agent SDK that you get with `createClaudeAgentsHandler()` is probably overkill. I know I'll be reaching for Completion mode a whole lot more with this in mind.
