Lab assignment
Manual tool-use loop
Build the application-controlled loop behind a small note assistant, then make every stop state visible.
The brief
Your assignment
Create a tiny fictional study-note catalog with at least three notes. Build an application-controlled tool-use loop that can answer directly, request one or more read-only tools, or stop abnormally.
Architecture path: sketch one synthetic response trace for each verification case below and draw the state machine; no API account is required. Build path: implement the same loop with your fictional notes. Keep every credential server-side and out of browser code.
Before you build
Set up a safe workspace
- Review Tasks 1.1, 2.1, and 2.2.
- Choose the paper architecture path or a server-side build path.
- Create three fictional notes and keep credentials out of browser code.
Build in checkpoints
One observable behavior at a time
- 01Sketch the response-state machine.
- 02Trace a no-tool response and a single tool request.
- 03Add multiple-tool correlation and a visible tool failure.
- 04Route abnormal stop reasons away from normal success.
- 05Add a hard turn cap and record the observed traces.
What you'll practice
- Branch on structured response state rather than phrases such as “done.”
- Correlate every tool result with its tool request.
- Distinguish normal completion, tool use, and abnormal stop reasons.
Your lab files
Four files for each lab
- 01
decision.mdState the requirement, chosen pattern, rejected alternatives, and the reason for the tradeoff.
- 02
implementation/Keep the smallest working example, configuration, diagram, or synthetic-trace analysis.
- 03
evidence.mdRecord test cases, observed results, failure behavior, limitations, and evidence locations.
- 04
review.mdExplain what must be deterministic, what may remain model-directed, and where a human is required.
What to save
- A state diagram for normal, tool-use, and abnormal stops.
- A trace table covering all six test cases.
- A minimal loop or a synthetic-trace analysis.
- Redacted logs that preserve response structure.
Test bench
What good work includes
- A no-tool response finishes without inventing a tool call.
- One and multiple tool requests return correctly correlated results.
- The complete assistant response is preserved.
- A visible tool failure never becomes empty success.
- Output-limit and other abnormal stops avoid the normal-success branch.
- A safety turn cap surfaces an unfinished status.
Review questions
- Why is parsing the word “done” unsafe?
- When would a deterministic workflow be simpler than an agentic loop?
- Which errors can be handled locally, and which must be propagated?
Strong solutions tend to
- Explicit state branches and a hard turn cap.
- Bounded, read-only tools with replayable fixtures.
- Structured logs without secrets or hidden reasoning.
Partial example
What useful evidence can look like
This is one small example, not a complete solution or a template you must copy. Use the notes to see why the evidence is useful.
Open annotated example from evidence.md / trace excerpt
Case: output limit during tool arguments
[1] stop_reason = max_tokens
[2] branch = abnormal_stop
[3] final status = unfinished: response was cut off- [1]
- Records the structured value the application actually received.
- [2]–[3]
- Shows the branch and visible outcome, so the trace proves the response did not become normal success.
Review your work
Use evidence from your work—not confidence alone. For each area, run the check and choose the strongest stage your work fully demonstrates.
Loop state handling
The loop uses structured response states to decide whether to finish, run tools, or report unfinished work.
Compare your no-tool and output-limit traces. Point to the exact branch each response follows and the final status it produces.
Needs another pass
The loop looks for words such as “done,” or treats every response without a tool request as successful.
Partly demonstrated
tool_use and end_turn follow different paths, but at least one abnormal or unknown stop can still fall into normal success.
Demonstrated
Only end_turn finishes normally. tool_use continues the loop, and every abnormal or unknown stop produces a visible unfinished or error state.
Tool requests and results
Every tool request stays paired with its own result, including multiple requests and failures.
Run the single-tool, multiple-tool, and tool-failure cases. Use the trace to match every tool_use ID to one tool_result.
Needs another pass
A result is missing its request ID, multiple results can be mixed up, or a failed call disappears from the conversation history.
Partly demonstrated
One tool call works, but the multiple-call or failed-call trace does not preserve every request and result clearly.
Demonstrated
Every request receives one result with the matching ID. Multiple results remain correctly paired, failures stay visible, and the complete assistant response is preserved.
Failures and safety limits
Tool failures, abnormal stops, and the turn limit are clearly reported instead of looking successful.
Run the tool-failure, output-limit, and turn-cap cases. Confirm that none reaches the same final status as normal completion.
Needs another pass
A failure can become empty success, the loop has no hard turn limit, or an abnormal stop is treated like end_turn.
Partly demonstrated
Tool errors are visible, but the output-limit or turn-cap path does not clearly report that the work is unfinished.
Demonstrated
Tool failures are structured and visible, abnormal stops never report success, and the hard turn limit returns an explicit unfinished status.
Testing and evidence
The submitted traces and diagram show what the loop actually did, not only what it was intended to do.
Ask whether another student could identify the branch, tool pairing, and final status for all six required cases without asking you for an explanation.
Needs another pass
The packet shows only the happy path, describes intended behavior without observed results, or omits the response-state diagram.
Partly demonstrated
Several cases have traces, but expected and observed results are unclear or one of the six required cases is missing.
Demonstrated
The trace table covers all six cases with the response state, chosen branch, tool results, and final status. The diagram agrees with those traces and the logs reveal no secrets.