opendunes
Helpers · 3 min
Copy page ▾

Subagent

Let a model hand a self-contained task to a smaller, cheaper model, and pay for the worker on its own meter.

  1. What it does.
  2. Name it in tools.
  3. Shape the worker.
  4. Read what it bills on.

This page is one helperHelperA tool run for you when a model reaches for it mid-answer: a web search, a page read, a sandbox. Named opendunes:‹name›.More on Helpers →. The list of helpers, and how the charge adds up, sit in Helpers.

1. What it does

Your model hands a task to a worker model: summarise this changelog, extract these fields, look this up. The worker sees only the task your model writes for it, never the conversation, and its outcome comes back as the helper's result. When your model calls the helper, it passes a task_name and a task_description, which must hold everything the worker needs.

Typeopendunes:subagent
Routes/v1/chat/completions, /v1/responses and /v1/messages
A stepone task
Stepsat most 30 a request
Bills onthe worker model's tokens, and its own helper calls on their meters, in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges →, beside your model's

2. Name it in tools

Souk Bot compares what three mobile operators offer. Sonnet plans and hands the lookups to a smaller worker that may search the web itself. The sample allows three tasks and prints the answer and the charge.

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"
WORKER = "anthropic/claude-haiku-4.5"
PROMPT = "Compare the offers of the three mobile operators in Algeria."

body = {
    "model": MODEL,
    "messages": [{"role": "user", "content": PROMPT}],
    "tools": [
        {
            "type": "opendunes:subagent",
            "parameters": {
                "model": WORKER,
                "tools": [{"type": "opendunes:web_search"}],
            },
        }
    ],
    "max_tool_calls": 3,
}
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"])

The answer is a 200. Name the helper by its type, opendunes:subagent; any other spelling of the type is a 400.

3. Shape the worker

Put these in the helper's parameters.

ParameterDoes
modelthe worker; left out, the request's own model
namenames this worker; several opendunes:subagent entries, each named, offer a choice, and at most one may go unnamed
toolshelpers the worker may use itself, such as opendunes:web_search; your own functions are refused here with a 400
instructionsthe worker's system instructions
max_tool_callsthe worker's own helper steps, from 1 to 25
max_completion_tokens · reasoning · temperaturepassed to the worker's call

The request's max_tool_calls and the worker's are two limits: the first counts tasks handed over, the second counts the steps inside one task.

4. Read what it bills on

One charge, in DA, from your balanceBalanceWhat you can spend, in DA.More on Balance and charges →, the moment the answer ends: your model's tokens, the worker's tokens at the worker model's own price, and the worker's own helper calls, each on its meter. usage.cost carries the whole of it. The worker model's page in Models gives its token rates.

The helper runs another model, so it has a spend cap. Before the model starts, OpenDunes holds money from your wallet for the words and the answer, and writes the cap into the request.

Your requestThe hold
names no stop_server_tools_whenwrites two conditions: the step count, 30 or your max_tool_calls, and a max_cost equal to half of what the wallet has left after the answer's hold; the helper stops at whichever comes first
names stop_server_tools_when with a max_costholds that cap whole; when the wallet cannot pay it, the answer is a 402 that says what the request needs
names stop_server_tools_when without a max_costkeeps your conditions and adds the cap

A cap is a condition on the request:

JSON
{
  "stop_server_tools_when": [
    { "type": "step_count_is", "step_count": 3 },
    { "type": "max_cost", "max_cost_in_dollars": 0.1 }
  ]
}

When the steps or the cap run out, the model answers with what it has gathered.

Don't

Don't hand a worker a task that needs the conversation. It never sees the conversation, and your model pays to write a long task when a short one would do.

Do

Hand over self-contained lookups and extractions, and set the worker's max_tool_calls so one task cannot run long.