🧊 dagcache

Record your AI agent once. Replay it on every repeat task.

Agents waste time and money re-planning tasks they've already solved. dagcache watches an agent run, remembers the steps it took, and replays those steps the next time a similar task comes in — the LLM only gets called for genuinely new situations.

💡 The idea

Workflow tools like Luigi make you write out the whole workflow up front. dagcache flips that around: it watches your agent work and learns the workflow on its own. Once a way of solving a task proves it works, dagcache saves it and reuses it — like VCR cassettes, but for agent behavior instead of HTTP.

run agent once  ──▶  save the steps it took  ──▶  approve the winning route
                                                        │
        similar task comes in  ──▶  replay the steps (no planning LLM call)
                                                        │
        something changed in the world?  ──▶  fall back to the live agent

🚀 Install

pip install dagcache        # zero runtime dependencies

⚡ Quickstart

import dagcache

@dagcache.tool(pure=True)            # read-only: safe to skip in frozen replay
def search_kb(query: str) -> str: ...

@dagcache.tool(pure=False)           # has side effects: always runs for real
def send_reply(ticket_id: str, body: str) -> str: ...

@dagcache.llm(planning=True)         # decides what to do: skipped on replay
def plan(prompt: str) -> str: ...

@dagcache.llm                        # writes user-facing text: runs fresh
def draft(prompt: str) -> str: ...

@dagcache.agent
def resolve_ticket(ticket: dict) -> str:
    plan(f"handle {ticket['title']}")
    article = search_kb(ticket["title"])
    order = fetch_order(ticket["order_id"])
    send_reply(ticket["id"], f"see {article}")
    return draft(f"article={article}; status={order['status']}")

▶️ Try it: python examples/ticket_agent.py

🧠 What gets saved, exactly

dagcache doesn't cache answers — it caches the plan. Two things decide whether a saved plan applies:

1. which task it is (the @agent function), and
2. the shape of the inputs (their types and field names — never the actual values).

The saved plan is a graph of steps. Each step's arguments are stored as references, not fixed values:

If the agent finds two different ways to solve the same kind of task, both are kept and ranked by how often they work. dagcache approve locks in the winner. A saved plan that keeps failing is dropped after 3 failures.

🔁 Replay modes

• verified (default) — tools run for real with fresh values (real side effects, fresh data), planning LLM calls are skipped, text-writing LLM calls run again. Think of it as Luigi's worker, where the learned plan is the workflow.
• frozen — nothing runs; recorded results are returned as-is. Like Luigi's output().exists() across the whole graph — VCR mode, great for tests and CI.

dagcache.configure(db_path=".dagcache/store.db", replay_mode="frozen")
# or env: DAGCACHE_MODE=record|off, DAGCACHE_REPLAY=verified|frozen, DAGCACHE_DB=...

Two tasks can have the same input shape but mean different things (a refund ticket vs. a complaint). Give the agent a discriminator — its value becomes part of what makes a task unique:

@dagcache.agent(key=lambda ticket: ticket["category"])

🛠 CLI

dagcache ls                    # id, status, recordings, hits, failures, steps
dagcache show 3                # full plan JSON
dagcache approve 3             # lock in the winning route
dagcache demote 3              # back to probation
dagcache diff 3 7              # compare two candidate routes
dagcache export 3 -o c.json    # save a cassette for code review
dagcache import c.json
dagcache prune --status dead --older-than 30

🔌 Framework integrations

OpenAI (duck-typed — works with any .chat.completions.create client):

from dagcache.adapters.openai import wrap_client
client = wrap_client(OpenAI())   # role="auto"|"planning"|"output"

Responses containing tool_calls are treated as planning (skipped on replay); text responses as output writing (run again on replay, with the prompt updated to fresh data).

LangChain (duck-typed — no langchain import required):

from dagcache.adapters.langchain import wrap_tools, wrap_llm
agent = build_agent(llm=wrap_llm(ChatOpenAI(...)), tools=wrap_tools([...]))

⚠️ Honest limitations

• Matching is exact, not "similar". A saved plan only applies when the task type, input shape, and key all match exactly. Fuzzy/embedding matching is deliberately not in v0.1 — a "close enough" match replaying a path with real side effects is how the cache refunds the wrong customer.
• Side effects really happen. Verified replay runs effectful tools for real. That's automation, not caching. Mark them pure=False and keep fuzzy matching off.
• Made-up values can go stale. If the LLM invented a value that came from neither the inputs nor tool results (e.g. a date it guessed), it's replayed verbatim. Change detection only checks the shape of results.
• Prompt updating is a heuristic: old→new value substitution with word-boundary matching. A value that changed but still looks the same (e.g. a price) is not detected.
• The agent function must return its final call's result. Custom post-processing after the last LLM/tool call won't run on replay.
• Cache poisoning is a thing: if agent inputs are attacker-controlled, keep a separate store per principal and approve plans before production.

💎 Ruby

A RubyLLM plugin on the same mental model lives in the companion repo ruby_llm-dagcache — YAML cassettes, DagCache.watch(agent), automatic RubyLLM::Tool instrumentation.

📚 Prior art

• Agentic Plan Caching (arXiv 2506.14852) — research prototype; still spends an LLM call adapting templates.
• Agent Workflow Memory (arXiv 2409.07429) — injects past workflows into prompts; doesn't skip the agent.
• GPTCache / LangChain caches — cache single LLM calls by semantic similarity.
• LangGraph checkpointing / Temporal — resume interrupted runs, not reuse across tasks.
• vcrpy / VCR — the right mental model, at the wrong layer.

📄 License

MIT © dagcache contributors