Edit this page

Pocket Flow - 100-line LLM Framework

PocketFlow: The 100-Line LLM Framework That Makes Agents Actually Understandable

Hook with a Story

Picture this: You’re at a tech meetup, and someone starts explaining their AI agent architecture. They mention LangChain’s 405K lines of code, CrewAI’s complex abstractions, and AutoGen’s mysterious black boxes. Your eyes glaze over as they dive into the technical jargon.

Then someone else steps up and says: “What if I told you that every AI agent is just a simple graph with 100 lines of code?”

That person would be talking about PocketFlow - the minimalist LLM framework that strips away all the complexity to reveal the beautiful simplicity underneath. No more wondering what’s happening behind the scenes. No more vendor lock-in. Just pure, transparent agent logic you can actually understand.

Lay Out the Roadmap

Here’s our journey to mastering PocketFlow and understanding how LLM agents really work:

What you’ll learn:

  1. Why agents are just simple graphs (not rocket science!)
  2. The three building blocks that power everything
  3. How to build a research agent in minutes
  4. Why PocketFlow beats massive frameworks
  5. How to apply this to real projects

The Big Secret: Agents Are Just Simple Graphs!

Wait, That’s It? Really?

Yes! Here’s the mind-blowing truth that complex frameworks try to hide:

Every AI agent, no matter how complex it seems, follows this pattern:

  1. Think about the current situation
  2. Decide what action to take next
  3. Do the chosen action
  4. Loop back to thinking with new information

💡 Pro Tip: Even the most sophisticated frameworks like OpenAI Agents, LangChain, and LangGraph follow this exact pattern under the hood. PocketFlow just makes it visible!

Your Turn: Spot the Pattern

Think about how you solve problems. Let’s say someone asks: “What’s the weather like in Tokyo?”

Your mental process:

  1. 🤔 “I need current weather info”
  2. 🔀 “Should I check my phone or ask someone?”
  3. 📱 “I’ll check a weather app”
  4. 🤔 “Got the info, now I can answer”
  5. 💬 “It’s 22°C and sunny in Tokyo”

See? You’re already thinking like an agent!

Dive into Bite-Sized Chunks

Building Block #1: Nodes (The Workers)

Think of Nodes as specialized workers in a kitchen:

class SearchWebNode(Node):
    def prep(self, shared):
        # 🥄 Grab ingredients (get search query)
        return shared["search_query"]
    
    def exec(self, search_query):
        # 👨‍🍳 Do the actual work (search the web)
        results = google_search(search_query)
        return results
    
    def post(self, shared, prep_res, exec_res):
        # 🍽️ Serve the dish (save results, decide what's next)
        shared["search_results"] = exec_res
        return "analyze_results"

Every node has three simple jobs:

  • Prep: Gather what you need from the shared workspace
  • Exec: Do your specialized task
  • Post: Save your results and decide where to go next

Your Turn: Design a Node

Do this! Imagine you’re building a “TranslateText” node. What would each method do?

  1. Prep: What information would you need?
  2. Exec: What’s the main task?
  3. Post: Where should the flow go next?

Think about it before reading on…

Quick Recap: Nodes are like specialized workers that prep, execute, and hand off to the next worker.

Building Block #2: Flow (The Recipe)

The Flow is like a recipe that tells workers where to go next:

# Connect the nodes like a flowchart
search_node - "analyze" >> analyze_node
search_node - "answer" >> answer_node
analyze_node - "search_more" >> search_node
analyze_node - "answer" >> answer_node

# Create the flow starting with search
flow = Flow(start=search_node)

Flow connections are simple:

  • node1 - "action" >> node2 means “if node1 returns ‘action’, go to node2”
  • It’s just like following arrows in a flowchart!

Your Turn: Connect the Dots

Do this! Draw arrows connecting these nodes:

  1. StartNode → (if “needs_info”) → SearchNode
  2. StartNode → (if “can_answer”) → AnswerNode
  3. SearchNode → (always) → StartNode

Quick Recap: Flow is just a simple recipe that says “if this, then go there.”

Building Block #3: Shared Store (The Kitchen Counter)

The Shared Store is like a big kitchen counter where everyone can leave notes and ingredients:

# Everyone can read and write to this shared space
shared = {
    "question": "What's the capital of France?",
    "search_results": "Paris is the capital...",
    "answer": "The capital of France is Paris."
}

It’s that simple:

  • All nodes can read from and write to this shared dictionary
  • It’s how information flows between different workers
  • Think of it as everyone’s shared notebook

Your Turn: Design Your Shared Store

Do this! If you were building a “Recipe Generator” agent, what would you put in the shared store?

Hint: Think about what information different nodes would need to share…

Quick Recap: Shared store is just a dictionary where all nodes can read and write information.

Graph Patterns: The Secret Sauce Behind Every Agent

Wait, There Are Patterns?

Absolutely! Just like design patterns in software, AI agents follow predictable graph patterns. Once you know these patterns, you can build any agent by mixing and matching them.

Think of it like LEGO blocks: Each pattern solves a specific problem, and you combine them to build whatever you need!

🔄 Pattern #1: The Simple Loop (Most Common)

When to use: When your agent needs to keep working until it finds the right answer.

Perfect for: Research agents, problem-solving bots, iterative refinement

Real example: "Keep searching until you have enough info to answer the question."

Your Turn: What would you use this pattern for? Customer support? Content research? Data analysis?

🌊 Pattern #2: The Pipeline (Step-by-Step)

When to use: When you have a clear sequence of steps that must happen in order.

Perfect for: Content generation, data processing, multi-stage analysis

Real example: "Write a blog post: research → outline → draft → edit → publish."

Your Turn: Think of a process you do manually. How would you break it into pipeline steps?

🌲 Pattern #3: The Decision Tree (Choose Your Path)

When to use: When different inputs need completely different handling.

Perfect for: Customer routing, content classification, conditional workflows

Real example: "Route customer messages to the right specialist bot."

Your Turn: What decisions does your business make repeatedly? Could a bot handle them?

🔄 Pattern #4: The Feedback Loop (Self-Improving)

When to use: When your agent should learn from its mistakes and get better.

Perfect for: Quality control, A/B testing, performance optimization

Real example: "Try different email subject lines, measure open rates, keep improving."

Your Turn: What do you currently do manually that could self-optimize? Marketing? Pricing? Scheduling?

⚡ Pattern #5: The Parallel Split (Do Multiple Things)

When to use: When you need to do several independent tasks at the same time.

Perfect for: Data gathering, multi-source research, parallel processing

Real example: "Research a company by simultaneously checking news, financials, and social media."

Your Turn: What research do you do that involves checking multiple sources? Market research? Due diligence?

🎛️ Pattern #6: The State Machine (Remember Context)

When to use: When your agent needs to remember where it is in a complex process.

Perfect for: Multi-step workflows, conversation bots, guided processes

Real example: "Guide users through a complex signup process, remembering what they've already completed."

Your Turn: What multi-step processes do your users go through? Onboarding? Purchasing? Support tickets?

🔄 Pattern #7: The Batch Processing (Handle Lots of Data)

When to use: When you need to process large amounts of data efficiently.

Perfect for: Document analysis, bulk operations, data transformation

Real example: "Process 1000 customer reviews by breaking them into batches of 50 for sentiment analysis."

Your Turn: What bulk operations could benefit from batching? Email campaigns? Image processing? Report generation?

⏰ Pattern #8: The Async Wait (Handle Time-Sensitive Tasks)

When to use: When you need to wait for external systems or time-based events.

Perfect for: API rate limits, scheduled tasks, webhook responses

Real example: "Submit document for processing, wait for OCR service to complete, then continue with text analysis."

Your Turn: What async operations do you deal with? Payment processing? File uploads? Third-party APIs?

🌐 Pattern #9: The Parallel I/O (Multiple External Calls)

When to use: When you need to call multiple external services simultaneously.

Perfect for: API aggregation, data enrichment, cross-platform integration

Real example: "Enrich user profile by simultaneously calling LinkedIn API, GitHub API, and Twitter API."

Your Turn: What data do you gather from multiple sources? User verification? Market data? Social media analytics?

Design Patterns: The Power Combinations

Beyond Basic Patterns: Real-World Architectures

Now that you know the building blocks, let’s see how they combine into design patterns that solve real business problems:

🤖 Design Pattern #1: The Autonomous Agent

What it is: An agent that makes its own decisions about what to do next.

How it works: Combines Decision Tree + Simple Loop + State Machine

Real example: "Customer service bot that decides whether to search knowledge base, escalate to human, or provide direct answer."

Your Turn: What decisions could your business automate? Lead qualification? Content moderation? Inventory management?

⛓️ Design Pattern #2: The Workflow Pipeline

What it is: A sequence of specialized nodes that each add value to the data.

How it works: Linear Pipeline + Error Handling + Quality Gates

Real example: "Content publishing: Draft → Fact-check → Edit → SEO optimize → Publish → Promote."

Your Turn: What multi-step processes could benefit from automation? Onboarding? Order fulfillment? Quality assurance?

🎯 Design Pattern #3: The RAG System (Retrieval-Augmented Generation)

What it is: Combines information retrieval with AI generation for accurate, sourced responses.

How it works: Parallel Split + Document Search + Context Integration + Generation

