Cline rules

1---
2glob: "**/*.ts"
3description: "Langgraph Subgraphs & Workflow Orchestration"
4---
5# Subgraphs and Workflow Orchestration
6 
7## LangGraph Core Concept
8 
9* This project heavily utilizes LangGraph's `StateGraph` to define and manage complex, multi-step AI agent workflows.
10* A "graph" represents the flow of control and data between different nodes (which are typically agents or tool calls).
11* Subgraphs allow you to reuse an existing graph as a node within another graph, promoting modularity and hierarchical organization.
12 
13## Key Components
14 
15* **Nodes:** Represent individual steps or agents in the workflow (e.g., `entryNode`, `supervisor`, `reactAgent`, `research_collectNode`). Each node takes the current `AgentState` as input and returns an updated state.
16* **Edges:** Define the transitions between nodes.
17  * **Normal Edges:** Unconditionally move from one node to another (e.g., `START` to `entry`, `chat` to `END`).
18  * **Conditional Edges:** Route to different nodes based on a decision function (e.g., `routeMessages` from `supervisor` to various agents). The routing function takes the `AgentState` and returns the name of the next node(s) or `END`.
19* **`AgentState`:** The central data structure that is passed and modified across all nodes in the graph, maintaining the conversation context and agent-specific data. Defined using `Annotation`.
20* **Supervisor:** A critical node responsible for intelligently routing the `AgentState` to the appropriate specialized agent or action based on the current context and goal.
21* **`Command` Primitive:** Allows combining state updates and control flow (routing) within a single node, useful for dynamic handoffs between agents.
22 
23## Designing Subgraphs
24 
25* **Modularity:** Complex workflows should be broken down into smaller, manageable subgraphs or sequences of nodes.
26* **Clear Responsibilities:** Each node and subgraph should have a clear, single responsibility.
27* **State Flow:** Pay close attention to how data flows through the `AgentState` between nodes to ensure necessary information is available at each step.
28* **Error Handling:** Design subgraphs to handle errors gracefully, potentially returning control to a supervisor for re-routing or error reporting.
29* **Routing Logic:** The `routeMessages` function (or similar conditional routing) is crucial for dynamic and intelligent workflow execution. Ensure its logic covers all necessary transitions and fallback scenarios.
30* **Communication:**
31  * If the parent graph and subgraph share schema keys (channels), the compiled subgraph can be added directly as a node.
32  * If schemas are different, define a node function that explicitly invokes the subgraph, transforming input state and output results to match the parent's schema. This prevents errors due to non-overlapping channels.
33* **Nesting:** Subgraphs can be nested to any level, allowing for highly complex hierarchical agent systems.
34 
35## Example Flows
36 
37* **General Conversation:** `entry` -> `supervisor` -> `chat` -> `END`
38* **Research Task:** `entry` -> `supervisor` -> `research_collect` -> `research_summarize` -> `research_report` -> `supervisor` (for final response)
39* **Documentation Task:** `entry` -> `supervisor` -> `draft_documentation` -> `finalize_documentation` -> `supervisor` (for final response)
40* **React Agent Task:** `entry` -> `supervisor` -> `react` -> `supervisor` (for tool execution or further action)
41* **Multi-agent Network:** Agents can communicate with each other in a many-to-many fashion, making decisions on which agent to call next (e.g., `travel_advisor` -> `sightseeing_advisor` -> `hotel_advisor`).
42 
43## Persistence with Subgraphs
44 
45* Checkpointers should be passed only when compiling the *parent* graph. LangGraph automatically propagates the checkpointer to child subgraphs, enabling persistence across nested levels.
46* State of subgraphs can be viewed and updated, facilitating human-in-the-loop interactions and debugging within nested workflows.
47