Helpers
Give the model tools that OpenDunes runs for it: web search, page read, a sandbox.
1. Name the helper in tools
A helper is a tool the model reaches for in the middle of its answer. Your own functions run in your code, as Tools and function calling shows. OpenDunes runs a helper, and the model reads its result before it goes on writing. You write no code for it.
Put the helper in tools by its type, opendunes:<name>. Souk Bot lets the model search the web before it quotes a price.
import json
import os
import urllib.request
API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/chat/completions"
MODEL = "anthropic/claude-sonnet-4.5"
PROMPT = "What does an iPhone 16 cost in Algiers today? Cite sources."
body = {
"model": MODEL,
"messages": [{"role": "user", "content": PROMPT}],
"tools": [{"type": "opendunes:web_search"}],
}
request = urllib.request.Request(
ADDRESS,
data=json.dumps(body).encode(),
headers={
"Authorization": "Bearer " + API_KEY,
"Content-Type": "application/json",
},
)
with urllib.request.urlopen(request) as response:
answer = json.load(response)
print(answer["choices"][0]["message"]["content"])
print(answer["usage"]["cost"])Helpers and your own functions share tools. The model calls the helpers on its own; a call to one of your functions comes back to your code, as usual.
{
"tools": [
{
"type": "opendunes:web_search"
},
{
"type": "opendunes:datetime"
},
{
"type": "function",
"function": {
"name": "stock_level",
"description": "How many units of a product the shop holds.",
"parameters": {
"type": "object",
"properties": {
"sku": {
"type": "string"
}
},
"required": ["sku"]
}
}
}
]
}Some helpers work on some routes only. Shell, tool search and bash: /v1/messages.
Shell and tool search also work on /v1/responses, and apply patch on /v1/responses alone.
How far the model goes
The model decides whether to call a helper, and how often. A request runs at most 30 helper steps; each call is one step. When the steps run out, the model answers with what it has gathered.
| You send | Holds |
|---|---|
max_tool_calls | fewer steps than 30, for the whole request |
stop_server_tools_when | conditions that end the steps early; when sent, it replaces max_tool_calls |
2. Read the answer
200, with the model's answer in choices[0].message.content, written after it read what the helpers returned. OpenDunes ran the helper calls: you send none of their results back.
| Field | Holds |
|---|---|
choices[0].message.content | the answer |
usage.server_tool_use | how many times each helper ran, such as web_search_requests |
usage.cost | the charge, in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges →: the model's tokens and every helper call |
The shell and bash helpers work in a sandbox. The files a command leaves there are listed at GET /v1/containers/{id}/files, with the sandbox's id from the helper's result; GET /v1/containers/{id}/files/{file}/content returns one file's bytes. Both are free.
3. Read what it cost
One charge, in DA, from your balanceBalanceWhat you can spend, in DA.More on Balance and charges →, the moment the answer ends. It carries the model's tokens and every helper call, each on its own meter.
Helpers with a meter of their own
| Helper | Type | Does | Bills on |
|---|---|---|---|
| web search | opendunes:web_search | searches the web | each search |
| web fetch | opendunes:web_fetch | reads one page | each page read |
| shell | opendunes:shell | runs commands in a sandbox | each second of sandbox |
| bash | opendunes:bash | runs commands in a sandbox, the Anthropic way | each second of sandbox |
Helpers on another model's meter
| Helper | Type | Does | Bills on |
|---|---|---|---|
| image generation | opendunes:image_generation | draws a picture | the picture model's meter |
| advisor | opendunes:advisor | consults a stronger model | that model's tokens |
| subagent | opendunes:subagent | hands a task to a smaller model | that model's tokens |
Helpers that cost tokens only
| Helper | Type | Does |
|---|---|---|
| date and time | opendunes:datetime | gives the current date and time |
| apply patch | opendunes:apply_patch | proposes edits to a file |
| tool search | opendunes:tool_search | loads your own tools when the model needs them |
| model search | opendunes:experimental__search_models | searches the catalogue |
The model's page in Models gives its token rates.
Don't give a model a search helper it has no use for. It decides how often to search, and every search is charged.
Name only the helpers the task needs, and lower the steps with max_tool_calls.
Plugins
A plugin is not a tool the model chooses: it runs once, on every request that names it in plugins.
{
"plugins": [
{
"id": "response-healing"
}
]
}| Plugin | id | Does |
|---|---|---|
| PDF inputs | file-parser | reads a PDF sent with the request |
| response healing | response-healing | repairs broken JSON in the answer |
| context compression | context-compression | cuts the middle of a prompt too long for the model |
Search the web with the opendunes:web_search helper. It replaces the web plugin and the :online suffix.
Errors
The body says why.
| Status | When |
|---|---|
| 400 | the request is malformed, or longer than the model takes |
| 401 | the key is missing, wrong, disabled or expired |
| 402 | your balance is at zero or below, cannot pay the request's hold, or the key's cap is spent; error.metadata.limit_source names which, and deposit_url or key_url says where to lift it. After up to 60 seconds of waiting for money your running requests hold, the 402 carries Retry-After: 60 |
| 404 | model is not on sale |
| 429 | the provider is limiting its rate; Retry-After says how many seconds to wait |
What to do on each: Errors and retries.
Last modified on