0%

A Small Agent · practice

Write the Loop

The loop from Lesson 1 needs three things from its caller: the question, the tools the model may use, and the instructions in the system message. This lesson builds it as run_agent.

Which tools, and their descriptions

In Chapter 6, answer_with_tools used the module’s TOOLS and TOOL_DESCRIPTIONS, so it always offered the same two tools. An agent should not get every tool by default: an agent that answers questions has no business writing files. So run_agent takes tools as a parameter, one dictionary from names to functions, like TOOLS. Near the top of agent.py are two that the Runs use:

READ_TOOLS = {"list_notes": list_notes, "read_note": read_note}
AGENT_TOOLS = {"list_notes": list_notes, "read_note": read_note, "save_flashcard": save_flashcard}

The request needs a description for each of those tools, and only for those. The descriptions live in one list, AGENT_DESCRIPTIONS: Chapter 6’s TOOL_DESCRIPTIONS plus SAVE_FLASHCARD_DESCRIPTION. The supplied describe_tools picks the ones you need:

def describe_tools(tools, descriptions):
    """Return the descriptions of the tools in tools, in the order of descriptions."""
    names = []
    for description in descriptions:
        names.append(description["function"]["name"])
    for name in tools:
        if name not in names:
            raise ValueError(f"There is no description for the tool {name}.")
    chosen = []
    for description in descriptions:
        if description["function"]["name"] in tools:
            chosen.append(description)
    return chosen

describe_tools(READ_TOOLS, AGENT_DESCRIPTIONS) returns the descriptions of list_notes and read_note, and leaves out save_flashcard. A tool with no description is a mistake in the program, not something the model did, so it raises instead of quietly leaving the tool out. The caller chooses the tools, and the descriptions follow from that choice.

Build run_agent

run_agent(question, *, client, tools, system):

  1. Start the conversation: messages = [{"role": "system", "content": system}, {"role": "user", "content": question}].

  2. Get the descriptions once: descriptions = describe_tools(tools, AGENT_DESCRIPTIONS).

  3. Loop with while True:. In each pass:

    • Send the conversation: response = client.chat.completions.create(model=MODEL, messages=messages, tools=descriptions).

    • Read the calls with calls = read_tool_calls(response).

    • If there are none, this is the answer. Take the reply’s content, or "" when it is None, add {"role": "assistant", "content": answer} to messages, and return {"answer": answer, "stop_reason": "answered", "messages": messages}.

    • Otherwise, add assistant_turn(calls) to messages, then every message from tool_messages(calls, tools), in order.

The return inside the loop is what ends it. A while True: loop has no condition that can become false, so a return (or an exception) is the only way out.

Use the tools and system you are given. The checks pass their own tools and their own system text, and they script the model’s replies, including two calls in one reply and three rounds of tools before an answer.

Why it returns a dictionary

run_agent could return just the answer text, as answer_with_tools did. It returns a dictionary instead, because a caller needs more than the text:

  • "answer" is the reply the person sees.

  • "stop_reason" says why the loop ended. So far there is only one way to end, "answered". The next lessons add others, and then an empty answer means something different depending on the reason.

  • "messages" is the whole conversation, including the final answer. A caller that wants to ask a follow-up question can add a user message to it and carry on, as Chapter 2’s chat did with its history.

Later lessons add keys to the same dictionary without changing what the first three mean.

The system text is a parameter for a similar reason. This chapter’s Runs pass TOOLS_SYSTEM, which asks the model to look things up and name the note it used. A different job needs different instructions: the study assistant you finish in Chapter 11 runs this same loop with a system message that asks for an answer with citations.

Run it

Run python agent.py. The demonstration calls your run_agent with the errors question, READ_TOOLS and system=TOOLS_SYSTEM:

The agent loop:
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)
The conversation has 7 messages.
Run stopped at the next function to build: run_agent gets its max_steps parameter in Lesson 3.

The loop made the three requests from Lesson 1’s table. The seven messages are the system message, the question, two assistant messages with their tool results, and the final answer.

This loop trusts the model completely: it goes round for as long as the model keeps asking. The scripted model stops after two rounds for this question. The next lesson shows a model that never stops.

run_agent is called with tools=READ_TOOLS. Why does the request leave out the description of save_flashcard, which is in AGENT_DESCRIPTIONS?

run_agent loops with while True:. How does it ever finish?

Task

In agent.py, replace the unfinished body of run_agent(question, *, client, tools, system).

  1. Start with messages = [{"role": "system", "content": system}, {"role": "user", "content": question}] and descriptions = describe_tools(tools, AGENT_DESCRIPTIONS).

  2. In a while True: loop, call client.chat.completions.create(model=MODEL, messages=messages, tools=descriptions) and read the calls with read_tool_calls.

  3. With no calls, add {"role": "assistant", "content": answer} to messages, where answer is the reply’s content or "" when it is None, and return {"answer": answer, "stop_reason": "answered", "messages": messages}.

  4. Otherwise add assistant_turn(calls) and every message from tool_messages(calls, tools) to messages, and go round again.

Use the tools and system you are given. Run python agent.py to see the agent answer the errors question, then check your work.