opendunes
Requests · 4 min
Copy page ▾

Helpers

Give the model tools that OpenDunes runs for it: web search, page read, a sandbox.

  1. Name the helper in tools.
  2. Read the answer.
  3. Read what it cost.

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.

JSON
{
  "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"]
        }
      }
    }
  ]
}
Watch out

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 sendHolds
max_tool_callsfewer steps than 30, for the whole request
stop_server_tools_whenconditions 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.

FieldHolds
choices[0].message.contentthe answer
usage.server_tool_usehow many times each helper ran, such as web_search_requests
usage.costthe 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

HelperTypeDoesBills on
web searchopendunes:web_searchsearches the webeach search
web fetchopendunes:web_fetchreads one pageeach page read
shellopendunes:shellruns commands in a sandboxeach second of sandbox
bashopendunes:bashruns commands in a sandbox, the Anthropic wayeach second of sandbox

Helpers on another model's meter

HelperTypeDoesBills on
image generationopendunes:image_generationdraws a picturethe picture model's meter
advisoropendunes:advisorconsults a stronger modelthat model's tokens
subagentopendunes:subagenthands a task to a smaller modelthat model's tokens

Helpers that cost tokens only

HelperTypeDoes
date and timeopendunes:datetimegives the current date and time
apply patchopendunes:apply_patchproposes edits to a file
tool searchopendunes:tool_searchloads your own tools when the model needs them
model searchopendunes:experimental__search_modelssearches the catalogue

The model's page in Models gives its token rates.

Don't

Don't give a model a search helper it has no use for. It decides how often to search, and every search is charged.

Do

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.

JSON
{
  "plugins": [
    {
      "id": "response-healing"
    }
  ]
}
PluginidDoes
PDF inputsfile-parserreads a PDF sent with the request
response healingresponse-healingrepairs broken JSON in the answer
context compressioncontext-compressioncuts the middle of a prompt too long for the model
Do

Search the web with the opendunes:web_search helper. It replaces the web plugin and the :online suffix.

Errors

The body says why.

StatusWhen
400the request is malformed, or longer than the model takes
401the key is missing, wrong, disabled or expired
402your 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
404model is not on sale
429the provider is limiting its rate; Retry-After says how many seconds to wait

What to do on each: Errors and retries.

Last modified on