What Is an AI Agent? The Plan–Act–Observe Loop

Workflows versus agents, the reasoning-and-acting loop, when an agent is the wrong tool, and building a minimal agent from scratch.

Est. 30 min Updated Suggest a fix
// Part 01 — Mental model

An Agent Chooses What Happens Next

A chatbot answers a message. An agent is a system that pursues a goal through a sequence of decisions and actions. It observes information, chooses an action, calls a tool or asks for more information, observes the result, and decides what to do next. The model may help choose an action, but the application owns the tools, permissions, state, and stopping rules.

Think of a delivery-support assistant asked, "Where is my order?" It might look up the order, inspect the latest status, then explain the result. The model should not invent a delivery status: an order tool supplies the source of truth. If the customer asks for a refund, the system may need an approval step rather than an automatic action.

SystemWho chooses the next step?Good fit
Fixed workflowYour code follows a predetermined sequenceForm validation, invoice generation, known support scripts
AgentA model selects among a bounded set of allowed actionsRequests that need flexible tool selection or iterative search
Unbounded automationThe model can keep acting without explicit limitsNot a safe production design
💡 Note
An agent is not "an LLM with a prompt." It is a controlled software system around a model: tools, state, limits, error handling, and evaluation are part of the design.
// Part 02 — Prerequisites

Tool Calling Is the Bridge from Text to Action

This lesson assumes you know how an LLM requests a tool and how your application validates and executes that request. If you have not built that yet, complete Function and Tool Callingfirst. An agent loop repeats that familiar hand-off: provide context and available tools, receive a proposed action, validate it, execute it, and send the result back into the next model turn.

A model response is untrusted input even when it follows a schema. Validate names and arguments, check the current user's authorization, and return a narrow result. Never treat model-generated text as Python code or let a model invent a URL, SQL query, or tool name that your program executes directly.

  1. Observe the user request and the current application state.
  2. Think: select a permitted action, ask a clarifying question, or finish.
  3. Act through one validated tool call, then record its result.
  4. Observe the result and continue only while a stop condition has not been met.
🎯 Pro Tip
We will first use a small deterministic policy as the "think" step. It makes the control flow runnable without provider credentials. In a real app, a tool-calling LLM proposes the same structured action; the rest of the loop still belongs to your code.
// Part 03 — The loop

Observe, Think, Act — Then Observe Again

Keep the model-facing decision separate from tool execution. A useful decision has an action name and structured arguments, or a final answer. The program checks that decision against an allowlist before executing anything. This separation lets you test the policy, swap model providers, and apply authorization in one predictable place.

agent_loop.py
python
from typing import Any


def lookup_order(order_id: str) -> dict[str, str]:
    orders = {"A104": "Out for delivery", "A105": "Delivered"}
    status = orders.get(order_id)
    if status is None:
        return {"error": "Order not found"}
    return {"order_id": order_id, "status": status}


def think(request: str, observations: list[dict[str, Any]]) -> dict[str, Any]:
    if observations:
        result = observations[-1]["result"]
        return {"type": "final", "text": f"Order status: {result.get('status', result.get('error'))}"}
    order_id = request.rsplit(" ", 1)[-1].strip("?.! ")
    return {"type": "tool", "name": "lookup_order", "args": {"order_id": order_id}}


def run_agent(request: str, max_steps: int = 4) -> str:
    observations: list[dict[str, Any]] = []
    tools = {"lookup_order": lookup_order}
    for _ in range(max_steps):
        decision = think(request, observations)
        if decision["type"] == "final":
            return decision["text"]
        name = decision.get("name")
        if name not in tools:
            raise ValueError("Tool is not allowed")
        result = tools[name](**decision["args"])
        observations.append({"tool": name, "result": result})
    raise RuntimeError("Agent reached its step limit")


print(run_agent("Check order A104"))

Run it with python agent_loop.py. The first decision requests lookup_order; the program executes that function, adds its result to observations, and calls the decision function again. The second decision returns a final answer. The loop is deliberately tiny, but its boundaries are the same ones a model-driven loop needs.

// Part 04 — Tools

Treat Actions as Typed, Narrow Capabilities

A tool should do one job and accept only the fields needed for that job. For example, a read-only order lookup should take an order identifier, not arbitrary SQL or a complete database connection. The tool layer must still check that the signed-in customer owns that order; hiding records in a prompt is not authorization.

tool_boundary.py
python
from typing import Any


def execute_tool(
    name: str,
    args: dict[str, Any],
    user_id: str,
    tools: dict[str, Any],
) -> dict[str, Any]:
    if name not in tools:
        return {"ok": False, "error": "Unknown tool"}
    if set(args) != {"order_id"}:
        return {"ok": False, "error": "Invalid arguments"}

    order_id = args["order_id"]
    if not isinstance(order_id, str) or not order_id:
        return {"ok": False, "error": "Invalid order identifier"}

    # The real database query must include both order_id and user_id.
    result = tools[name](order_id=order_id, user_id=user_id)
    return {"ok": True, "result": result}


def lookup_order(order_id: str, user_id: str) -> dict[str, str]:
    return {"order_id": order_id, "status": "Out for delivery"}

In a real application, the lookup function would scope its query by user_id as shown in the comment. Validate types and expected keys before the call, then normalise errors into a result the next model turn can understand. Do not expose secrets, full database rows, or internal exception details in tool results.

⚠️ Important
Model choice is not permission. Check identity and authorization in server-side tool code immediately before each sensitive operation, and require a human for consequential or irreversible actions.
// Part 05 — Stopping

Bound the Loop Before Connecting a Model

