| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 6 | 7 | 0% |
| Commands | 0 | 0 | 0 | — |
| Section tags | 1 | 0 | 5 | 17% |
What each file covers
Sections
0 shared · 6 only in A · 7 only in B- − Subgraphs and Workflow Orchestration
- − LangGraph Core Concept
- − Key Components
- − Designing Subgraphs
- − Example Flows
- − Persistence with Subgraphs
- + Headers
- + PROJECT DOCUMENTATION & CONTEXT SYSTEM
- + TECH STACK
- + CODING STANDARDS
- + Environment Variables
- + DEBUGGING
- + WORKFLOW & RELEASE RULES
Commands
neither file has anySection tags
1 shared · 0 only in A · 5 only in B- + setup
- + security
- + deployment
- + do-not
- + docs
- agent-behaviour
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 · .github/copilot-instructions.md
@@ +1 @@
1---
2description: AI rules derived by SpecStory from the project AI interaction history
3globs: *
4---
5
6## Headers
7
8## PROJECT DOCUMENTATION & CONTEXT SYSTEM
9
10## TECH STACK
11
12## CODING STANDARDS
13
14### Environment Variables
15
16* Avoid direct use of `process.env` or `import.meta.env` in the main code.
17* Use a configuration module or utility function to safely access environment variables.
18* Implement error handling to ensure that required environment variables are set. For example:
19
20 ```typescript
21 function getEnvVar(name: string): string {
22 const value = process.env[name];
23 if (!value) {
24 throw new Error(`${name} environment variable is not set.`);
25 }
26 return value;
27 }
28
29 const GOOGLE_API_KEY = getEnvVar("GOOGLE_API_KEY");
30 ```
31* All usages of environment variables must go through the designated utility function (e.g., `getEnvVar`). Direct access via `process.env` or `import.meta.env` elsewhere in the code is prohibited. Only the designated utility function (e.g. `getEnvVar`) should directly access `process.env`.
32* In Node.js environments, use `process.env` instead of `import.meta.env` to access environment variables.
33* When using external libraries, ensure that API keys or other sensitive configuration parameters are not passed directly as properties in constructors, if the library does not expect it. Instead, rely on environment variables or the library's recommended approach for authentication.
34* When using the `ExaSearchResults` class from the `@langchain/exa` library, the API key should not be passed directly to the constructor. Instead, ensure the `EXA_API_KEY` environment variable is set, and instantiate `ExaSearchResults` without the `apiKey` argument in the constructor. The library automatically uses the environment variable if set.
35
36## DEBUGGING
37
38## WORKFLOW & RELEASE RULES
@@ −1 +1 @@
11 ---
2−glob: "**/*.ts"
3−description: "Langgraph Subgraphs & Workflow Orchestration"
2+description: AI rules derived by SpecStory from the project AI interaction history
3+globs: *
44 ---
5−# Subgraphs and Workflow Orchestration
65
7−## LangGraph Core Concept
6+## Headers
87
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.
8+## PROJECT DOCUMENTATION & CONTEXT SYSTEM
129
13−## Key Components
10+## TECH STACK
1411
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.
12+## CODING STANDARDS
2213
23−## Designing Subgraphs
14+### Environment Variables
2415
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.
16+* Avoid direct use of `process.env` or `import.meta.env` in the main code.
17+* Use a configuration module or utility function to safely access environment variables.
18+* Implement error handling to ensure that required environment variables are set. For example:
3419
35−## Example Flows
20+ ```typescript
21+ function getEnvVar(name: string): string {
22+ const value = process.env[name];
23+ if (!value) {
24+ throw new Error(`${name} environment variable is not set.`);
25+ }
26+ return value;
27+ }
3628
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`).
29+ const GOOGLE_API_KEY = getEnvVar("GOOGLE_API_KEY");
30+ ```
31+* All usages of environment variables must go through the designated utility function (e.g., `getEnvVar`). Direct access via `process.env` or `import.meta.env` elsewhere in the code is prohibited. Only the designated utility function (e.g. `getEnvVar`) should directly access `process.env`.
32+* In Node.js environments, use `process.env` instead of `import.meta.env` to access environment variables.
33+* When using external libraries, ensure that API keys or other sensitive configuration parameters are not passed directly as properties in constructors, if the library does not expect it. Instead, rely on environment variables or the library's recommended approach for authentication.
34+* When using the `ExaSearchResults` class from the `@langchain/exa` library, the API key should not be passed directly to the constructor. Instead, ensure the `EXA_API_KEY` environment variable is set, and instantiate `ExaSearchResults` without the `apiKey` argument in the constructor. The library automatically uses the environment variable if set.
4235
43−## Persistence with Subgraphs
36+## DEBUGGING
4437
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−
38+## WORKFLOW & RELEASE RULES