Real example: "Corporate chatbot that searches internal docs, finds relevant policies, and generates accurate answers with citations."

Your Turn: What knowledge bases could power better customer service? Product manuals? FAQ databases? Company policies?

🗺️ Design Pattern #4: The Map-Reduce System

What it is: Breaks large tasks into smaller parallel pieces, then combines results.

How it works: Parallel Split + Batch Processing + Result Aggregation

Real example: "Analyze 10,000 customer reviews by processing 100 at a time, then aggregate sentiment scores."

Your Turn: What large-scale analysis could benefit from parallel processing? Log analysis? Market research? Performance monitoring?

📋 Design Pattern #5: The Structured Output System

What it is: Ensures AI generates consistent, validated data structures.

How it works: Input Validation + Template Processing + Output Formatting + Quality Check

Real example: "Extract structured data from job postings: title, salary, requirements, location → JSON format for database."

Your Turn: What unstructured data needs consistent formatting? Resumes? Contracts? Survey responses?

👥 Design Pattern #6: The Multi-Agent Coordination

What it is: Multiple specialized agents working together on complex problems.

How it works: Hub & Spoke + State Machine + Message Passing + Result Coordination

Real example: "Marketing campaign creation: Research agent finds trends, Writing agent creates copy, Design agent makes visuals."

Your Turn: What complex projects need multiple types of expertise? Product launches? Content creation? Event planning?

Your Turn: Identify the Right Pattern

Do this! Match these business needs with design patterns:

  1. Process 50,000 customer service tickets for insights
    • Pattern: __________
  2. Answer questions about company policies using internal docs
    • Pattern: __________
  3. Create social media campaigns from product descriptions
    • Pattern: __________
  4. Monitor website performance and auto-optimize
    • Pattern: __________

Pro Tip: Most real applications combine multiple patterns! Start with one pattern, prove it works, then add complexity.

🎯 Quiz Answers: Design Pattern Mastery

Business Needs to Design Pattern Answers:

1. Process 50,000 customer service tickets for insights
   - Pattern: Map-Reduce System - Break large dataset into parallel chunks for processing, then aggregate insights

2. Answer questions about company policies using internal docs
   - Pattern: RAG System - Retrieval-Augmented Generation to search docs and generate accurate, cited answers

3. Create social media campaigns from product descriptions
   - Pattern: Multi-Agent Coordination - Research agent analyzes market, Writing agent creates copy, Design agent makes visuals

4. Monitor website performance and auto-optimize
   - Pattern: Autonomous Agent - Makes decisions about what metrics to check and optimizations to apply

How did you score? 🎯

  • 4/4 correct: Pattern Master! You understand how to architect real-world agent solutions
  • 3/4 correct: Pattern Pro! You're ready to build production agents
  • 2/4 correct: Pattern Apprentice! Review the design patterns and try again
  • 1/4 correct: Pattern Beginner! Focus on understanding when to use each pattern

Quick Recap: These design patterns are battle-tested solutions to common business problems. Pick the right combination for your use case!

Let’s Build a Super Simple Research Agent

The Goal: A Research Agent in 100 Lines

Here’s the complete code for a simple research agent using PocketFlow:

# Import the PocketFlow framework
from pocketflow import *

# Define the nodes
class InputNode(Node):
    def exec(self, question):
        print(f"🔍 Searching for: {question}")
        return "search_results"

class AnalyzeNode(Node):
    def exec(self, search_results):
        print(f"📊 Analyzing: {search_results}")
        return "answer"

class AnswerNode(Node):
    def exec(self, answer):
        print(f"✅ Answering: {answer}")
        return "done"

# Define the flow
search_node = InputNode("What's the capital of France?")
analyze_node = AnalyzeNode()
answer_node = AnswerNode()

search_node - "search_results" >> analyze_node
analyze_node - "answer" >> answer_node

flow = Flow(start=search_node)

# Run the agent
flow.run()

How It Works

  1. InputNode: Starts the flow by taking a question.
  2. SearchNode: Pretends to search the web (replace with real search code).
  3. AnalyzeNode: Analyzes the search results.
  4. AnswerNode: Gives the final answer.

Your Turn: Modify and Run

Do this! Change the question in InputNode to something else. Maybe “What’s the weather today?” or “Who won the World Series in 2020?”

Hint: You can also add more nodes for a more complex agent!

References

Here are the key resources and inspirations that shaped this exploration of PocketFlow and LLM graph frameworks:

Core Framework Resources:

Graph Theory & Agent Patterns:

LLM Framework Landscape:

Practical Implementation:

Community & Learning:

Tools & Extensions:

Have you built something cool with PocketFlow? Share your experience in the comments below! 🚀