opendunes
Building agents
Copy page ▾

Long-horizon agents

Keep an agent working for hours: cap what it may spend, save it after every turn, and let it check its own work before it stops.

  1. Cap every run.
  2. Save the conversation after every turn.
  3. Review the work until it is done.
  4. Shorten a long conversation.
  5. Say when it ends.

1. Cap every run

A long run is the same tool loop as a short one (Tools and function calling), turned hundreds of times. It must end even when the model never says it is finished, so it carries three ceilings. Whichever comes first stops it.

CeilingStops the run whenSet in
MAX_STEPSthe loop has sent that many requeststhe samples
BUDGETthe sum of usage.cost, in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges →, reaches itthe samples
the key's capthe key has spent its cap: the next request gets a 402API Keys, in the app (Limits)

The samples set BUDGET to 50: set your own. The loop learns a turn's charge only when its answer arrives, so the run can pass BUDGET by one turn. The key's cap is the one that cannot be passed.

Do

Give a long run an API keyAPI keyThe key you create and send with every request that calls a model.More on API keys → of its own, with a cap. A run that goes wrong stops at the cap, and your other keys run on.

2. Save the conversation after every turn

A run that lasts the night meets a restart, a deploy, a laptop lid. After each turn, the samples write the conversation, the steps and the spend to run.json; on start, they read it back and go on from the last turn saved. Delete run.json to start a new run.

On diskHolds
messagesthe whole conversation, tool calls and results included
steps, spentthe ceilings' counters, so a resumed run keeps its budget
answerthe latest full answer
donetrue once the review passed

The samples write to run.json.tmp first, then rename it: a crash in the middle of a write leaves the last good save whole.

3. Review the work until it is done

A first answer often has gaps. When the model answers in words, the loop does not stop: it sends one more turn asking the model to check its answer against the goal. The model either answers again, in full, or replies [DONE]. [DONE] ends the run.

Amina runs a travel agency in Constantine. Overnight, her agent reads the notes her staff left on each hotel and writes a guide, city by city.

import json
import os
from openai import OpenAI

API_KEY = os.environ["OPENDUNES_API_KEY"]
BASE_URL = "https://opendunes.com/v1"
MODEL = "anthropic/claude-sonnet-4.5"
GOAL = "Read notes/hotels.txt and write a hotel guide, city by city."
REVIEW = (
    "Check your last answer against the goal, as a strict reviewer. "
    "If anything is missing or wrong, answer again in full. "
    "If nothing is, reply with [DONE] and nothing else."
)
STATE = "run.json"
BUDGET = 50.0
MAX_STEPS = 200

client = OpenAI(base_url=BASE_URL, api_key=API_KEY)


def read_file(path):
    if not os.path.isfile(path):
        return {"error": f"no file at {path}"}
    with open(path) as file:
        return {"text": file.read()[:20000]}


tools = [
    {
        "type": "function",
        "function": {
            "name": "read_file",
            "description": "Read a text file.",
            "parameters": {
                "type": "object",
                "properties": {"path": {"type": "string"}},
                "required": ["path"],
            },
        },
    }
]


def load():
    if os.path.exists(STATE):
        with open(STATE) as file:
            return json.load(file)
    first = [{"role": "user", "content": GOAL}]
    return {"messages": first, "steps": 0, "spent": 0.0, "done": False}


def save(state):
    with open(STATE + ".tmp", "w") as file:
        json.dump(state, file)
    os.replace(STATE + ".tmp", STATE)


state = load()
messages = state["messages"]

while (
    not state["done"]
    and state["steps"] < MAX_STEPS
    and state["spent"] < BUDGET
):
    reply = client.chat.completions.create(
        model=MODEL,
        messages=messages,
        tools=tools,
    )
    state["steps"] += 1
    state["spent"] += reply.usage.cost
    message = reply.choices[0].message
    messages.append(message.model_dump(exclude_none=True))
    for call in message.tool_calls or []:
        result = read_file(**json.loads(call.function.arguments))
        messages.append(
            {
                "role": "tool",
                "tool_call_id": call.id,
                "content": json.dumps(result),
            }
        )
    if not message.tool_calls:
        if "[DONE]" in message.content:
            state["done"] = True
        else:
            state["answer"] = message.content
            messages.append({"role": "user", "content": REVIEW})
    save(state)

print(state.get("answer"))
print(state["steps"], state["spent"])

The cURL sample is the review turn: the goal, a draft answer, and the request to check it.

Watch out

A review turn is a full turn: it reads the whole conversation again. On a long run, reviews are a large part of the spend, which is why they count against BUDGET like any other turn.

4. Shorten a long conversation

Every turn sends the whole conversation, so each one costs more than the last, and a run can outgrow what the model takes in one request: a 400. When the conversation grows long, keep its first message and its latest turns, and replace the middle with a summary written by the model.

JSON
{
  "model": "anthropic/claude-sonnet-4.5",
  "max_tokens": 800,
  "messages": [
    {
      "role": "system",
      "content": "Summarise as a progress note: done, left, facts still needed."
    },
    {
      "role": "user",
      "content": "…the middle turns, as text…"
    }
  ]
}

The summary goes back as one user message between the goal and the latest turns. Cut between turns, never inside one: a tool message kept without the assistant message that called it is refused.

Good to know

How long each model's context runs is on its page in Models. A cut at half of it leaves the run room to work.

5. Say when it ends

Nobody watches a run at 3 in the morning. When the loop ends, post what it did to your own address: a webhook, a message to the team, a line in a log. Send the reason it ended with it, because a run stopped by BUDGET is not a run that finished.

Illustrative: the values are an example.

JSON
{
  "run": "hotel-guide",
  "ended_by": "done",
  "steps": 37,
  "spent": 21.4
}
ended_byMeans
donethe review passed
max_stepsthe run hit MAX_STEPS
budgetthe run hit BUDGET
key_capthe key's cap is spent: the request got a 402

A run that pauses for a person before a risky call: Human approval on tool calls.

What it costs

Each turn is a request of its own, charged as one: usage.cost on its answer, in DA, from your balanceBalanceWhat you can spend, in DA.More on Balance and charges →. The turns grow as the conversation does, so the last hour of a run costs more than the first. The samples keep the running sum in spent, and Activity, in the app, lists every turn. What to do on each status: Errors and retries.

Last modified on