| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 6 | 6 | 0% |
| Commands | 0 | 0 | 0 | — |
| Section tags | 0 | 1 | 1 | 0% |
What each file covers
Sections
0 shared · 6 only in A · 6 only in B- − Subgraphs and Workflow Orchestration
- − LangGraph Core Concept
- − Key Components
- − Designing Subgraphs
- − Example Flows
- − Persistence with Subgraphs
- + Graph Rules
- + Rule 1: Mandatory Entry Node
- + Rule 2: Conditional Routing Logic
- + Rule 3: Node Error Handling
- + Rule 4: Logging for Node Transitions
- + Rule 5: Termination Conditions
Commands
neither file has anySection tags
0 shared · 1 only in A · 1 only in B- − agent-behaviour
- + do-not
Line diff
ssdeanx/langgraph-dm · .clinerules/subgraphs.md
@@ −1 @@
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
ssdeanx/langgraph-dm · .windsurf/rules/graphs.md
@@ +1 @@
1---
2trigger: manual
3---
4
5# Graph Rules
6
7These rules govern the construction and management of graph workflows within the LangGraph project. The purpose is to ensure that graphs are structured correctly, maintain logical flow, and adhere to best practices for conversational agent interactions.
8
9## Rule 1: Mandatory Entry Node
10- **Description**: All graph workflows must include an entry node to process initial user input. This node is responsible for initializing the conversation state and ensuring that user input is captured correctly.
11- **Rationale**: The entry node sets the foundation for the conversation flow, as seen in 'src/agent/graph.ts' where the 'entryNode' function processes the initial user input into the state.
12- **Enforcement**: During graph design or updates, verify that an 'entry' node is defined and connected to the START point.
13
14## Rule 2: Conditional Routing Logic
15- **Description**: Graphs must implement conditional routing logic to determine the next node based on the state or supervisor decisions. This ensures dynamic conversation flow.
16- **Rationale**: In 'src/agent/graph.ts', the 'routeMessages' function uses state.next to decide whether to proceed to a chat node or end the conversation, demonstrating the importance of conditional edges.
17- **Enforcement**: Ensure that conditional edges are defined for supervisor nodes to route to appropriate nodes or END.
18
19## Rule 3: Node Error Handling
20- **Description**: Each node in the graph must include error handling to manage model invocation failures or unexpected issues during processing.
21- **Rationale**: Error handling is critical for robustness, as shown in 'src/agent/graph.ts' where 'safeModelInvoke' and 'handleGlobalError' are used to catch and manage errors during model calls.
22- **Enforcement**: Include try-catch blocks or error handling mechanisms in node implementations.
23
24## Rule 4: Logging for Node Transitions
25- **Description**: Log transitions between nodes to track the flow of conversation and aid in debugging graph execution.
26- **Rationale**: Logging is implemented in 'src/agent/graph.ts' for chat and entry nodes to monitor processing, which is essential for understanding graph behavior.
27- **Enforcement**: Add logging statements at the start and end of each node's processing logic.
28
29## Rule 5: Termination Conditions
30- **Description**: Define clear termination conditions within the graph to prevent infinite loops and ensure conversations can conclude appropriately.
31- **Rationale**: The 'routeMessages' function in 'src/agent/graph.ts' checks for 'FINISH' or 'END' to route to END, providing a clear exit path.
32- **Enforcement**: Verify that routing logic includes checks for termination signals or states.
33
34These rules are designed to maintain the integrity and efficiency of graph-based workflows in LangGraph, ensuring that conversational agents operate smoothly and reliably. Review these during graph design and updates to ensure compliance.
35
@@ −1 +1 @@
11 ---
2−glob: "**/*.ts"
3−description: "Langgraph Subgraphs & Workflow Orchestration"
2+trigger: manual
43 ---
5−# Subgraphs and Workflow Orchestration
64
7−## LangGraph Core Concept
5+# Graph Rules
86
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.
7+These rules govern the construction and management of graph workflows within the LangGraph project. The purpose is to ensure that graphs are structured correctly, maintain logical flow, and adhere to best practices for conversational agent interactions.
128
13−## Key Components
9+## Rule 1: Mandatory Entry Node
10+- **Description**: All graph workflows must include an entry node to process initial user input. This node is responsible for initializing the conversation state and ensuring that user input is captured correctly.
11+- **Rationale**: The entry node sets the foundation for the conversation flow, as seen in 'src/agent/graph.ts' where the 'entryNode' function processes the initial user input into the state.
12+- **Enforcement**: During graph design or updates, verify that an 'entry' node is defined and connected to the START point.
1413
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.
14+## Rule 2: Conditional Routing Logic
15+- **Description**: Graphs must implement conditional routing logic to determine the next node based on the state or supervisor decisions. This ensures dynamic conversation flow.
16+- **Rationale**: In 'src/agent/graph.ts', the 'routeMessages' function uses state.next to decide whether to proceed to a chat node or end the conversation, demonstrating the importance of conditional edges.
17+- **Enforcement**: Ensure that conditional edges are defined for supervisor nodes to route to appropriate nodes or END.
2218
23−## Designing Subgraphs
19+## Rule 3: Node Error Handling
20+- **Description**: Each node in the graph must include error handling to manage model invocation failures or unexpected issues during processing.
21+- **Rationale**: Error handling is critical for robustness, as shown in 'src/agent/graph.ts' where 'safeModelInvoke' and 'handleGlobalError' are used to catch and manage errors during model calls.
22+- **Enforcement**: Include try-catch blocks or error handling mechanisms in node implementations.
2423
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.
24+## Rule 4: Logging for Node Transitions
25+- **Description**: Log transitions between nodes to track the flow of conversation and aid in debugging graph execution.
26+- **Rationale**: Logging is implemented in 'src/agent/graph.ts' for chat and entry nodes to monitor processing, which is essential for understanding graph behavior.
27+- **Enforcement**: Add logging statements at the start and end of each node's processing logic.
3428
35−## Example Flows
29+## Rule 5: Termination Conditions
30+- **Description**: Define clear termination conditions within the graph to prevent infinite loops and ensure conversations can conclude appropriately.
31+- **Rationale**: The 'routeMessages' function in 'src/agent/graph.ts' checks for 'FINISH' or 'END' to route to END, providing a clear exit path.
32+- **Enforcement**: Verify that routing logic includes checks for termination signals or states.
3633
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.
34+These rules are designed to maintain the integrity and efficiency of graph-based workflows in LangGraph, ensuring that conversational agents operate smoothly and reliably. Review these during graph design and updates to ensure compliance.
4735
