SpillwaveSolutions/mastering-langgraph-agent-skill
mastering-langgraph
VerifiedBuild stateful AI agents and agentic workflows with LangGraph in Python. Covers tool-using agents with LLM-tool loops, branching workflows, conversation memory, human-in-the-loop oversight, and production monitoring. Use when - (1) building agents that use tools and loop until task complete, (2) creating multi-step workflows with conditional branches, (3) adding persistence/memory across turns with checkpointers, (4) implementing human approval with interrupt(), (5) debugging via time-travel or LangSmith. Covers StateGraph, nodes, edges, add_conditional_edges, MessagesState, thread_id, Command objects, and ToolMessage handling. Examples include chatbots, calculator agents, and structured workflows.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.9 KB |
| references/core-api.md | markdown | 6.3 KB |
| references/debugging-monitoring.md | markdown | 4.2 KB |
| references/hitl-patterns.md | markdown | 5.3 KB |
| references/multi-agent-patterns.md | markdown | 9.4 KB |
| references/official-resources.md | markdown | 10.9 KB |
| references/persistence-memory.md | markdown | 5.1 KB |
| references/production-deployment.md | markdown | 8.3 KB |
| references/tool-agent-pattern.md | markdown | 6.4 KB |
| references/workflow-patterns.md | markdown | 6.3 KB |
references/hitl-patterns.md
View on GitHub# Human-in-the-Loop Patterns
Pause agents for human approval, correction, or additional input.
## Contents
- [Overview](#overview)
- [The interrupt() Function](#the-interrupt-function)
- [Approval Workflows](#approval-workflows)
- [Correction Workflows](#correction-workflows)
- [Requesting Additional Input](#requesting-additional-input)
- [Best Practices](#best-practices)
---
## Overview
| Pattern | Use Case |
|---------|----------|
| Approval | Review draft before sending |
| Correction | Fix agent mistakes mid-execution |
| Input | Request missing information |
| Escalation | Hand off complex cases |
**Requirement:** HITL requires a checkpointer for state persistence.
---
## The interrupt() Function
```python
from langgraph.types import interrupt
def review_node(state):
draft = state["draft"]
# Pause and ask human
human_response = interrupt({
"draft": draft,
"question": "Approve or provide feedback."
})
# Resumes here after human responds
if human_response.get("approved"):
return {"status": "approved"}
return {"feedback": human_response.get("feedback")}
```
### Resuming After Interrupt
```python
config = {"configurable": {"thread_id": "review-123"}}
# Initial invocation (pauses at interrupt)
result = chain.invoke({"draft": "Hello world..."}, config=config)
# Returns interrupt payload
# Human provides response
human_input = {"approved": True}
final = chain.invoke(human_input, config=config)
```
---
## Approval Workflows
### Draft → Review → Send
```python
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.types import interrupt
from typing_extensions import TypedDict
class EmailState(TypedDict):
request: str
draft: str
approved: bool
sent: bool
def generate_draft(state: EmailState) -> dict:
draft = llm.invoke(f"Write email for: {state['request']}")
return {"draft": draft.content}
def human_review(state: EmailState) -> dict:
response = interrupt({
"draft": state["draft"],
"action": "approve_or_edit"
})
if response.get("approved"):
return {"approved": True}
elif response.get("edited_draft"):
return {"draft": response["edited_draft"], "approved": True}
return {"approved": False}
def send_email(state: EmailState) -> dict:
if state["approved"]:
send(state["draft"])
return {"sent": True}
return {"sent": False}
def route_after_review(state: EmailState) -> str:
return "send" if state["approved"] else "__end__"
graph = StateGraph(EmailState)
graph.add_node("generate", generate_draft)
graph.add_node("review", human_review)
graph.add_node("send", send_email)
graph.add_edge(START, "generate")
graph.add_edge("generate", "review")
graph.add_conditional_edges("review", route_after_review, ["send", "__end__"])
graph.add_edge("send", END)
chain = graph.compile(checkpointer=InMemorySaver())
```
---
## Correction Workflows
### Rollback and Retry
```python
# Find checkpoint before mistake
for state in chain.get_state_history(config):
print(f"{state.config['configurable']['checkpoint_id']}: {state.next}")
# Resume from earlier checkpoint
corrected_config = {
"configurable": {
"thread_id": "task-123",
"checkpoint_id": "checkpoint-before-mistake"
}
}
chain.update_state(corrected_config, {"classification": "correct_value"})
result = chain.invoke(None, config=corrected_config)
```
### Mid-Execution Verification
```python
def classification_node(state) -> dict:
classification = llm.invoke(f"Classify: {state['input']}").content
if state.get("confidence", 1.0) < 0.8:
human_check = interrupt({
"proposed": classification,
"question": "Is this correct?"
})
if not human_check.get("correct"):
classification = human_check.get("corrected_value")
return {"classification": classification}
```
---
## Requesting Additional Input
```python
def process_order(state) -> dict:
if not state.get("shipping_address"):
address = interrupt({
"question": "Please provide shipping address",
"required_fields": ["street", "city", "zip"]
})
return {"shipping_address": address}
return {"order_status": "processing"}
```
---
## Best Practices
### 1. Always Use Checkpointer
```python
# ✓ Required for interrupt()
chain = graph.compile(checkpointer=InMemorySaver())
```
### 2. Clear Interrupt Payloads
```python
# ✓ Clear and actionable
interrupt({
"draft": state["draft"],
"action": "approve_or_reject",
"instructions": "Review for tone and accuracy"
})
```
### 3. Handle All Response Cases
```python
def review_node(state):
response = interrupt({"draft": state["draft"]})
if response.get("approved"):
return {"status": "approved"}
elif response.get("rejected"):
return {"status": "rejected", "reason": response.get("reason")}
elif response.get("edited"):
return {"draft": response["edited"], "status": "revised"}
return {"status": "pending"}
```
### 4. Audit Trail
```python
def audited_review(state):
response = interrupt({"draft": state["draft"]})
return {
"approved": response.get("approved"),
"reviewer": response.get("reviewer_id"),
"review_timestamp": response.get("timestamp")
}
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 470k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |