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.
- Cap every run.
- Save the conversation after every turn.
- Review the work until it is done.
- Shorten a long conversation.
- 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.
| Ceiling | Stops the run when | Set in |
|---|---|---|
MAX_STEPS | the loop has sent that many requests | the samples |
BUDGET | the sum of usage.cost, in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges →, reaches it | the samples |
| the key's cap | the key has spent its cap: the next request gets a 402 | API 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.
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 disk | Holds |
|---|---|
messages | the whole conversation, tool calls and results included |
steps, spent | the ceilings' counters, so a resumed run keeps its budget |
answer | the latest full answer |
done | true 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.
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.
{
"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.
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.
{
"run": "hotel-guide",
"ended_by": "done",
"steps": 37,
"spent": 21.4
}ended_by | Means |
|---|---|
done | the review passed |
max_steps | the run hit MAX_STEPS |
budget | the run hit BUDGET |
key_cap | the 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