# Helpers

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

1. [Name the helper in `tools`](#1-name-the-helper-in-tools).
2. [Read the answer](#2-read-the-answer).
3. [Read what it cost](#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](/docs/tools) 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.

```python
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"])
```

```javascript
const API_KEY = process.env.OPENDUNES_API_KEY;
const ADDRESS = "https://opendunes.com/v1/chat/completions";
const MODEL = "anthropic/claude-sonnet-4.5";
const PROMPT = "What does an iPhone 16 cost in Algiers today? Cite sources.";

const response = await fetch(ADDRESS, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: MODEL,
    messages: [{ role: "user", content: PROMPT }],
    tools: [{ type: "opendunes:web_search" }],
  }),
});
const answer = await response.json();

console.log(answer.choices[0].message.content);
console.log(answer.usage.cost);
```

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

const (
	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."
)

func main() {
	apiKey := os.Getenv("OPENDUNES_API_KEY")

	body, err := json.Marshal(map[string]any{
		"model": model,
		"messages": []map[string]string{
			{"role": "user", "content": prompt},
		},
		"tools": []map[string]string{
			{"type": "opendunes:web_search"},
		},
	})
	if err != nil {
		panic(err)
	}

	req, err := http.NewRequest("POST", address, bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var answer struct {
		Choices []struct {
			Message struct {
				Content string `json:"content"`
			} `json:"message"`
		} `json:"choices"`
		Usage struct {
			Cost json.Number `json:"cost"`
		} `json:"usage"`
	}
	if err := json.NewDecoder(res.Body).Decode(&answer); err != nil {
		panic(err)
	}
	fmt.Println(answer.Choices[0].Message.Content)
	fmt.Println(answer.Usage.Cost)
}
```

```bash cURL
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."

curl "$ADDRESS" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "messages": [
      {
        "role": "user",
        "content": "'"$PROMPT"'"
      }
    ],
    "tools": [
      {
        "type": "opendunes:web_search"
      }
    ]
  }'
```

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"]
        }
      }
    }
  ]
}
```

<div class="watch-out">
<p>Some helpers work on some routes only. Shell, tool search and bash: <code>/v1/messages</code>.</p>
</div>

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 DA: 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 balance, 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](/models) gives its token rates.

<div class="dont">
<p>Don't give a model a search helper it has no use for. It decides how often to search, and every search is charged.</p>
</div>

<div class="do">
<p>Name only the helpers the task needs, and lower the steps with <code>max_tool_calls</code>.</p>
</div>

## 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"
    }
  ]
}
```

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

<div class="do">
<p>Search the web with the <code>opendunes:web_search</code> helper. It replaces the <code>web</code> plugin and the <code>:online</code> suffix.</p>
</div>

## 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](/docs/errors-and-retries).
