#Exercises: make the learning stick

No: the model never runs anything. It emits a request: a tool name plus arguments. Your code decides whether and how to execute it. That gap is where all of an agent's safety lives (approval, sandboxing, validation).

Because the description is the model's only basis for deciding when and how to call the tool. A vague description ("does stuff") leads to misuse; a precise one ("use this for arithmetic; expression like '2+2'") leads to correct calls. You're programming the model's behavior through that text.

With a tool call request (calculator, expression="23 * 47"), not the number. It defers the math to the tool. You then run it, and to turn that result into a final answer you'd feed it back and ask again, which is the loop.

Ask the model; if it requests tools, run them, append the results, and ask again; repeat until it responds with no tool calls; that final, tool-free response is the answer. (A step cap is the backstop in case it never stops.)

Usually one (or a few) at a time, using earlier results to inform later steps that step-by-step, result-dependent reasoning is exactly what the loop enables and a single call can't do.

search_notes first (to find the monthly price, a product fact), then calculator (to multiply by 12). The model routes each sub-task to the tool whose description fits. Nothing hard-codes that order; it's the model's choice, guided by the tool descriptions.

Feeding the error back lets the model see what went wrong and adapt (retry with different inputs, or explain): robustness instead of a dead program. max_steps protects against an infinite loop: a model that keeps calling tools and never finishes would otherwise run forever (and run up a bill).

It returns a "stopped early" message and stopped_early=True, because it hit the ceiling before reaching a final answer. That flag is how your code knows the result is incomplete rather than a real answer.

You mark it dangerous=True; the loop then calls your approve callback before running it. With no callback it fails closed; an explicit denial is returned to the model as a normal tool result ("permission denied"), so the agent acknowledges it and adapts instead of forcing the action.

Only the first proposal crosses the effect boundary. The tenant attempt is rejected as trusted-context forgery before ordinary schema validation; the oversized amount fails schema validation; the support principal fails authorization; and the replay returns the first completed result. The final effect count is one.

Strict mode constrains what the provider generates and reduces malformed calls. Local validation treats the resulting request as untrusted at the execution seam and works regardless of provider or transport. Neither authorizes the caller; authorization uses roles and identity from authenticated ExecutionContext, not the model's arguments.

The amount becomes schema_validation, the role becomes not_authorized, and the tenant becomes trusted_context_forgery; none invokes the callable. A new request ID changes the replay scope, so an otherwise allowed call executes a new effect. These independent perturbations prove the decision didn't derive its expected result from the proposal itself.

Neither: it denies with idempotency_key_reuse. Returning the stored result would answer a question nobody asked and bury the second attempt (the audit record would carry the first call's argument digest, so the log wouldn't even show it happened). Running it would defeat the point of the key. A settled key is a promise about one specific payload, which is why the executor compares argument digests and not just the key. Stripe's API behaves the same way for the same reason.

A timeout says the caller stopped waiting, not that the effect failed; the tool may have committed just before the connection disappeared. An automatic retry could duplicate it. Production needs a durable idempotency key enforced transactionally by the sink (plus coordination across workers), because an in-process bounded cache disappears on restart and doesn't stop concurrent workers from racing.

Only replayed changes: it's False for the dispatch and True for the cached retry. Both steps keep status=ok, approval=approved, and the same argument and output digests because they describe the same settled operation. Exactly one event reaches the sink.

Because an agent makes its own multi-step decisions (which tools, in what order, with what arguments. When it goes wrong, the why is in that sequence. Without a trace you're debugging a black box; with one you can see (and later eval) exactly what it did.

It works, because the same history list is passed back each turn, so the earlier search and its results are still in the conversation the model sees. The API is stateless; the memory is the growing list you choose to resend.

Just another tool. Calling research(question=...) looks identical to calling any tool, but its function body runs a second agent loop with its own prompt and tools. Sub-agents are agents wrapped as tools; that's how large systems decompose.

When you can already draw the flowchart. If the steps are known, a workflow (classify → route → handle, orchestrated in code) is cheaper, more predictable, and easier to test. An agent is worth its cost and unpredictability only when the path is genuinely open-ended.

Plan (before) keeps a multi-step task from dropping a sub-goal. Reflect (after) catches half-answers and slips, then revises. The weakness: a model grading itself is fallible; the strong version grounds the critic in a real check (tests, a schema, a verifier), as in the prompt-engineering "reflexion" lesson.

Independent calls don't depend on each other, so there's no reason to wait. Run them concurrently and the turn finishes in the time of the slowest call, not the sum. Three ~0.8s calls: ~2.4s sequential vs ~0.8s parallel (~3×). The final answer is a normal completion, so you can stream it on top.

Almost nothing changes. You swap run_turn for stream_turn and print the text deltas via a callback; the rest of the loop (run tools, feed results back, repeat) is identical. The fiddly part is reassembling the tool call: OpenAI streams the arguments as JSON fragments you must concatenate by index before you can parse them. That lives in agent/providers.py so the loop stays clean.

Zero client-side rounds, and search did happen. A hosted tool is run by the provider inside the turn, not by your loop. You send one request and get one final answer already grounded in search; there's no tool_use/tool_result round-trip for your code, even though the provider ran search one or more times (the example prints that count). Client-executed and hosted tools are different in kind.

You give up control: the call runs on the provider's side, so Section 7's approval gate can't reach it, and you can't custom-log, validate, or sandbox it. You gain zero plumbing: no schema, no execution, no result round-trip. Real agents mix both: client tools for actions you must govern, hosted tools (web search, code execution) for capability you're happy to rent.

The func is a closure that sends a tools/call request over the protocol (JSON lines over the server's stdin/stdout) and reads the text content blocks back. The loop can't tell the difference; the converted tool has the same name, description, schema, and callable shape as a local one, so tracing and approval gates apply unchanged. That's the payoff of the conversion step: the transport is invisible to the loop.

MCP adds discovery and a wire format: tools/list advertises those same three things from another process (another team, another language, another machine), and tools/call invokes one by name with JSON arguments, with no hand-written glue per tool. What never changes: the model still never runs anything. It only ever sees the menu entry and emits a request. Now even your client doesn't hold the implementation; the server does. (For the protocol's other primitives, like resources, prompts, HTTP transport, and security, see the MCP deep dive.)

ToolExecutor raises ValueError before a single model call, because it refuses any schema that hasn't closed the door on undeclared fields. That's deliberate: a schema this loose would let the model slip in an argument nobody described, and the repo would rather fail loudly at wiring time than silently forward it. seal_schema() is the fix, and as_tools() applies it to every descriptor as it comes off the wire. Note the cost, which is real: if that server accepts a field it never declared and says nothing, sealing rejects a call it would have honored.

Because neither end can verify the other did it. The server has no idea whose model is on the other end of the pipe, which prompt it was given, or whether that prompt came off an injected web page; "my client validated" isn't a fact a server can check. Symmetrically, the client can't audit the server's code. Each side enforces the contract at its own trust boundary, which is what makes them boundaries. Skipping either is how an internal service ends up trusting arguments that originated in text a stranger wrote.