A terminal agent app
Build a chat agent that runs in your terminal: it streams its answer, runs your tools, and shows what each turn cost.
- Install the library.
- Read a line, stream the answer.
- Run the tools the model calls.
- Show what each turn cost.
- Add what your app needs.
1. Install the library
The app is one file on the OpenAI library, with no terminal framework: it reads a line, prints the answer as it arrives, and loops.
| Tab | Install line | Run |
|---|---|---|
| Python | pip install openai | python agent.py |
| JavaScript | npm install openai | node agent.mjs |
| Go | go get github.com/openai/openai-go/v3 | go run . |
Put your key in OPENDUNES_API_KEY first, in the terminal the app runs in (API keys).
2. Read a line, stream the answer
Each line you type becomes a user message. The app sends the whole conversation with stream set to true, and prints each piece of the answer as it arrives (Streaming). Two commands never reach the model: /cost prints the session's charge so far, /exit quits.
Sofiane keeps his shop's price lists in text files. His terminal agent reads them and answers his questions about them.
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"
SYSTEM = "You help in a terminal. Use read_file to read files."
MAX_STEPS = 10
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 stream_turn(messages):
stream = client.chat.completions.create(
model=MODEL,
messages=messages,
tools=tools,
stream=True,
)
text, calls, cost = "", {}, 0.0
for chunk in stream:
if chunk.usage:
cost = chunk.usage.cost
if not chunk.choices:
continue
delta = chunk.choices[0].delta
if delta.content:
print(delta.content, end="", flush=True)
text += delta.content
for part in delta.tool_calls or []:
empty = {"id": "", "name": "", "args": ""}
call = calls.setdefault(part.index, empty)
call["id"] = part.id or call["id"]
if part.function:
call["name"] = part.function.name or call["name"]
call["args"] += part.function.arguments or ""
message = {"role": "assistant", "content": text or None}
if calls:
message["tool_calls"] = [
{
"id": call["id"],
"type": "function",
"function": {"name": call["name"], "arguments": call["args"]},
}
for call in calls.values()
]
return message, cost
messages = [{"role": "system", "content": SYSTEM}]
session = 0.0
while True:
line = input("\n> ").strip()
if line == "/exit":
break
if line == "/cost":
print(f"{session} DA this session")
continue
if not line:
continue
messages.append({"role": "user", "content": line})
turn = 0.0
for step in range(MAX_STEPS):
message, cost = stream_turn(messages)
turn += cost
messages.append(message)
for call in message.get("tool_calls", []):
args = json.loads(call["function"]["arguments"] or "{}")
print(f"\n -> {call['function']['name']} {args}")
messages.append(
{
"role": "tool",
"tool_call_id": call["id"],
"content": json.dumps(read_file(**args)),
}
)
if "tool_calls" not in message:
break
session += turn
print(f"\n {turn} DA")The cURL sample is one streamed turn: its pieces carry the words, or the read_file call your code runs.
3. Run the tools the model calls
A streamed call arrives in pieces too: the call's id and name first, then its arguments a few characters at a time, all under the same index. The app joins the pieces, and once the stream ends, runs each call and sends the results back (Tools and function calling). The model then streams its answer, or calls again, up to MAX_STEPS times for one line.
A piece's delta carries | The app |
|---|---|
content | prints it, and keeps it for the conversation |
tool_calls[].id, function.name | starts the call at that index |
tool_calls[].function.arguments | adds the characters to that call's arguments |
Go's ChatCompletionAccumulator joins the pieces for you.
Parse a call's arguments only once the stream has ended. Midway, they are half a JSON object.
4. Show what each turn cost
The last piece of each stream carries usage, with usage.cost: that request's charge in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges →. One line can take several requests when the model calls tools, so the app adds them up in turn and prints the sum under the answer. session holds the total since the app started, and /cost prints it.
Illustrative: the question and the charge are an example.
> What does prices.txt say about the Galaxy A16?
-> read_file {"path": "prices.txt"}
The Galaxy A16 is listed at two prices: the 128 GB model and the 256 GB…
0.041288 DA5. Add what your app needs
| Add | How |
|---|---|
| a tool that writes, deletes or pays | ask before it runs: Human approval on tool calls |
| a session that survives a restart | save the conversation after each turn: Long-horizon agents |
| a stronger model to consult | Review by a stronger model |
| the same agent with no one at the keyboard | A headless agent |
An error after the first piece arrives under a 200: the last piece carries error, and finish_reason reads error. Check for it before you keep the text. What to do on each status: Errors and retries.
Last modified on