0%

Tools · practice

Send the Result Back

Your program has run read_note and holds the text of 03-lists.md. The model has not seen it. It also remembers nothing of its own request, because, as Chapter 2 showed, a model keeps nothing between requests. So the second request has to carry the whole story: the question, the model’s request to run a tool, and the result.

The two new messages

The second request sends the original messages again, followed by two kinds of message you have not sent before:

messages = [
    {"role": "user", "content": "What do the notes say about copying a list?"},
    {
        "role": "assistant",
        "content": None,
        "tool_calls": [
            {"id": "call_1_1", "type": "function", "function": {"name": "read_note", "arguments": '{"note_id": "03-lists"}'}},
        ],
    },
    {"role": "tool", "tool_call_id": "call_1_1", "content": "# Lists\n\nA list is an ordered collection ..."},
]

The assistant message records what the model said last time, the way add_turn recorded its text answers in Chapter 2. This time it said nothing in words, so content is None, and what it asked for goes in tool_calls. Each call is written back in the service’s own format: its id, "type": "function", and a "function" with the name and the arguments, still the same JSON string the model sent. Send it back as it came; this is the model’s own message, not something to tidy up.

The tool message carries one result. Its role is "tool", its content is the result string, and tool_call_id is the id of the call it answers. The id is how the model matches results to requests. With one call that seems like a formality, but Lesson 7 has a reply with two calls, and there the ids are the only link between each result and its call.

Order matters. The assistant message with the calls comes first, then a tool message for each of its calls. A tool message with no assistant message before it, or with an id that no call has, is an error on real services. The scripted model does not check this. It counts the assistant messages that carry tool_calls, so without one it asks for the tool again instead of answering.

The second request also sends tools=TOOL_DESCRIPTIONS again. A request carries everything the model knows, and that includes which tools are on offer.

Build the two functions

assistant_turn(calls) takes the list that read_tool_calls returns and gives back the assistant message:

  1. Loop over the calls, and build one dictionary per call: {"id": call["id"], "type": "function", "function": {"name": call["name"], "arguments": call["arguments"]}}.

  2. Return {"role": "assistant", "content": None, "tool_calls": [...]} with those dictionaries, in the same order as calls.

Write the "content": None key, even though its value is empty. It records that the model gave no text, in the same shape the service used in its reply, and the checks expect it.

tool_result(call, result) takes one call dictionary and the string run_tool returned for it, and gives back {"role": "tool", "tool_call_id": call["id"], "content": result}.

Neither function changes the dictionaries it is given. Both build new ones.

Run it

Run python tools.py. The demonstration takes the read_note call and its result from Lesson 4, prints the assistant message, then sends the original question, your assistant message and your tool message, with the same tools:

Sending the result back:
{'role': 'assistant', 'content': None, 'tool_calls': [{'id': 'call_1_1', 'type': 'function', 'function': {'name': 'read_note', 'arguments': '{"note_id": "03-lists"}'}}]}
A tool message for call_1_1 with 1226 characters of content
Answer: The lists note says that two names can refer to the same list, so a change through one shows through the other. Use scores.copy() or list(scores) for an independent copy. (03-lists)
A request for a note that does not exist:
[{'id': 'call_1_1', 'name': 'read_note', 'arguments': '{"note_id": "99-magic"}'}]
run_tool raised ValueError: There is no note called 99-magic. Call list_notes to see the ids.
Run stopped: run_tool does not check the request yet. Lesson 6 changes that.

That is a complete tool round: a question, a request for a tool, your program running it, and an answer that names the note. The scripted model’s answer is fixed, as SCRIPTED_MODEL.md says: it counts the assistant messages with tool calls in your request and gives its next step, without reading the note. A live model would write its answer from the note’s text, which is why the result has to go back at all.

The last lines show the next problem. The demonstration asked What does the note 99-magic say?, the model asked for a note that does not exist, and the ValueError from read_note stopped the whole program. The model, which could have tried something else, never heard about it.

Why does the second request include the assistant message with tool_calls, and not just the question and the tool message?

A tool message has "tool_call_id": "call_1_1". What is the id for?

Task

In tools.py, replace the unfinished bodies of two functions.

  • assistant_turn(calls) returns {"role": "assistant", "content": None, "tool_calls": [...]}, with one item per call in calls, in the same order: {"id": call["id"], "type": "function", "function": {"name": call["name"], "arguments": call["arguments"]}}.

  • tool_result(call, result) returns {"role": "tool", "tool_call_id": call["id"], "content": result}.

Pass the arguments string through unchanged, and do not change the dictionaries you are given. Run python tools.py to see a whole tool round end in an answer, then check your work.