0%

A Small Agent · capstone

Capstone project: Project: A Study Agent with Limits

Lesson 2 built the loop, and Lessons 3, 4 and 7 added its stop checks one at a time, each where it fitted. The order of the checks now matters, and it is spread over several if statements in the middle of run_agent. This project moves the decision into one small function, stop_reason, and makes run_agent act on what it says:

result = run_agent("What does the note on errors say about finally?",
    client=make_client(), tools=READ_TOOLS, system=TOOLS_SYSTEM,
    approve=refuse_all, max_steps=6, max_tokens_total=2000)
print(result["stop_reason"])
print_trace(result["trace"])
answered
Step 1 (48 tokens)
  list_notes {} -> 140 characters
Step 2 (89 tokens)
  read_note {"note_id": "07-errors"} -> 1325 characters
Step 3 (454 tokens)
  answered

The pieces you have

StepYour code
Choose the descriptionsdescribe_tools(tools, AGENT_DESCRIPTIONS) (supplied, Lesson 2)
Read the calls from a replyread_tool_calls(response) (Chapter 6)
Record the model’s requestassistant_turn(calls) (Chapter 6)
Run the calls, asking first where neededrun_calls(calls, tools, approve) (Lesson 6)
Notice a repeatrepeated_call(calls, trace) (Lesson 7)
Count steps and tokens, keep the traceinside run_agent (Lessons 3 to 5)

Build stop_reason

stop_reason(calls, repeated, used, max_tokens_total, steps, max_steps) gets everything the checks need as arguments, and returns a reason or None. It checks in this order:

  1. "answered" when calls is empty.

  2. "budget" when used >= max_tokens_total.

  3. "stuck" when repeated is true.

  4. "max_steps" when steps >= max_steps.

  5. Otherwise None: keep going.

The order is the design:

  • An answer is never thrown away. A reply with no calls is the result the run was for, so it wins over every limit. It is already paid for.

  • Money comes first among the limits. When the budget is used up, that is the most important thing for the caller to know, whatever else is also true.

  • A repeat is named before the step limit, so the reason says what went wrong. A model stuck on its last allowed step is stuck; “it ran out of steps” hides that.

Because stop_reason is a plain function of its arguments, with no client and no loop, every combination can be tested on its own. The checks try all sixteen combinations of the four conditions.

Here is the loop you are about to rebuild, with stop_reason in the middle. Read its checks from top to bottom: the first one that holds decides, and only None leads to running the calls.

In the agent loop, stop_reason checks answered, budget, stuck and max_steps in that order, and only when none holds are the calls run before the next step.

Rebuild run_agent

run_agent(question, *, client, tools, system, approve, max_steps, max_tokens_total):

  1. Start messages with the system message and the question, get the descriptions with describe_tools, and start the trace, the step count and the token total.

  2. In a while True: loop, call create with model=MODEL, messages and the descriptions. Count the step, add the reply’s usage.total_tokens to the total, and read the calls.

  3. Work out repeated = repeated_call(calls, trace), then append this step’s trace entry.

  4. Call stop_reason(calls, repeated, used, max_tokens_total, steps, max_steps).

  5. On "answered", add {"role": "assistant", "content": answer} to messages, with the reply’s content or "", and return {"answer": answer, "stop_reason": "answered", "trace": trace, "messages": messages}.

  6. On any other reason, return {"answer": "", "stop_reason": reason, "trace": trace, "messages": messages}. The stopping reply’s assistant message is not added, and its calls never run.

  7. On None, add assistant_turn(calls) to messages, run the calls with run_calls(calls, tools, approve), add each tool message to messages and its content to the entry’s "results", and go round again.

messages is always the conversation as it was last sent, plus the final assistant message when the run answered. Use the tools, system and approve you are given. The checks pass their own, script the model’s replies, and look at the trace and messages for every stop reason, including replies on which several conditions hold at once.

Run it

Run python agent.py. Now that stop_reason exists, the demonstration skips the lessons’ output and runs the finished agent five ways, each followed by its trace:

Answered, with max_steps=6 and max_tokens_total=2000:
Step 1 (48 tokens)
  list_notes {} -> 140 characters
Step 2 (89 tokens)
  read_note {"note_id": "07-errors"} -> 1325 characters
Step 3 (454 tokens)
  answered
stop_reason: answered
answer: The errors note says that a finally block always runs, whether or not an exception was raised. An else block, by contrast, runs only when nothing was raised. (07-errors)
Over budget, with max_tokens_total=100:
Step 1 (48 tokens)
  list_notes {} -> 140 characters
Step 2 (89 tokens)
  read_note {"note_id": "07-errors"} (not run)
stop_reason: budget
At the step limit, with max_steps=2:
Step 1 (48 tokens)
  list_notes {} -> 140 characters
Step 2 (89 tokens)
  read_note {"note_id": "07-errors"} (not run)
stop_reason: max_steps
Stuck, through the tool-loop scenario:
Step 1 (48 tokens)
  list_notes {} -> 140 characters
Step 2 (83 tokens)
  list_notes {} (not run)
stop_reason: stuck
The flashcard request, refused:
Step 1 (50 tokens)
  read_note {"note_id": "03-lists"} -> 1226 characters
Step 2 (391 tokens)
  save_flashcard {"name": "copying-a-list", "front": "How do you make an independent copy of a list?", "back": "Use scores.copy() or list(scores). Both build a new list."} -> 58 characters
Step 3 (414 tokens)
  answered
stop_reason: answered
answer: I did not save the flashcard, because you did not approve it. Here it is, so you can write it down yourself: How do you make an independent copy of a list? Use scores.copy() or list(scores). (03-lists)

The budget and step-limit runs stop at the same reply for different reasons, and their traces look alike: the reason is what tells them apart. With max_steps=2, step 2 asks for a new call, read_note, so it is the step limit that stops it; in the tool-loop run, step 2 repeats step 1, so it is stuck.

The demonstration shows each reason once. Before you check your work, think about the replies it does not show: a repeat that also uses up the budget, an answer that arrives on the last allowed step, and a reply that is a repeat on the last step. stop_reason’s order decides each one. If you get stuck, ask Monty for a hint about one case without asking for the whole function.

Try it live

This step is optional. run_agent reads the module’s MODEL each time it calls the model, so a short script can point it at the live model without changing agent.py. Create a file called try_live.py next to agent.py with these lines, then run python try_live.py in the :

import agent

agent.MODEL = "pl-live"
result = agent.run_agent(
    "What does the note on errors say about finally?",
    client=agent.make_client(),
    tools=agent.READ_TOOLS,
    system=agent.TOOLS_SYSTEM,
    approve=agent.refuse_all,
    max_steps=6,
    max_tokens_total=2000,
)
agent.print_trace(result["trace"])
print(result["stop_reason"])
print(result["answer"])

The live model chooses its own steps. It may call list_notes first, as the scripted model does, or guess the note’s id and read it straight away, and it writes its own answer from the note. Its token counts are real: they include the tool descriptions and any reasoning, so the run may stop with "budget" where the scripted run answered. A 403 means your account has no live access, and a 429 means you reached the limit for now. A read timeout is a normal outcome too: a live model can think for longer than this course’s read bound. Delete try_live.py when you are done.

Where this goes next

The study assistant now has an agent that looks things up for as long as it needs to, within limits you set, asks before it writes, and reports every step. Chapter 8 gives it a better way to find things than reading whole notes: a search tool that returns only the passages that match a question. Chapter 9 sends every model call through one wrapper that retries what is worth retrying and replaces this chapter’s token count with a budget that every call shares.

After a reply that repeats an earlier call, the token total has also reached the budget. What does stop_reason return?

The last allowed step's reply answers the question, and that reply takes the token total past the budget. What does run_agent return?

Task

In agent.py, replace the unfinished body of stop_reason(calls, repeated, used, max_tokens_total, steps, max_steps), then make run_agent use it.

  1. stop_reason checks in this order: "answered" when calls is empty, "budget" when used >= max_tokens_total, "stuck" when repeated, "max_steps" when steps >= max_steps. Otherwise it returns None.

  2. run_agent(question, *, client, tools, system, approve, max_steps, max_tokens_total) calls stop_reason after every reply.

  3. On "answered", add the final assistant message and return the content (or "") as the answer. On any other reason, return "" as the answer, without running the calls or adding their assistant message.

  4. On None, run the calls with run_calls and go round again.

Every result has "answer", "stop_reason", "trace" and "messages". Run python agent.py to see each stop reason, then check your work.