# 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](#1-cap-every-run).
2. [Save the conversation after every turn](#2-save-the-conversation-after-every-turn).
3. [Review the work until it is done](#3-review-the-work-until-it-is-done).
4. [Shorten a long conversation](#4-shorten-a-long-conversation).
5. [Say when it ends](#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](/docs/tools)), 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 DA, 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](/docs/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.

<div class="do">
<p>Give a long run an API key of its own, with a cap. A run that goes wrong stops at the cap, and your other keys run on.</p>
</div>

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

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

```javascript
import fs from "node:fs";
import OpenAI from "openai";

const API_KEY = process.env.OPENDUNES_API_KEY;
const BASE_URL = "https://opendunes.com/v1";
const MODEL = "anthropic/claude-sonnet-4.5";
const GOAL = "Read notes/hotels.txt and write a hotel guide, city by city.";
const 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.";
const STATE = "run.json";
const BUDGET = 50;
const MAX_STEPS = 200;

const client = new OpenAI({ baseURL: BASE_URL, apiKey: API_KEY });

function readFile({ path }) {
  if (!fs.existsSync(path)) return { error: `no file at ${path}` };
  return { text: fs.readFileSync(path, "utf8").slice(0, 20000) };
}

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

function load() {
  if (fs.existsSync(STATE)) return JSON.parse(fs.readFileSync(STATE));
  const first = [{ role: "user", content: GOAL }];
  return { messages: first, steps: 0, spent: 0, done: false };
}

function save(state) {
  fs.writeFileSync(STATE + ".tmp", JSON.stringify(state));
  fs.renameSync(STATE + ".tmp", STATE);
}

const state = load();
const messages = state.messages;

while (!state.done && state.steps < MAX_STEPS && state.spent < BUDGET) {
  const reply = await client.chat.completions.create({
    model: MODEL,
    messages,
    tools,
  });
  state.steps += 1;
  state.spent += reply.usage.cost;
  const message = reply.choices[0].message;
  messages.push(message);
  for (const call of message.tool_calls ?? []) {
    const result = readFile(JSON.parse(call.function.arguments));
    messages.push({
      role: "tool",
      tool_call_id: call.id,
      content: JSON.stringify(result),
    });
  }
  if (!message.tool_calls?.length) {
    if (message.content.includes("[DONE]")) {
      state.done = true;
    } else {
      state.answer = message.content;
      messages.push({ role: "user", content: REVIEW });
    }
  }
  save(state);
}

console.log(state.answer);
console.log(state.steps, state.spent);
```

```go
package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"
	"strconv"
	"strings"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/option"
)

const (
	baseURL = "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."
	stateFile = "run.json"
	budget    = 50.0
	maxSteps  = 200
)

type runState struct {
	Messages []openai.ChatCompletionMessageParamUnion `json:"messages"`
	Steps    int                                      `json:"steps"`
	Spent    float64                                  `json:"spent"`
	Answer   string                                   `json:"answer"`
	Done     bool                                     `json:"done"`
}

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

	client := openai.NewClient(
		option.WithBaseURL(baseURL),
		option.WithAPIKey(apiKey),
	)

	path := map[string]any{"type": "string"}
	tools := []openai.ChatCompletionToolUnionParam{
		openai.ChatCompletionFunctionTool(openai.FunctionDefinitionParam{
			Name:        "read_file",
			Description: openai.String("Read a text file."),
			Parameters: openai.FunctionParameters{
				"type":       "object",
				"properties": map[string]any{"path": path},
				"required":   []string{"path"},
			},
		}),
	}

	state := load()
	for !state.Done && state.Steps < maxSteps && state.Spent < budget {
		params := openai.ChatCompletionNewParams{
			Model:    model,
			Messages: state.Messages,
			Tools:    tools,
		}
		reply, err := client.Chat.Completions.New(context.TODO(), params)
		if err != nil {
			panic(err)
		}
		cost := reply.Usage.JSON.ExtraFields["cost"].Raw()
		charge, _ := strconv.ParseFloat(cost, 64)
		state.Steps++
		state.Spent += charge
		message := reply.Choices[0].Message
		state.Messages = append(state.Messages, message.ToParam())
		for _, call := range message.ToolCalls {
			var args struct{ Path string }
			json.Unmarshal([]byte(call.Function.Arguments), &args)
			result := openai.ToolMessage(readFile(args.Path), call.ID)
			state.Messages = append(state.Messages, result)
		}
		if len(message.ToolCalls) == 0 {
			if strings.Contains(message.Content, "[DONE]") {
				state.Done = true
			} else {
				state.Answer = message.Content
				next := openai.UserMessage(review)
				state.Messages = append(state.Messages, next)
			}
		}
		save(state)
	}

	fmt.Println(state.Answer)
	fmt.Println(state.Steps, state.Spent)
}

func readFile(path string) string {
	raw, err := os.ReadFile(path)
	if err != nil {
		return `{"error": "no such file"}`
	}
	text := string(raw)
	if len(text) > 20000 {
		text = text[:20000]
	}
	out, _ := json.Marshal(map[string]string{"text": text})
	return string(out)
}

func load() runState {
	state := runState{Messages: []openai.ChatCompletionMessageParamUnion{
		openai.UserMessage(goal),
	}}
	if raw, err := os.ReadFile(stateFile); err == nil {
		json.Unmarshal(raw, &state)
	}
	return state
}

func save(state runState) {
	raw, _ := json.Marshal(state)
	os.WriteFile(stateFile+".tmp", raw, 0o644)
	os.Rename(stateFile+".tmp", stateFile)
}
```

```bash cURL
ADDRESS="https://opendunes.com/v1/chat/completions"
MODEL="anthropic/claude-sonnet-4.5"
GOAL="Read notes/hotels.txt and write a hotel guide, city by city."
DRAFT="Constantine: Hotel Cirta, near the bridges. Oran: Hotel Royal."
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."

curl "$ADDRESS" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "messages": [
      {
        "role": "user",
        "content": "'"$GOAL"'"
      },
      {
        "role": "assistant",
        "content": "'"$DRAFT"'"
      },
      {
        "role": "user",
        "content": "'"$REVIEW"'"
      }
    ]
  }'
```

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

<div class="watch-out">
<p>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 <code>BUDGET</code> like any other turn.</p>
</div>

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

<div class="good-to-know">
<p>How long each model's context runs is on its page in <a href="/docs/models">Models</a>. A cut at half of it leaves the run room to work.</p>
</div>

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