| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 5 | 6 | 0% |
| Commands | 0 | 0 | 0 | — |
| Section tags | 1 | 1 | 0 | 50% |
What each file covers
Sections
0 shared · 5 only in A · 6 only in B- − Agents Guidelines
- − Agent Responsibilities
- − Agent Development Principles
- − Agent Architectures
- − Agent Type Definitions (`src/agent/state.ts`)
- + Subgraphs and Workflow Orchestration
- + LangGraph Core Concept
- + Key Components
- + Designing Subgraphs
- + Example Flows
- + Persistence with Subgraphs
Commands
neither file has anySection tags
1 shared · 1 only in A · 0 only in B- − types
- agent-behaviour
Line diff
ssdeanx/langgraph-dm · .clinerules/agents.md
@@ −1 @@
1---
2glob: "**/*.ts"
3description: "Langgraph Agents Guidelines"
4---
5# Agents Guidelines
6
7## Agent Responsibilities
8
9* **Supervisor:** Acts as the central orchestrator (`src/agent/supervisor.ts`), directing the flow between specialized agents based on the current state and user intent. It should be robust in decision-making and error recovery.
10* **Specialized Agents:** Each agent (e.g., `reactAgent`, `research_agent`, `documentation_agent`) should have a clearly defined purpose and set of tools. They should focus on their specific domain, update the `AgentState` with their results, and return control to the supervisor upon completion or if an unhandled error occurs.
11* **Chat Agent (`chatNode`):** Provides general conversational responses and acts as a fallback for queries not requiring specialized agent intervention.
12* **Tool-Calling Agent (ReAct):** Uses an LLM to decide the control flow, selecting and using various tools, retaining memory, and planning multi-step actions.
13
14## Agent Development Principles
15
16* **Modularity:** Each agent should be a self-contained unit, with its own logic and potentially its own set of tools. This facilitates reusability and easier debugging.
17* **State Management:** Agents must correctly interact with and update the `AgentState` to ensure continuity and accurate context passing throughout the graph. Use `Annotation` and reducers for precise state modifications.
18* **Tool Integration:** Agents should seamlessly integrate and utilize the available tools (`src/tools/*`) to perform their tasks. Ensure proper input validation and error handling when calling tools. Consider `ToolNode` for simplified tool execution.
19* **Error Handling:** Implement agent-specific error handling to gracefully manage failures and report back to the supervisor or user.
20* **Logging:** Use the `winston` logger (`src/config/logger.ts`) for tracing agent execution, decisions, and tool calls.
21* **Control Flow:** Agents can return `Command` objects to combine state updates and dynamic routing (e.g., handoffs between agents).
22* **Human-in-the-Loop:** Design agents to support human intervention for approvals, state editing, or input collection using LangGraph's `interrupt()` function.
23
24## Agent Architectures
25
26* **Router:** LLM selects a single path from options.
27* **Tool-Calling Agent (ReAct):** Combines tool usage, memory, and planning for multi-step decision-making.
28* **Multi-Agent Systems:** Break down complex problems into smaller, independent agents collaborating via networks, supervisors, or hierarchical structures. Handoffs are crucial for communication.
29
30## Agent Type Definitions (`src/agent/state.ts`)
31
32* The `AgentType` enum defines the various types of agents supported in the system, enabling clear categorization and routing within the `StateGraph`.
33* When adding new agent types, ensure they are properly defined in `AgentType` and integrated into the `StateGraph` in `src/agent/graph.ts`.
34
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
@@ −1 +1 @@
11 ---
22 glob: "**/*.ts"
3−description: "Langgraph Agents Guidelines"
3+description: "Langgraph Subgraphs & Workflow Orchestration"
44 ---
5−# Agents Guidelines
5+# Subgraphs and Workflow Orchestration
66
7−## Agent Responsibilities
7+## LangGraph Core Concept
88
9−* **Supervisor:** Acts as the central orchestrator (`src/agent/supervisor.ts`), directing the flow between specialized agents based on the current state and user intent. It should be robust in decision-making and error recovery.
10−* **Specialized Agents:** Each agent (e.g., `reactAgent`, `research_agent`, `documentation_agent`) should have a clearly defined purpose and set of tools. They should focus on their specific domain, update the `AgentState` with their results, and return control to the supervisor upon completion or if an unhandled error occurs.
11−* **Chat Agent (`chatNode`):** Provides general conversational responses and acts as a fallback for queries not requiring specialized agent intervention.
12−* **Tool-Calling Agent (ReAct):** Uses an LLM to decide the control flow, selecting and using various tools, retaining memory, and planning multi-step actions.
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.
1312
14−## Agent Development Principles
13+## Key Components
1514
16−* **Modularity:** Each agent should be a self-contained unit, with its own logic and potentially its own set of tools. This facilitates reusability and easier debugging.
17−* **State Management:** Agents must correctly interact with and update the `AgentState` to ensure continuity and accurate context passing throughout the graph. Use `Annotation` and reducers for precise state modifications.
18−* **Tool Integration:** Agents should seamlessly integrate and utilize the available tools (`src/tools/*`) to perform their tasks. Ensure proper input validation and error handling when calling tools. Consider `ToolNode` for simplified tool execution.
19−* **Error Handling:** Implement agent-specific error handling to gracefully manage failures and report back to the supervisor or user.
20−* **Logging:** Use the `winston` logger (`src/config/logger.ts`) for tracing agent execution, decisions, and tool calls.
21−* **Control Flow:** Agents can return `Command` objects to combine state updates and dynamic routing (e.g., handoffs between agents).
22−* **Human-in-the-Loop:** Design agents to support human intervention for approvals, state editing, or input collection using LangGraph's `interrupt()` function.
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.
2322
24−## Agent Architectures
23+## Designing Subgraphs
2524
26−* **Router:** LLM selects a single path from options.
27−* **Tool-Calling Agent (ReAct):** Combines tool usage, memory, and planning for multi-step decision-making.
28−* **Multi-Agent Systems:** Break down complex problems into smaller, independent agents collaborating via networks, supervisors, or hierarchical structures. Handoffs are crucial for communication.
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.
2934
30−## Agent Type Definitions (`src/agent/state.ts`)
35+## Example Flows
3136
32−* The `AgentType` enum defines the various types of agents supported in the system, enabling clear categorization and routing within the `StateGraph`.
33−* When adding new agent types, ensure they are properly defined in `AgentType` and integrated into the `StateGraph` in `src/agent/graph.ts`.
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.
3447
