Building Python Agents: From Intuition to Evidence

Meta description: Learn agentic engineering in Python: bounded tasks, two loops, evidence ladder, RECAP review, and acceptance checkpoints for safe AI-generated code.

Tags: agentic engineering, Python, AI coding agents, code review, developer workflow

Featured image: abstract, friendly illustration style showing two linked loops: one loop with a coding agent editing files, the other with a human reviewer and a checklist, no real people, no logos, no text.

A Real Python tutorial now outlines agentic engineering for Python developers who use AI coding agents in shared codebases and need a repeatable way to decide whether generated code should be kept. The guide frames the method as a disciplined approach to delegating bounded software tasks to AI coding agents while the human retains control over intent, constraints, review, and release decisions. Its practical value is a workflow that turns a fast agent-generated patch into a change backed by tests, type hints, checks, and a human acceptance step.

The Two Loops That Make the Workflow Work

The central idea is that two different processes are connected. The first is the agent execution loop. In this loop, the agent inspects the repository, plans work, edits files, runs tools, observes results, and repeats until it meets a stopping condition. The second is the human acceptance loop. In this loop, the developer reviews the candidate diff, decides whether the change belongs in the codebase, and either approves it, asks for clarification, or sends the agent back to run again.

The tutorial contrasts this with vibe coding. Vibe coding asks whether a result looks plausible. Agentic engineering asks what evidence supports the change. That difference matters in shared repositories and production-bound work, where plausible code can still hide broken contracts, missing edge cases, or architectural drift.

The guide also says agentic engineering is not a wholly new invention. It builds on practices Python developers already use: writing tests, adding type hints, refactoring for simplicity, and reviewing changes before merging them. The new part is the combination: using those practices to produce checkable evidence before accepting an agent's patch.

A Step-by-Step Agentic Engineering Review

A typical workflow can be broken into these steps:

1. Define intent. Start with a planning pass in Claude Code's plan mode or OpenCode's plan agent. Treating a large language model, or LLM, or an agent as a brainstorming tool can shorten the time needed to shape a feature or project goal. Saving the plan artifact also helps later auditing and review.

1. Bound the task and choose a stopping condition. Tell the agent what counts as done. A common example is: the task is complete only when the implementation passes the tests in tests/.

1. Run the agent execution loop. With intent as context, the agent inspects available files and directories, does any additional planning needed, writes code, and runs automated checks such as linting, unit tests, and type checking. If a check fails, the agent returns to planning and iterates.

1. Pause at a completed diff. Do not treat every agent action as a separate manual review checkpoint. Automated checks are what keep the agent execution loop fast. Human review remains the acceptance step, and it happens at meaningful checkpoints, such as a finished candidate diff.

1. Apply the RECAP review. Check the diff by role, edges, contracts, assumptions, and proof. Ask what responsibility the new code owns, whether boundary and error cases are covered, whether inputs and outputs match existing expectations, which assumptions the change depends on, and what tests or other artifacts prove the result.

1. Accept or re-run. If the diff does not earn approval, clarify the intent and let the agent run another execution loop. If it earns approval, the change can move through continuous integration, often shortened to CI, with evidence backing it.

Evidence, RECAP, and Workflow Types

The tutorial names two review aids. The Engineering Evidence Ladder identifies the evidence already gathered and the evidence still needed. The RECAP method gives reviewers a standard set of questions: role, edges, contracts, assumptions, and proof. Together, they make the acceptance loop repeatable instead of relying on a vague sense that the code looks correct.

Automated checks produce repeatable evidence, but accepting the diff stays the human decision. As agents take on bigger tasks and produce larger diffs, the review focus shifts. Instead of reading every line of code, the reviewer weighs the evidence behind the change: behavior, boundaries, tests, architecture fit, and risk.

The terminology around coding with AI is still changing quickly. As of now, the guide distinguishes several related terms:

Real Python also links to an interactive quiz titled Agentic Engineering in Python: From Vibes to Evidence, as well as a free PDF cheat sheet covering the Engineering Evidence Ladder, the RECAP review checklist, and the two loops used to turn agent-generated Python into code backed by evidence. The full article is available at https://realpython.com/agentic-engineering/.

Common mistakes

• Accepting a patch because it looks plausible rather than because it has checkable evidence.
• Giving an agent an open-ended task with no stopping condition, such as a passing test suite or a defined set of checks.
• Running manual review after every small agent action, which slows the workflow and dilutes attention from the final diff.
• Treating linting, unit tests, or type checking as the final judgment instead of as evidence that still needs human acceptance.
• Skipping the plan artifact, which removes context for later auditing and review.
• Failing to clarify intent after a rejected diff, which sends the agent into another execution loop with the same ambiguity.
• Reviewing larger agent-generated diffs only by reading code, without checking behavior, boundaries, tests, architecture fit, and risk.