update doc

README.md

@@ -6,7 +6,7 @@
 [![Docs](https://img.shields.io/badge/docs-latest-blue)](https://the-pocket.github.io/PocketFlow/)
 
 <div align="center">
-  <img src="./assets/minillmflow.jpg" width="400"/>
+  <img src="./assets/meme.jpg" width="400"/>
 </div>
 
 <br>
@@ -67,7 +67,7 @@ From there, it’s easy to implement popular design patterns like ([Multi-](http
 
 <br>
 <div align="center">
-  <img src="./assets/paradigm.png" width="600"/>
+  <img src="./assets/design.png" width="600"/>
 </div>
 <br>
 

docs/agent.md

@@ -7,10 +7,24 @@ nav_order: 6
 
 # Agent
 
-For many tasks, we need agents that take dynamic and recursive actions based on the inputs they receive.
+Agent is a powerful design pattern, where node can take dynamic actions based on the context it receives.
-You can create these agents as **Nodes** connected by *Actions* in a directed graph using [Flow](./flow.md).
+To express an agent, create a Node (the agent) with [branching](./flow.md) to other nodes (Actions).
 
 
+### Best Practice
+
+The core of build **performant** and **reliable** agents boils down to:
+
+1. **Context Management**  
+   Provide *clear, relevant context* so agents can understand the problem. 
+   E.g., Rather than dumping an entire chat history or entire files, use a [Workflow](./decomp.md) that filters out and includes only the most relevant information.
+
+2. **Action Space**  
+   Define *a well-structured, unambiguous, and easy-to-use* set of actions. 
+   For instance, avoid creating overlapping actions like `read_databases` and `read_csvs`. 
+   Instead, unify data sources (e.g., move CSVs into a database) and design a single action.
+   The action can be parameterized (e.g., string for search) or  programmable (e.g., SQL queries).
+
 ### Example: Search Agent
 
 This agent:

docs/decomp.md

@@ -5,9 +5,19 @@ parent: "Design"
 nav_order: 2
 ---
 
-# Task Decomposition
+# Workflow
 
-Many real-world tasks are too complex for one LLM call. The solution is to decompose them into multiple calls as a [Flow](./flow.md) of Nodes.
+Many real-world tasks are too complex for one LLM call. The solution is to decompose them into a [chain](./flow.md) of multiple Nodes.
+
+### Best Practice
+
+You don't want to make each task **too coarse**, because it may be *too complex for one LLM call*.
+
+You don't want to make each task **too granular**, because then *the LLM call doesn't have enough context* and results are *not consistent across nodes*.
+
+You usually need multiple *iterations* to find the *sweet spot*.
+
+If the task has too many *edge cases*, consider using [Agents](./agent.md).
 
 ### Example: Article Writing
 

docs/index.md

@@ -51,7 +51,7 @@ We model the LLM workflow as a **Nested Directed Graph**:
 ## Design Patterns
 
 - [Structured Output](./structure.md)
-- [Task Decomposition](./decomp.md)
+- [Workflow](./decomp.md)
 - [Map Reduce](./mapreduce.md)
 - [RAG](./rag.md)
 - [Chat Memory](./memory.md)

docs/multi_agent.md

@@ -10,6 +10,9 @@ nav_order: 7
 Multiple [Agents](./flow.md) can work together by handling subtasks and communicating the progress. 
 Communication between agents is typically implemented using message queues in shared storage.
 
+### Best Practice
+
+Most of time, you don't need Multi-Agents. Start with a simple solution first.
 
 ### Example Agent Communication: Message Queue