Agents can repeat a tool call, misread a result, or keep asking for work. A production loop needs several exits: a clear final-answer signal, a maximum number of steps, a request deadline, per-tool timeouts, and a graceful path for failures. A step cap is a circuit breaker, not proof that the task is complete. If the cap is reached, tell the user the task stopped and preserve enough trace data to investigate.

bounded_runner.py
python
from time import monotonic


def run_bounded(request: str, decide, execute, max_steps: int = 6, timeout: float = 20.0):
    started = monotonic()
    observations = []

    for step in range(max_steps):
        if monotonic() - started > timeout:
            return {"status": "timed_out", "steps": step}
        decision = decide(request, observations)
        if decision["type"] == "final":
            return {"status": "complete", "answer": decision["text"], "steps": step}
        if decision["type"] != "tool":
            return {"status": "needs_clarification", "steps": step}
        try:
            result = execute(decision["name"], decision["args"])
        except TimeoutError:
            result = {"error": "Tool timed out"}
        except ValueError:
            result = {"error": "Tool request was invalid"}
        observations.append({"action": decision, "result": result})

    return {"status": "step_limit", "steps": max_steps}

The sample gives the caller a structured status rather than silently pretending the last tool output is a completed task. A web service should also enforce a request-level deadline, because a blocking tool might not return in time for the loop to check its clock. Apply rate limits and concurrency limits outside the agent as well.

// Part 06 — Choose the right shape

Do Not Use an Agent for Every Task

If the steps are known and predictable, write a workflow. It is cheaper to test and easier to explain. Use an agent when the request genuinely requires flexible choice among tools or iterative gathering of evidence. Many products use a hybrid: deterministic code handles permissions and business rules while an agent chooses which read-only search or retrieval step to try.

QuestionPrefer a fixed workflowAn agent may help
Are the steps known?Yes; inputs map to the same sequenceNo; the next useful search depends on results
What is the impact of an error?High and deterministic controls are neededLow-risk, reversible exploration with oversight
Can a normal function solve it?A direct rule or query is sufficientTool choice needs flexible interpretation
Can you verify completion?A clear programmatic condition existsEvidence can be checked after each action
📌 Real World Example
For a UPI dispute, a fixed workflow can collect a transaction reference and open a case reliably. An agent might summarize the customer's description or search approved help articles, but it should not independently transfer money or close a dispute based on its own summary.
// Part 07 — Production

Observe Decisions, Not Just Final Answers

Keep a trace of the request identifier, selected tool name, validated argument summary, duration, result category, and stop reason. Avoid logging access tokens, raw payment details, or unnecessary personal data. A useful trace lets an engineer answer: Did the agent choose the wrong tool, did the tool fail, or did the model fail to understand the observation?

  1. Write scenarios for successful completion, missing data, tool errors, and a request that needs clarification.
  2. Assert tool calls and arguments as well as the final response.
  3. Measure steps, latency, failure rate, and the number of tasks that need a person.
  4. Review traces with personal data minimised and access controlled.

Before giving the loop write access, simulate actions and inspect what it would do. Then add narrow permissions, idempotency for retryable operations, approval gates, and a way to stop a run. A model can propose a correct action twice after a timeout; the tool must be designed for that possibility.

// Part 08 — Pitfalls

Common Mistakes

Calling every LLM workflow an agent

Why: The label hides whether the model actually chooses actions.

Fix: Use a deterministic workflow when the sequence is known; use agent loops only for flexible decisions.

Executing arbitrary model output

Why: Text that looks like a tool call is still untrusted input.

Fix: Parse a typed action, allowlist the tool, validate arguments, and authorize in the tool layer.

Letting the loop run until it feels done

Why: The model can repeat actions or fail to recognise completion.

Fix: Add step and time limits plus explicit completion and escalation states.

Giving a demo agent broad write access

Why: A short happy-path demo does not cover mistakes or prompt injection.

Fix: Start read-only, scope data to the user, simulate changes, and gate consequential actions.

// Part 09 — Practice

Build a Read-Only Delivery Support Agent

Practice

A bounded observe–think–act loop

  1. Run the local loop and trace each decision, tool call, result, and final answer.
  2. Add a second read-only tool that returns the delivery estimate for an order.
  3. Reject an unknown tool and malformed arguments without calling either function.
  4. Add a maximum-step test in which the decision function never returns final.
  5. Write a scenario for an order that is not found and make the agent ask for clarification instead of guessing.

Hint: Keep the mock tool data in memory for this exercise. In an application, enforce the customer-to-order relationship in the database query, not in the model prompt.

🎯 Key Takeaways

  • ✓An agent is an application that repeatedly observes, selects a bounded action, and uses the result to pursue a goal.
  • ✓Tool calling connects model decisions to functions; validate and authorize every call in application code.
  • ✓Start with plain Python to understand the loop before introducing orchestration frameworks.
  • ✓Use a fixed workflow when the steps are predictable; agents add flexibility and failure modes.
  • ✓Bound execution with step limits, deadlines, tool timeouts, explicit stop reasons, and escalation paths.
  • ✓Trace decisions and tool outcomes, minimise sensitive logs, and test failure paths before enabling writes.

Next

What comes next

The loop needs more than a request string. Next, model its state, conversation context, and carefully scoped long-term memory.

Lesson 02 · Agent State and Memory →

HELP US IMPROVE

How was this lesson?

Your note is shared with the Chaduvuko team for review. Please don’t include personal or sensitive information.

Choose your feedback

Spotted a mistake or something unclear? Suggest a fix on GitHub or email us. Select the text first and it is quoted for you.

Share

Discussion

0

Have a better approach? Found something outdated? Share it — your knowledge helps everyone learning here.

Continue with GitHub
Loading...