mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-17 14:36:29 +03:00
Magnus Hedemark
4a73657522
Comprehensive LangGraph skill covering: - Core architecture: Graph API, Functional API, state management, agent loops - Three multi-agent patterns: supervisor (~94% accuracy), swarm (~40% fewer LLM calls), hierarchical teams (subgraphs with nested state) - Persistence: checkpointers vs stores, per-invocation/per-thread/stateless modes - Production: Agent Server deployment, LangSmith observability, 8 failure modes - Evals: routing accuracy, resolution coverage, LLM-as-judge methodology - Troubleshooting: symptom→cause→fix tables per pattern - 3 Python scripts: supervisor scaffold, swarm scaffold, eval generator - 3 runnable templates: supervisor, swarm, subgraph composition Ships 8 reference files, 3 scripts, and 3 templates.
132 lines
4.4 KiB
Markdown
132 lines
4.4 KiB
Markdown
# Persistence — Checkpointers and Stores
|
|
|
|
LangGraph provides two complementary persistence systems: **checkpointers** for short-term, thread-scoped memory and **stores** for long-term, cross-thread memory.
|
|
|
|
## Checkpointer vs Store
|
|
|
|
| Dimension | Checkpointer | Store |
|
|
|-----------|-------------|-------|
|
|
| Persists | Graph state snapshots | Application-defined key-value data |
|
|
| Scope | A single thread | Across threads |
|
|
| Memory type | Short-term, thread-scoped | Long-term, cross-thread |
|
|
| Use for | Conversation continuity, HITL, time travel, fault tolerance | User preferences, facts, shared knowledge |
|
|
| Access | Pass `thread_id` in graph config | Read/write from nodes or application code |
|
|
|
|
## Checkpointers (Short-Term Memory)
|
|
|
|
A checkpointer saves snapshots of graph state after each superstep (node execution). This enables:
|
|
- **Conversation continuity** — resume a thread where it left off
|
|
- **Human-in-the-loop** — pause for input, then resume
|
|
- **Time travel** — replay from any checkpoint
|
|
- **Fault tolerance** — recover from crashes
|
|
|
|
### Backends
|
|
|
|
```python
|
|
from langgraph.checkpoint.memory import MemorySaver # in-memory (dev only)
|
|
from langgraph.checkpoint.sqlite import SqliteSaver # file-based (dev)
|
|
from langgraph.checkpoint.postgres import PostgresSaver # production
|
|
```
|
|
|
|
### Usage
|
|
|
|
```python
|
|
checkpointer = MemorySaver() # or PostgresSaver.from_conn_string(...)
|
|
checkpointer.setup() # creates tables for persistent backends
|
|
|
|
graph = builder.compile(checkpointer=checkpointer)
|
|
|
|
# Each thread gets a unique thread_id
|
|
config = {"configurable": {"thread_id": "thread-123"}}
|
|
|
|
result = graph.invoke(
|
|
{"messages": [{"role": "user", "content": "Hi, my name is Bob."}]},
|
|
config=config,
|
|
)
|
|
|
|
# Resume on the same thread — graph remembers previous messages
|
|
result2 = graph.invoke(
|
|
{"messages": [{"role": "user", "content": "What's my name?"}]},
|
|
config=config,
|
|
)
|
|
```
|
|
|
|
### Agent Server Handles Persistence Automatically
|
|
|
|
When deploying via LangSmith Agent Server, you do not need to implement or configure checkpointers manually. The server handles persistence infrastructure.
|
|
|
|
## Stores (Long-Term Memory)
|
|
|
|
A store persists key-value data outside graph state, accessible across threads and sessions.
|
|
|
|
### Usage
|
|
|
|
```python
|
|
from langgraph.store.memory import InMemoryStore
|
|
|
|
store = InMemoryStore()
|
|
|
|
# Write to store from a node
|
|
def remember_user(state: MessagesState, store: InMemoryStore):
|
|
user_id = extract_user_id(state["messages"])
|
|
store.put(
|
|
("users", user_id),
|
|
"preferences",
|
|
{"theme": "dark", "language": "en"},
|
|
)
|
|
return {"messages": [AIMessage(content="Saved your preferences!")]}
|
|
|
|
# Read from store
|
|
config = {"configurable": {"thread_id": "1"}}
|
|
result = graph.invoke(inputs, config=config, store=store)
|
|
```
|
|
|
|
### When to Use Store vs Checkpointer
|
|
|
|
| Need | Use |
|
|
|------|-----|
|
|
| Resume a conversation mid-stream | Checkpointer |
|
|
| Undo/redo across steps (time travel) | Checkpointer |
|
|
| Pause for human approval | Checkpointer |
|
|
| Remember user preferences across sessions | Store |
|
|
| Share data between unrelated threads | Store |
|
|
| Learn facts that persist beyond conversation | Store |
|
|
|
|
## Checkpointer Troubleshooting
|
|
|
|
### `thread_id` too long (PostgresSaver)
|
|
|
|
Keep `thread_id` under 255 characters. Use UUID or hash:
|
|
|
|
```python
|
|
import uuid
|
|
config = {"configurable": {"thread_id": str(uuid.uuid4())[:255]}}
|
|
```
|
|
|
|
### `MemorySaver` doesn't persist between restarts
|
|
|
|
In-memory checkpointers are lost on process restart. Use `PostgresSaver` or `SqliteSaver` for persistence.
|
|
|
|
### Checkpoints growing unboundedly
|
|
|
|
Long conversations accumulate checkpoints. Prune periodically or set retention:
|
|
|
|
```python
|
|
# PostgresSaver — add a cron job to delete old checkpoints:
|
|
# DELETE FROM langgraph_checkpoints WHERE created_at < NOW() - INTERVAL '7 days'
|
|
```
|
|
|
|
### State access from parent to subgraph
|
|
|
|
Subgraphs manage their own checkpoint namespace. Use **Store** for data that needs to cross graph boundaries, or configure the subgraph to write to the parent checkpoint.
|
|
|
|
## Advanced: Subgraph Persistence Modes
|
|
|
|
See `references/multi-agent-hierarchical.md` for the full subgraph persistence reference. Summary:
|
|
|
|
| Mode | `checkpointer=` | Behavior |
|
|
|------|----------------|----------|
|
|
| Per-invocation (default) | `None` | Fresh each call, inherits parent checkpointer for HITL |
|
|
| Per-thread | `True` | State accumulates across calls |
|
|
| Stateless | `False` | No checkpointing, runs like plain function |
|