Migrating to the Agent SDK

Not yet available. The OpenDunes Agent SDK is on the roadmap. This page describes the intended migration path so you can build toward it now.

The OpenAI-compatible SDK is the right starting point for most projects. As your agent grows — multiple tools, multi-turn state, retry budgets, approval gates — the Agent SDK adds primitives designed for those patterns so you don't have to build them yourself.

When to migrate#

Stay on the OpenAI-compatible SDK if:

You're running simple single-turn or short multi-turn conversations.
You're integrating OpenDunes into an existing framework (LangChain, Vercel AI SDK, etc.) that manages the loop for you.
You want maximum portability to other OpenAI-compatible providers.

Consider the Agent SDK when:

Your loop logic is growing: you're accumulating tool calls, retry counters, and state management in application code.
You need per-step stop conditions, approval callbacks, or budgets tied to OpenDunes balance.
You want the call-model primitive to handle streaming, tool dispatch, and next-turn parameters as one unit rather than orchestrating them manually.

What changes#

The Agent SDK wraps POST /v1/chat/completions — it still calls the same endpoint. The difference is in what you manage yourself vs. what the SDK handles:

Concern	OpenAI-compatible SDK	Agent SDK
Message history accumulation	You	SDK
Tool dispatch and result injection	You	SDK
Streaming reassembly	You	SDK
Stop conditions	You	Built-in
Next-turn parameter updates	You	Built-in
Balance-aware halting	You	Built-in

Migration steps (intended)#

Keep your model slugs and messages. The slug format (provider/model) and message shape are identical.
Replace the loop scaffold with callModel() — it handles turns, tool calls, and streaming internally.
Lift your tools into the Agent SDK tool registry. Tool schemas stay the same; you register them once rather than passing them per-call.
Add stop conditions declaratively instead of checking return values in your loop body.
Remove manual retry logic — the SDK handles 429 and 503 retries with the same backoff rules.

Also see#

Agent SDK overview — the full planned API.
Call Model — the core primitive.
Usage for Agents (SDKs) — best practices while you're still on the OpenAI-compatible SDK.

When to migrate#

Stay on the OpenAI-compatible SDK if:

You're running simple single-turn or short multi-turn conversations.

You're integrating OpenDunes into an existing framework (LangChain, Vercel AI SDK, etc.) that manages the loop for you.

You want maximum portability to other OpenAI-compatible providers.

Consider the Agent SDK when:

Your loop logic is growing: you're accumulating tool calls, retry counters, and state management in application code.

You need per-step stop conditions, approval callbacks, or budgets tied to OpenDunes balance.

You want the call-model primitive to handle streaming, tool dispatch, and next-turn parameters as one unit rather than orchestrating them manually.

What changes#

The Agent SDK wraps POST /v1/chat/completions — it still calls the same endpoint. The difference is in what you manage yourself vs. what the SDK handles:

Concern	OpenAI-compatible SDK	Agent SDK
Message history accumulation	You	SDK
Tool dispatch and result injection	You	SDK
Streaming reassembly	You	SDK
Stop conditions	You	Built-in
Next-turn parameter updates	You	Built-in
Balance-aware halting	You	Built-in

Migration steps (intended)#

Keep your model slugs and messages. The slug format (provider/model) and message shape are identical.

Replace the loop scaffold with callModel() — it handles turns, tool calls, and streaming internally.

Lift your tools into the Agent SDK tool registry. Tool schemas stay the same; you register them once rather than passing them per-call.

Add stop conditions declaratively instead of checking return values in your loop body.

Remove manual retry logic — the SDK handles 429 and 503 retries with the same backoff rules.