Agentic Coding with PocketFlow

Build LLM systems using PocketFlow's 100-line minimalist framework. This skill guides you through collaborative development where humans design high-level system flows and AI agents implement the detailed code.

Overview

PocketFlow models LLM workflows as **Graph + Shared Store**: Nodes handle simple tasks, Flows connect nodes through labeled edges (actions), and a Shared Store enables communication between nodes.

**Core principle**: Humans understand requirements and design flows; AI agents implement nodes, utilities, and handle reliability.

Development Steps

Follow these steps in order. Always start simple and iterate frequently.

1. Requirements Analysis

**Human-led, AI supports**

Clarify project requirements from the user's perspective (problem-focused, not feature lists)

Evaluate if an AI system fits:

- ✅ Good for: Routine tasks with common sense (form filling, email replies), creative tasks with defined inputs (slides, SQL)

- ❌ Not good for: Ambiguous problems requiring complex decisions (business strategy)

Balance complexity vs. impact: deliver highest-value features with minimal complexity first

**AI agent tasks:**

Ask clarifying questions about user goals and constraints

Suggest applicable AI system patterns

Identify potential limitations or risks

2. Flow Design

**Collaborative design phase**

Outline how the AI system orchestrates nodes at a high level

Identify design patterns: Map Reduce, Agent, RAG, Workflow, Multi-Agent

For each node, write a one-line description of what it does

Document the flow in a Mermaid diagram

**Pattern-specific details:**

**Map Reduce**: Specify how to split (map) and how to combine (reduce)

**Agent**: Define inputs (context) and possible actions

**RAG**: Specify what to embed; note offline (indexing) and online (retrieval) workflows

**AI agent tasks:**

Generate Mermaid flowchart from human's high-level description

Suggest pattern improvements or alternatives

Fill in low-level node details within the specified flow

**Example Mermaid diagram:**

```mermaid

flowchart LR

start[Start] --> batch[Batch]

batch --> check[Check]

check -->|OK| process

check -->|Error| fix[Fix]

fix --> check

subgraph process[Process]

step1[Step 1] --> step2[Step 2]

end

process --> endNode[End]

```

**Critical rule**: If humans can't specify the flow, AI agents can't automate it. Manually solve example inputs first to develop intuition.

3. Utilities Design & Implementation

**Collaborative implementation**

Identify utility functions needed based on Flow Design

Think of utilities as the "body" for the AI "brain":

- Reading inputs (Slack messages, emails)

- Writing outputs (reports, emails)

- Using external tools (LLMs, web search)

**Note**: LLM-based tasks (summarizing, sentiment analysis) are NOT utilities—they're core functions

**For each utility:**

Implement the function

Write a simple test with `if __name__ == "__main__"`

Document: name, file path, input/output types, necessity

**Example utility:**

```python

utils/call_llm.py

from openai import OpenAI

def call_llm(prompt):

client = OpenAI(api_key="YOUR_API_KEY_HERE")

r = client.chat.completions.create(

model="gpt-4o",

messages=[{"role": "user", "content": prompt}]

)

return r.choices[0].message.content

if __name__ == "__main__":

prompt = "What is the meaning of life?"

print(call_llm(prompt))

```

**Important**: Avoid exception handling in utilities. Let Node's built-in retry mechanism handle failures.

**AI agent tasks:**

Implement utility functions from specifications

Write test cases for each utility

Document input/output contracts

4. Data Design

**AI-led, human verifies**

Design the shared store (data contract) that all nodes use to communicate

Use in-memory dictionary for simple systems

Use database for complex systems or when persistence is required

Follow DRY principle: use references or foreign keys

**Example shared store:**

```python

shared = {

"user": {

"id": "user123",

"context": {

"weather": {"temp": 72, "condition": "sunny"},

"location": "San Francisco"

}

"results": {}

}

```

**AI agent tasks:**

Design data schema based on flow requirements

Propose nested structures for related data

Document all keys and expected value types

5. Node Design

**AI-led, human reviews**

For each Node, specify:

**Type**: Regular, Batch, or Async

**prep()**: What data to read from shared store

**exec()**: Which utility function to call (avoid exception handling—let Node retry mechanism handle it)

**post()**: What data to write to shared store and which action to return

**Example node specification:**

`type`: Regular

`prep`: Read "text" from shared store

`exec`: Call embedding utility function

`post`: Write "embedding" to shared store, return "default" action

**AI agent tasks:**

Design node logic based on flow diagram

Map utility functions to exec() methods

Define data read/write patterns

6. Implementation

**AI-led, human provides feedback**

Now implement nodes and flows based on the design.

**Principles:**

**Keep it simple!** Avoid complex features and excessive type checking

**Fail fast**: Leverage built-in Node retry/fallback mechanisms

Add logging throughout for debugging

**File structure:**

```

my_project/

├── main.py # Entry point

├── nodes.py # Node definitions

├── flow.py # Flow creation functions

├── utils/ # Utility functions

│ ├── __init__.py

│ ├── call_llm.py

│ └── search_web.py

├── requirements.txt

└── docs/

└── design.md # High-level design documentation

```

**Example nodes.py:**

```python

from pocketflow import Node

from utils.call_llm import call_llm

class GetQuestionNode(Node):

def exec(self, _):

user_question = input("Enter your question: ")

return user_question

def post(self, shared, prep_res, exec_res):

shared["question"] = exec_res

return "default"

class AnswerNode(Node):

def prep(self, shared):

return shared["question"]

def exec(self, question):

return call_llm(question)

def post(self, shared, prep_res, exec_res):

shared["answer"] = exec_res

```

**Example flow.py:**

```python

from pocketflow import Flow

from nodes import GetQuestionNode, AnswerNode

def create_qa_flow():

get_question_node = GetQuestionNode()

answer_node = AnswerNode()

get_question_node >> answer_node

return Flow(start=get_question_node)

```

**AI agent tasks:**

Implement all nodes according to specifications

Create flow connection logic

Write main.py entry point

Add comprehensive logging

7. Optimization

**Collaborative iteration**

**Initial evaluation**: Use human intuition for quick assessment

**Flow redesign**: Break down tasks further, introduce agentic decisions, better manage contexts

**Micro-optimizations** (if flow is solid):

- Prompt engineering: Clear, specific instructions with examples

- In-Context Learning: Provide robust examples for difficult-to-specify tasks

**Expect hundreds of iterations through Steps 3-6!**

**AI agent tasks:**

Propose flow improvements based on results

Refine prompts and examples

Suggest alternative patterns

8. Reliability

**AI-led, human validates**

**Node retries**: Add checks in exec() to validate outputs; increase `max_retries` and `wait` times

**Logging and visualization**: Maintain logs of all attempts; visualize node results

**Self-evaluation**: Add LLM-powered evaluation nodes to review uncertain outputs

**AI agent tasks:**

Implement output validation logic

Add retry strategies for critical nodes

Create self-evaluation nodes

Write test cases for edge cases

Core Abstractions Reference

**Node**: Handles simple LLM tasks with prep/exec/post lifecycle

**Flow**: Connects nodes through labeled edges (actions)

**Shared Store**: Enables communication between nodes

**Batch**: Processes data-intensive tasks

**Async**: Waits for asynchronous operations

**Parallel**: Handles I/O-bound tasks concurrently

Design Patterns Available

**Agent**: Autonomous decision-making

**Workflow**: Chain multiple tasks into pipelines

**RAG**: Retrieval-augmented generation (offline indexing + online retrieval)

**Map Reduce**: Split-process-combine for data tasks

**Structured Output**: Consistent output formatting

**Multi-Agent**: Coordinate multiple agents

Best Practices

1. **Design utilities before flow** if interfacing with legacy systems is the bottleneck

2. **No exception handling in utilities** called from Node.exec()—let Node retry mechanism handle it

3. **Keep docs/design.md high-level and no-code**—focus on what, not how

4. **One Python file per API call** in utils/ directory

5. **Include main() test function** in each utility file

6. **Start simple, iterate frequently**—avoid premature optimization

7. **Fail fast with Node retries**—quickly identify weak points

Important Constraints

PocketFlow has ZERO dependencies—no vendor lock-in

Framework is ~100 lines of code (check `pocketflow/__init__.py`)

Do not provide built-in utilities; implement project-specific ones

Human must be able to specify the flow before AI can automate it

When to Use This Skill

Building LLM systems with task decomposition

Implementing agent-based workflows

Creating RAG pipelines

Designing multi-step AI applications

Prototyping complex LLM architectures

Collaborative AI + human system design

Agentic Coding with PocketFlow

Agentic Coding with PocketFlow

Overview

Development Steps

1. Requirements Analysis

2. Flow Design

3. Utilities Design & Implementation

utils/call_llm.py

4. Data Design

5. Node Design

6. Implementation

7. Optimization

8. Reliability

Core Abstractions Reference

Design Patterns Available

Best Practices

Important Constraints

When to Use This Skill

Reviews (0)