Ever wondered how AI agents actually work behind the scenes? This guide breaks down how agent systems are built as simple graphs – explained in the most beginner-friendly way possible!

Note: This is a super-friendly, step-by-step version of the official PocketFlow Agent documentation. We’ve expanded all the concepts with examples and simplified explanations to make them easier to understand.

Have you been hearing about “LLM agents” everywhere but feel lost in all the technical jargon? You’re not alone! While companies are racing to build increasingly complex AI agents like GitHub Copilot, PerplexityAI, and AutoGPT, most explanations make them sound like rocket science.

Good news: they’re not. In this beginner-friendly guide, you’ll learn:

• The surprisingly simple concept behind all AI agents

• How agents actually make decisions (in plain English!)

• How to build your own simple agent with just a few lines of code

• Why most frameworks overcomplicate what’s actually happening

In this tutorial, we’ll use PocketFlow – a tiny 100-line framework that strips away all the complexity to show you how agents really work under the hood. Unlike other frameworks that hide the important details, PocketFlow lets you see the entire system at once.

Most agent frameworks hide what’s really happening behind complex abstractions that look impressive but confuse beginners. PocketFlow takes a different approach – it’s just 100 lines of code that lets you see exactly how agents work!

Benefits for beginners:

• Crystal clear: No mysterious black boxes or complex abstractions

• See everything: The entire framework fits in one readable file

• Learn fundamentals: Perfect for understanding how agents really operate

• No baggage: No massive dependencies or vendor lock-in

Instead of trying to understand a gigantic framework with thousands of files, PocketFlow gives you the fundamentals so you can build your own understanding from the ground up.

Imagine our agent system like a kitchen:

• Nodes are like different cooking stations (chopping station, cooking station, plating station)

• Flow is like the recipe that tells you which station to go to next

• Shared store is like the big countertop where everyone can see and use the ingredients

In our kitchen (agent system):

1. Each station (Node) has three simple jobs:

   • Prep: Grab what you need from the countertop (like getting ingredients)

   • Exec: Do your special job (like cooking the ingredients)

   • Post: Put your results back on the countertop and tell everyone where to go next (like serving the dish and deciding what to make next)

2. The recipe (Flow) just tells you which station to visit based on decisions:

   • “If the vegetables are chopped, go to the cooking station”

   • “If the meal is cooked, go to the plating station”

Let’s see how this works with our research helper!

An LLM (Large Language Model) agent is basically a smart assistant (like ChatGPT but with the ability to take actions) that can:

1. Think about what to do next

2. Choose from a menu of actions

3. Actually do something in the real world

4. See what happened

5. Think again…

Think of it like having a personal assistant managing your tasks:

1. They review your inbox and calendar to understand the situation

2. They decide what needs attention first (reply to urgent email? schedule a meeting?)

3. They take action (draft a response, book a conference room)

4. They observe the result (did someone reply? was the room available?)

5. They plan the next task based on what happened

Here’s the mind-blowing truth about agents that frameworks overcomplicate:

That’s it! Every agent is just a graph with:

1. A decision node that branches to different actions

2. Action nodes that do specific tasks

3. A finish node that ends the process

4. Edges that connect everything together

5. Loops that bring execution back to the decision node

No complex math, no mysterious algorithms – just nodes and arrows! Everything else is just details. If you dig deeper, you’ll uncover these hidden graphs in overcomplicated frameworks:

• OpenAI Agents: run.py#L119 for a workflow in graph.

• Pydantic Agents: _agent_graph.py#L779 organizes steps in a graph.

• Langchain: agent_iterator.py#L174 demonstrates the loop structure.

• LangGraph: agent.py#L56 for a graph-based approach.

Let’s see how the graph actually works with a simple example.

Imagine we want to build an AI assistant that can search the web and answer questions – similar to tools like Perplexity AI, but much simpler. We want our agent to be able to:

1. Read a question from a user

2. Decide if it needs to search for information

3. Look things up on the web if needed

4. Provide an answer once it has enough information

Let’s break down our agent into individual “stations” that each handle one specific job. Think of these stations like workers on an assembly line – each with their own specific task.

Here’s a simple diagram of our research agent:

In this diagram:

1. DecideAction is our “thinking station” where the agent decides what to do next

2. SearchWeb is our “research station” where the agent looks up information

3. AnswerQuestion is our “response station” where the agent creates the final answer

Imagine you asked our agent: “Who won the 2023 Super Bowl?”

Here’s what would happen step-by-step:

1. DecideAction station:

   • LOOKS AT: Your question and what we know so far (nothing yet)

   • THINKS: “I don’t know who won the 2023 Super Bowl, I need to search”

   • DECIDES: Search for “2023 Super Bowl winner”

   • PASSES TO: SearchWeb station

2. SearchWeb station:

   • LOOKS AT: The search query “2023 Super Bowl winner”

   • DOES: Searches the internet (imagine it finds “The Kansas City Chiefs won”)

   • SAVES: The search results to our shared countertop

   • PASSES TO: Back to DecideAction station

3. DecideAction station (second time):

   • LOOKS AT: Your question and what we know now (search results)

   • THINKS: “Great, now I know the Chiefs won the 2023 Super Bowl”

   • DECIDES: We have enough info to answer

   • PASSES TO: AnswerQuestion station

4. AnswerQuestion station:

   • LOOKS AT: Your question and all our research

   • DOES: Creates a friendly answer using all the information

   • SAVES: The final answer

   • FINISHES: The task is complete!

This is exactly what our code will do – just expressed in programming language.

Let’s build each of these stations one by one and then connect them together!

The DecideAction node is like the “brain” of our agent. Its job is simple:

1. Look at the question and any information we’ve gathered so far

2. Decide whether we need to search for more information or if we can answer now

Let’s build it step by step:

class DecideAction(Node):
    def prep(self, shared):
        # Think of "shared" as a big notebook that everyone can read and write in
        # It's where we store everything our agent knows

        # Look for any previous research we've done (if we haven't searched yet, just note that)
        context = shared.get("context", "No previous search")

        # Get the question we're trying to answer
        question = shared["question"]

        # Return both pieces of information for the next step
        return question, context

First, we created a prep method that gathers information. Think of prep like a chef gathering ingredients before cooking. All it does is look at what we already know (our “context”) and what question we’re trying to answer.

Now, let’s build the “thinking” part:

    def exec(self, inputs):
        # This is where the magic happens - the LLM "thinks" about what to do
        question, context = inputs

        # We ask the LLM to decide what to do ne