update doc

docs/_config.yml

@@ -29,3 +29,7 @@ callouts:
   note:
     title: Note
     color: blue
+  best_practice:
+    title: Best Practice
+    color: green
+

docs/agent.md

@@ -10,20 +10,12 @@ nav_order: 6
 Agent is a powerful design pattern, where node can take dynamic actions based on the context it receives.
 To express an agent, create a Node (the agent) with [branching](./flow.md) to other nodes (Actions).
 
-
+> The core of build **performant** and **reliable** agents boils down to:
-### Best Practice
+> 
-
+> 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.
-The core of build **performant** and **reliable** agents boils down to:
+>
-
+> 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).
-1. **Context Management**  
+{: .best_practice }
-   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
 

docs/communication.md

@@ -22,10 +22,8 @@ Nodes and Flows **communicate** in two ways:
 
 If you know memory management, think of the **Shared Store** like a **heap** (shared by all function calls), and **Params** like a **stack** (assigned by the caller).
 
-> **Best Practice:** Use `Shared Store` for almost all cases. It's flexible and easy to manage. It separates *Data Schema* from *Compute Logic*, making the code easier to maintain. 
+> Use `Shared Store` for almost all cases. It's flexible and easy to manage. It separates *Data Schema* from *Compute Logic*, making the code easier to maintain. `Params` is more a syntax sugar for [Batch](./batch.md).
->
+{: .best_practice }
-> `Params` is more a syntax sugar for [Batch](./batch.md).
-{: .note }
 
 ---
 

docs/decomp.md

@@ -1,6 +1,6 @@
 ---
 layout: default
-title: "Task Decomposition"
+title: "Workflow"
 parent: "Design"
 nav_order: 2
 ---
@@ -9,15 +9,12 @@ nav_order: 2
 
 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 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 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).
-You usually need multiple *iterations* to find the *sweet spot*.
+{: .best_practice }
-
-If the task has too many *edge cases*, consider using [Agents](./agent.md).
 
 ### Example: Article Writing
 

docs/multi_agent.md

@@ -10,9 +10,8 @@ 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.
-
+{: .best_practice }
-Most of time, you don't need Multi-Agents. Start with a simple solution first.
 
 ### Example Agent Communication: Message Queue