| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 5 | 6 | 0% |
| Commands | 0 | 0 | 0 | — |
| Section tags | 1 | 1 | 1 | 33% |
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`)
- + LangSmith Tracing & Console Rules
- + Rule 1: Mandatory Logging for Agent Nodes
- + Rule 2: Error Logging Standards
- + Rule 3: Trace Agent Decision Paths
- + Rule 4: Console Output for Key Events
- + Rule 5: LangSmith Integration for Production
Commands
neither file has anySection tags
1 shared · 1 only in A · 1 only in B- − types
- + do-not
- 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 · .windsurf/rules/langsmith.md
@@ +1 @@
1---
2trigger: manual
3---
4
5# LangSmith Tracing & Console Rules
6
7These rules are designed to ensure effective tracing and debugging of agent interactions within the LangGraph project using LangSmith or similar console logging mechanisms. Proper logging and tracing are essential for monitoring the behavior of conversational agents and diagnosing issues in the graph workflow.
8
9## Rule 1: Mandatory Logging for Agent Nodes
10- **Description**: All agent nodes must log their entry and exit states, including key state variables like message count and session ID, to provide visibility into the conversation flow.
11- **Rationale**: In 'src/agent/graph.ts', logging is implemented for chat and entry nodes to track processing, which is crucial for understanding node behavior during debugging.
12- **Enforcement**: Ensure each node function includes logging statements at the beginning and end of processing, capturing relevant state information.
13
14## Rule 2: Error Logging Standards
15- **Description**: Errors encountered during model invocation or node processing must be logged with detailed error messages, including the error type and context, to facilitate quick diagnosis.
16- **Rationale**: Error handling in 'src/agent/graph.ts' uses 'handleGlobalError' to manage and log errors, ensuring that issues are captured for review.
17- **Enforcement**: Implement error logging in try-catch blocks within node functions, ensuring error details are recorded.
18
19## Rule 3: Trace Agent Decision Paths
20- **Description**: Log the decision paths taken by the supervisor or routing functions to trace how conversations are routed through the graph.
21- **Rationale**: The 'routeMessages' function in 'src/agent/graph.ts' logs routing decisions, which helps in understanding why a particular node was chosen next.
22- **Enforcement**: Include logging for routing logic outcomes, specifying the next node or termination condition.
23
24## Rule 4: Console Output for Key Events
25- **Description**: Key events such as user input receipt, agent response generation, and conversation termination must be output to the console for real-time monitoring.
26- **Rationale**: Real-time console output provides immediate feedback on system operation, aiding developers during testing and debugging sessions.
27- **Enforcement**: Add console.log statements or equivalent for significant events in the conversation flow.
28
29## Rule 5: LangSmith Integration for Production
30- **Description**: For production environments, integrate LangSmith or a similar tracing tool to capture detailed execution traces of graph workflows for post-analysis.
31- **Rationale**: Advanced tracing tools like LangSmith provide deeper insights into performance and bottlenecks, beyond basic console logging.
32- **Enforcement**: Configure LangSmith integration in the project settings or environment variables when moving to production testing or deployment.
33
34These rules ensure that debugging and tracing capabilities are robust within the LangGraph project, allowing developers to monitor and improve agent performance effectively. Activate these rules during debugging sessions or when preparing for production deployment.
35
@@ −1 +1 @@
11 ---
2−glob: "**/*.ts"
3−description: "Langgraph Agents Guidelines"
2+trigger: manual
43 ---
5−# Agents Guidelines
64
7−## Agent Responsibilities
5+# LangSmith Tracing & Console Rules
86
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.
7+These rules are designed to ensure effective tracing and debugging of agent interactions within the LangGraph project using LangSmith or similar console logging mechanisms. Proper logging and tracing are essential for monitoring the behavior of conversational agents and diagnosing issues in the graph workflow.
138
14−## Agent Development Principles
9+## Rule 1: Mandatory Logging for Agent Nodes
10+- **Description**: All agent nodes must log their entry and exit states, including key state variables like message count and session ID, to provide visibility into the conversation flow.
11+- **Rationale**: In 'src/agent/graph.ts', logging is implemented for chat and entry nodes to track processing, which is crucial for understanding node behavior during debugging.
12+- **Enforcement**: Ensure each node function includes logging statements at the beginning and end of processing, capturing relevant state information.
1513
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.
14+## Rule 2: Error Logging Standards
15+- **Description**: Errors encountered during model invocation or node processing must be logged with detailed error messages, including the error type and context, to facilitate quick diagnosis.
16+- **Rationale**: Error handling in 'src/agent/graph.ts' uses 'handleGlobalError' to manage and log errors, ensuring that issues are captured for review.
17+- **Enforcement**: Implement error logging in try-catch blocks within node functions, ensuring error details are recorded.
2318
24−## Agent Architectures
19+## Rule 3: Trace Agent Decision Paths
20+- **Description**: Log the decision paths taken by the supervisor or routing functions to trace how conversations are routed through the graph.
21+- **Rationale**: The 'routeMessages' function in 'src/agent/graph.ts' logs routing decisions, which helps in understanding why a particular node was chosen next.
22+- **Enforcement**: Include logging for routing logic outcomes, specifying the next node or termination condition.
2523
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.
24+## Rule 4: Console Output for Key Events
25+- **Description**: Key events such as user input receipt, agent response generation, and conversation termination must be output to the console for real-time monitoring.
26+- **Rationale**: Real-time console output provides immediate feedback on system operation, aiding developers during testing and debugging sessions.
27+- **Enforcement**: Add console.log statements or equivalent for significant events in the conversation flow.
2928
30−## Agent Type Definitions (`src/agent/state.ts`)
29+## Rule 5: LangSmith Integration for Production
30+- **Description**: For production environments, integrate LangSmith or a similar tracing tool to capture detailed execution traces of graph workflows for post-analysis.
31+- **Rationale**: Advanced tracing tools like LangSmith provide deeper insights into performance and bottlenecks, beyond basic console logging.
32+- **Enforcement**: Configure LangSmith integration in the project settings or environment variables when moving to production testing or deployment.
3133
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+These rules ensure that debugging and tracing capabilities are robust within the LangGraph project, allowing developers to monitor and improve agent performance effectively. Activate these rules during debugging sessions or when preparing for production deployment.
3435
