Quick Start
A chatbot answers once: “Here are three weekend movies.” An agent can go further: search the current catalogue, compare family preferences, calculate total runtime and prepare a shared-watchlist update. But preparing an update is still not the same as completing it.
This Byte slows the agent loop down into five visible moments—goal, tool call, observation, approval proposal and confirmed result. Stepping through them will show exactly when state changes and why the agent must pause before a consequential action.
Byte project
Build a Watchlist Agent that searches verified titles, explains its plan, prepares a shared-profile update and pauses for approval before any write action.
Step through an agent loop and watch state change
An agent does not jump from goal to success. Move one step at a time and notice where evidence, approval and confirmation enter the loop.
Prepare a weekend watchlistNo external action
Start from Basics
| Pattern | What it does | Example |
|---|---|---|
| Chatbot | responds to one message | explains an age rating |
| Copilot | assists a person doing work | drafts a weekend watchlist |
| Agent | chooses and performs bounded steps | searches titles and prepares an update |
| Tool | performs one external operation | search_titles() |
| State | facts needed during this run | goal, steps, tool results |
| Memory | selected context retained across runs | permitted genre preference |
| Approval | human authorisation before consequence | confirm shared-profile update |
An agent loop is goal → choose step → call tool → observe result → stop or continue.
Core Explanation
Create narrow tools with precise contracts:
01def search_titles(language: str, rating: str) -> list[dict]:02"""Return currently available titles matching allowed filters."""03...0405def add_to_watchlist(profile_id: str, title_id: str) -> dict:06"""Add one verified title after an approval token is present."""07...
search_titles → read-only catalogue access
add_to_watchlist → approval token requiredAvoid a general run_anything tool. Narrow tools are easier to authorise, validate, test and audit.
01if proposed_action.type == "update_shared_watchlist":02return {03"status": "approval_required",04"proposal": proposed_action.model_dump(),05}
status: approval_required
external_change: not_completed
next_step: wait_for_humanAfter approval, the agent must inspect the write tool’s result. Preparing an action, asking for approval and completing an action are three different states.
Keep the loop small and make every stopping condition visible:
01for step in range(1, 5):02decision = choose_next_step(state)0304if decision.requires_approval:05return request_approval(decision)0607result = run_allowed_tool(decision.tool, decision.arguments)08state.record(result)0910if result.goal_completed:11return {"status": "completed", "evidence": result}1213return {"status": "stopped", "reason": "Step limit reached"}
step 1 → 3 titles found
step 2 → mv-101 selected
step 3 → approval received
step 4 → watchlist_updated: trueArchitecture / Flow Diagram
The observation step prevents blind execution. Every tool result changes what the agent knows and therefore what it should do next.
Types / Components
| Component | Responsibility | Safety question |
|---|---|---|
| Goal | desired outcome and constraints | Is “done” clear? |
| Planner | selects the next useful step | Can it choose only allowed actions? |
| Tool registry | exposes bounded capabilities | Are read and write tools separate? |
| State | records current-run evidence | Can each result be traced? |
| Memory | retains selected permitted context | Is there a retention rule? |
| Policy | checks identity, scope and limits | Who is allowed to do this? |
| Approval gate | pauses consequential action | Is the proposal specific? |
| Stop rule | ends success, uncertainty or failure | Can repeated loops terminate? |
Stop when the goal is complete, information is missing, permission is absent, a risk boundary is reached, a tool repeatedly fails or the maximum step count is reached.
Tool / Technology Comparison
| Approach | Best for | Trade-off |
|---|---|---|
| Explicit Python loop | narrow workflow and transparent control | you implement state and branching |
| Agent framework | durable state, tracing and complex branches | additional abstraction and dependency |
| Workflow engine | predictable long-running business process | less flexible open-ended reasoning |
| MCP-connected tools | interoperable tool/context exposure | trust and authorisation still remain yours |
| No-code agent builder | rapid prototype with known connectors | fine-grained testing may be limited |
MCP standardises how tools and context are exposed. It does not make a tool safe; authentication, authorisation, validation and approval remain application responsibilities.
Real-World Examples
- Before
- The model invents availability from memory.
- Engineering action
- Call a read-only catalogue tool.
- Evidence after
- The next step uses current tool evidence.
- Before
- The agent is ready to change a family profile.
- Engineering action
- Pause with a precise approval proposal.
- Evidence after
- Nothing changes until a person approves.
- Before
- The same tool times out repeatedly.
- Engineering action
- Stop at the retry and step limit.
- Evidence after
- The user receives an honest failure state.
In a support workflow, an agent may read an approved knowledge base and draft a response. Sending the response or issuing a refund needs a stronger permission boundary and verified tool result.
Imagine Pannunga
A junior coordinator works within a manager boundary
A junior coordinator can collect facts, compare options and prepare a plan. They should not send an official message, make a payment or change access without the correct authority and confirmation.
Simple Tanglish: Agent research panni plan prepare pannalaam. Aana shared profile change, email send, payment madhiri action-ku clear permission and tool confirmation venum.
Use Cases
Design the decision loop and tool contracts
Clear ownershipImplement narrow authorised operations
Clear ownershipSeparate read, write and approval permissions
Clear ownershipTrace steps, failures and execution evidence
Clear ownershipPractical project
Implement search_titles, check_profile_preferences, calculate_total_runtime and prepare_watchlist_update. Give the loop a maximum of four steps. Keep the update as a proposal until the user approves; then verify the tool response before reporting completion.
Log tool name, safe parameters, result status, latency and correlation ID. Never log secrets or unnecessary viewer content.
Key Takeaways
Key takeaways
- Agents choose steps; tools perform bounded operations.
- Every tool needs a clear name, description, parameters and result contract.
- State tracks the current run; memory carries selected context across runs.
- Read and write capabilities should have different permissions.
- Consequential actions need a specific, visible approval proposal.
- Tool evidence—not model wording—proves external completion.
- Retry, step and time limits prevent uncontrolled loops.
- Frameworks and MCP do not remove application safety responsibilities.
Final Thought + Next Path
Useful autonomy comes from clear boundaries, not unlimited capability. Your agent can now choose a tool, observe real evidence and pause before a consequential change. In the final Byte, you will test this behaviour, secure every boundary, package the application and operate it with measurable release evidence.
FAQ + Knowledge Check
Choose an answer, inspect the explanation and explain the idea in your own words.
Is an agent simply a chatbot with a longer prompt? No. An agent can select tools, change state and repeat steps toward a goal.
Is memory the same as state? No. State supports the current run; memory retains selected information across interactions.
Does approval mean the action already happened? No. Approval authorises a tool call; the returned result proves success or failure.
Does MCP guarantee a safe integration? No. It improves interoperability, while your system still owns trust and permissions.
- What proves an external update completed? A) Draft text B) Tool success result C) Model confidence
- Which tool is safer? A) run_anything B) narrow typed tool C) hidden shell
- What ends repeated failure? A) More prompts B) Stop and retry limits C) Memory
- When should write access occur? A) Always B) With authority and approval C) Before validation
- What belongs in logs? A) Secrets B) Safe parameters and status C) Full private conversation
Answers: 1-B, 2-B, 3-B, 4-B, 5-B. Score 4/5 or better before continuing.