Skip to content

First agent run

New in 0.2

In this tutorial you run the agent loop once on a tiny random model, with no API key and no GPU. The scripted editor stands in for a model: it sends a fixed list of tool calls to the MCP server, saves one edit, runs two forward passes and finishes. Then you read what the run left on disk.

You need the mcp and hf extras:

pip install "astro-weights[mcp,hf]"

1. Make a model

A two-layer random Llama with a word-level tokenizer stands in for a real model, so nothing is downloaded. The server loads the model from a directory, so save both to tiny-model/.

import torch
import transformers
from tokenizers import Tokenizer, models, pre_tokenizers

torch.manual_seed(0)
config = transformers.LlamaConfig(
    vocab_size=128,
    hidden_size=32,
    intermediate_size=64,
    num_hidden_layers=2,
    num_attention_heads=4,
    num_key_value_heads=2,
    max_position_embeddings=64,
)
transformers.LlamaForCausalLM(config).save_pretrained("tiny-model")

words = ["<unk>", "<s>", "</s>"] + [f"w{i}" for i in range(125)]
tok = Tokenizer(
    models.WordLevel({w: i for i, w in enumerate(words)}, unk_token="<unk>")
)
tok.pre_tokenizer = pre_tokenizers.Whitespace()
transformers.PreTrainedTokenizerFast(
    tokenizer_object=tok, unk_token="<unk>", bos_token="<s>", eos_token="</s>"
).save_pretrained("tiny-model")

2. Write the run config

A run config is a TOML file. It names the run directory, the model, the budget and the editor. Relative paths are read from the config file's directory.

from pathlib import Path

Path("agent.toml").write_text("""\
[run]
dir = "runs/first"
seed = 0
model_dir = "tiny-model"

[limits]
forward_passes = 4
code_runs = 4
tokens = 0
dollars = 0

[editor]
kind = "scripted"

[forward]
device = "cpu"
""")

The scripted editor uses 2 code runs and 2 forward passes, so a limit of 4 each leaves room.

3. Run it

astro-weights run agent.toml

The same from Python:

from astro_weights.cli import main

assert main(["run", "agent.toml"]) == 0

run checks the config and the extras, writes runs/first/run.json and a copy of the config (runs/first/config.toml), then starts the editor. The editor starts the MCP server (python -m astro_weights.mcp runs/first) as its child and talks to it over stdio. Exit code 0 means the run finished.

On Linux the agent's code runs under bubblewrap, on macOS under Seatbelt. With neither, the run stops with an error; see Explanation: agent budgets and sandbox.

4. Read the ledger

ledger.jsonl holds one line per charge, refusal or failure. Only finished work is charged.

import json

ledger = [json.loads(line) for line in open("runs/first/ledger.jsonl")]
for entry in ledger:
    print(entry["op"], entry["kind"], entry["amount"], entry["ref"])

Prints four charges, two code_runs and two forward_passes, each with the handle of the job that spent it, for example charge code_runs 1 exec-7b2ba8487f2dbaf9.

5. Read the record

record.jsonl is the run's history: a start line (seed, limits, editor, library version), events such as edit_saved, the editor's summary, the export of the edits and a final finish line with the budget.

record = [json.loads(line) for line in open("runs/first/record.jsonl")]
print([e["event"] for e in record])
print(record[-1]["outcome"], record[-1]["budget"]["used"])

Prints:

['start', 'edit_saved', 'summary', 'export', 'finish']
finished {'forward_passes': 2, 'code_runs': 2, 'tokens': 0, 'dollars': 0.0}

The saved edit sits in runs/first/edits/, and each job's request and result in runs/first/jobs/.

6. Inspect the adapter

On finish the server turned the stored edit into a PEFT LoRA adapter in runs/first/export/adapter:

astro-weights inspect runs/first/export/adapter

7. Status and resume

astro-weights run agent.toml --status

prints the state (finished), the budget used against each limit, the stored edits and the last events, from disk. Running astro-weights run agent.toml again is refused: the directory already holds a run. --resume goes on with an unfinished run and keeps the budget it used; a new run needs a new [run] dir.

Next