Skip to content

a5c-ai/babysitter / library/specializations/ai-agents-conversational/skills/langgraph-state-graph

langgraph-state-graph

Verified

LangGraph StateGraph builder with state schema design. Create stateful agent workflows with cycles, conditionals, and persistence.

FileKindSize
README.mdmarkdown7.3 KB
SKILL.mdskill md6.9 KB
# LangGraph StateGraph Skill

## Overview

The `langgraph-state-graph` skill enables the design and implementation of stateful agent workflows using LangGraph's StateGraph pattern. This is the foundational building block for creating sophisticated AI agents that can maintain state, handle cycles, and support human-in-the-loop interactions.

## Key Features

- **Stateful Workflows**: Maintain and transform state across execution steps
- **Cyclical Graphs**: Support iterative agent loops unlike traditional DAGs
- **Conditional Routing**: Dynamic edge selection based on state conditions
- **Persistence**: Checkpoint and resume workflows across sessions
- **Human-in-the-Loop**: Interrupt workflows for human input or approval

## Prerequisites

1. **Python 3.9+**: LangGraph requires modern Python
2. **LangGraph Package**: `pip install langgraph`
3. **LangChain Core**: `pip install langchain-core`

## Installation

```bash
pip install langgraph langchain-core langchain-openai
# Optional: For persistence
pip install langgraph-checkpoint-sqlite
```

## Quick Start

### 1. Define State Schema

```python
from typing import TypedDict, Annotated, List
from langgraph.graph.message import add_messages

class ConversationState(TypedDict):
    # Messages with automatic appending
    messages: Annotated[List, add_messages]
    # Custom state fields
    user_intent: str
    confidence: float
    requires_clarification: bool
```

### 2. Create Node Functions

```python
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4")

def classify_intent(state: ConversationState) -> ConversationState:
    """Classify user intent from messages."""
    messages = state["messages"]
    # Classification logic
    return {
        "user_intent": "booking",
        "confidence": 0.85
    }

def generate_response(state: ConversationState) -> ConversationState:
    """Generate response based on intent."""
    response = llm.invoke(state["messages"])
    return {"messages": [response]}

def request_clarification(state: ConversationState) -> ConversationState:
    """Ask for clarification when confidence is low."""
    return {
        "messages": [{"role": "assistant", "content": "Could you please clarify..."}],
        "requires_clarification": True
    }
```

### 3. Build the Graph

```python
from langgraph.graph import StateGraph, END

# Initialize graph with state type
graph = StateGraph(ConversationState)

# Add nodes
graph.add_node("classify", classify_intent)
graph.add_node("respond", generate_response)
graph.add_node("clarify", request_clarification)

# Set entry point
graph.set_entry_point("classify")

# Add conditional edges
def route_by_confidence(state: ConversationState) -> str:
    if state["confidence"] < 0.7:
        return "clarify"
    return "respond"

graph.add_conditional_edges(
    "classify",
    route_by_confidence,
    {"clarify": "clarify", "respond": "respond"}
)

# Both paths end the graph
graph.add_edge("respond", END)
graph.add_edge("clarify", END)

# Compile
app = graph.compile()
```

### 4. Execute the Workflow

```python
# Initial state
initial_state = {
    "messages": [{"role": "user", "content": "I want to book a flight"}],
    "user_intent": "",
    "confidence": 0.0,
    "requires_clarification": False
}

# Run the graph
result = app.invoke(initial_state)
print(result["messages"][-1])
```

## Advanced Patterns

### ReAct Agent Loop

```python
from langgraph.prebuilt import create_react_agent

# Simple ReAct agent
agent = create_react_agent(llm, tools=[search_tool, calculator_tool])
result = agent.invoke({"messages": [("user", "What is 25 * 4?")]})
```

### Multi-Agent Coordination

```python
# Define specialist agents as subgraphs
researcher_graph = create_researcher_graph()
writer_graph = create_writer_graph()
reviewer_graph = create_reviewer_graph()

# Coordinator graph
coordinator = StateGraph(CoordinatorState)
coordinator.add_node("researcher", researcher_graph)
coordinator.add_node("writer", writer_graph)
coordinator.add_node("reviewer", reviewer_graph)

# Sequential flow with feedback loop
coordinator.add_edge("researcher", "writer")
coordinator.add_edge("writer", "reviewer")
coordinator.add_conditional_edges(
    "reviewer",
    lambda s: "done" if s["approved"] else "revise",
    {"done": END, "revise": "writer"}
)
```

### Streaming Execution

```python
# Stream state updates
for chunk in app.stream(initial_state):
    for node_name, node_output in chunk.items():
        print(f"{node_name}: {node_output}")
```

## Integration with Babysitter Processes

| Process | Use Case |
|---------|----------|
| langgraph-workflow-design | Primary graph design workflow |
| multi-agent-system | Coordinate multiple specialist agents |
| plan-and-execute-agent | Hierarchical task planning |
| conversational-memory-system | Stateful conversation management |

## Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| workflowName | string | required | Identifier for the workflow |
| stateSchema | object | required | State type definition |
| nodes | array | required | Node function specifications |
| edges | array | required | Edge definitions with routing |
| enablePersistence | boolean | true | Enable checkpointing |
| interruptPoints | array | [] | Nodes to pause before |
| checkpointerType | string | "memory" | sqlite, postgres, or memory |

## State Schema Best Practices

### Use Annotated Types for Special Behaviors

```python
from typing import Annotated
from langgraph.graph.message import add_messages

class State(TypedDict):
    # Messages accumulate automatically
    messages: Annotated[list, add_messages]

    # Regular fields are replaced
    current_step: str

    # Use reducers for custom accumulation
    scores: Annotated[list, lambda a, b: a + b]
```

### Separate Mutable and Immutable State

```python
class WorkflowState(TypedDict):
    # Immutable inputs
    task_id: str
    user_id: str

    # Mutable working state
    messages: Annotated[list, add_messages]
    artifacts: list
    status: str
```

## Troubleshooting

### Graph Not Compiling

1. Verify all nodes are connected to the graph
2. Check that entry point is set
3. Ensure all conditional edge targets exist
4. Validate state schema matches node return types

### State Not Persisting

1. Confirm checkpointer is configured
2. Verify thread_id is passed in config
3. Check database connection for external checkpointers

### Cycles Not Working

1. Ensure conditional edges return correct target names
2. Verify loop termination conditions
3. Check for state updates that enable cycle exit

## Security Considerations

- Validate all user inputs before processing
- Implement rate limiting on LLM calls
- Use tool permissions and guardrails
- Audit state changes for sensitive data

## References

- [LangGraph Documentation](https://langchain-ai.github.io/langgraph/)
- [LangGraph Tutorials](https://langchain-ai.github.io/langgraph/tutorials/)
- [Awesome LangGraph](https://github.com/von-development/awesome-LangGraph)
- [LangGraph Conceptual Guide](https://langchain-ai.github.io/langgraph/concepts/)

## Related Resources

- [LangChain Expression Language](https://python.langchain.com/docs/expression_language/)
- [CrewAI](https://github.com/crewAIInc/crewAI) - Alternative multi-agent framework
- [AutoGen](https://github.com/microsoft/autogen) - Microsoft's agent framework
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall