GeezerVison

TL;DR: Build a small troubleshooting agent with bounded tools, validated actions, an ordered action-name trace, and automated tests using only the Python standard library.

What you will build

You will build the runtime around an agent rather than a language-model call. A deterministic planner classifies a Python problem, chooses a published troubleshooting playbook, records accepted action names with step numbers, and returns an answer.

The planner is deliberately predictable so you can inspect and test its action sequence without credentials or network access. Later, you can replace only decide() with a provider call while keeping validation, tools, deadlines, the action-name trace, and tests under application control.

You are done when the example returns the network troubleshooting playbook, records the expected action-name sequence, and all 13 published tests pass.

Download the published example

Create a directory and download the exact source and tests published with this guide:

mkdir flypython-agent-loop
cd flypython-agent-loop
curl -O https://flypython.com/examples/agent-loop/agent_loop.py
curl -O https://flypython.com/examples/agent-loop/test_agent_loop.py

You can also inspect agent_loop.py and test_agent_loop.py before downloading them.

The runtime exposes only narrow tools. Before execution, it checks the planner output, the requested tool, and the argument values. It appends the step number and accepted action name to the trace; arguments, timestamps, and tool observations are not part of that trace.

Run it and inspect the trace

Run the example:

python3 agent_loop.py

The final answer is only one part of the result. Inspect the ordered action-name trace to confirm that the planner classified the request, retrieved one bounded playbook, and finished explicitly.

A model can propose an action, but the application still owns the action schema, runtime validation, tool allowlist, deadlines, observations, completion rules, and ordered action-name trace.

Verify success and failure paths

Run the tests from the same directory:

python3 -m unittest -v

Verification command: python3 -m unittest -v. Treat a non-zero result as a failed guide verification rather than continuing to model integration. The suite covers three expected classifications plus a non-Action planner result, malformed action fields, an unknown tool, invalid tool and finish arguments, an exhausted step budget, planner and tool timeouts, and the wall-clock deadline.

The published tools classify text and read a fixed playbook dictionary. This example does not implement mutating tools, an approval workflow, or tests for side-effect review.

A step counter protects against excessive iterations. It is not a timeout; calls that can block also need a wall-clock deadline.

Add a model only where judgment is useful

When ready, replace the deterministic planner with a provider adapter that returns the same validated Action contract. Do not move tool authorization, execution, or completion decisions inside an untrusted prompt.

Use a framework when you need provider adapters, typed parsing, traces, handoffs, state graphs, or durable execution:

• OpenAI Agents SDK for tools, handoffs, guardrails, and tracing.
• Pydantic AI for typed dependencies and model portability.
• LangGraph for explicit state and durable execution.
• Model Context Protocol for reusable tool and data-source boundaries.

Sources

The example uses Python dataclasses and unittest. The framework descriptions link to maintained primary documentation.

Finish the roadmap

You have reached the end of the four-guide sequence when the published example produces the expected three action names and all 13 tests pass. If you extend it, change the request, add one narrow read-only tool, and write its failure tests before connecting a model.

Return to the FlyPython learning roadmap to revisit a boundary, or choose the AI agents playbook to record the expected output.

Verification record

About the author

Organizational byline for FlyPython guides, verification records, and corrections. Editorial standards and contact details →