durable-agents

Crash-proof, resumable AI agents — a DeepAgents-style developer experience backed by Temporal durable execution.

---

durable-agents is a small, extensible framework for building multi-agent systems that survive crashes, restarts, and infrastructure failures. It gives you the ergonomics of DeepAgents — tools, skills, sub-agents, a plan-then-execute loop — but every step runs as a Temporal activity or child workflow, so agent state lives in durable event history instead of process memory.

Kill the worker mid-run and the agent resumes exactly where it left off. Every LLM call, tool invocation, and delegation is retryable and visible in the Temporal Web UI.

Why durable-agents?

Problem with in-memory agents	How durable-agents solves it
A crash loses the entire run	State is persisted in Temporal history; runs resume automatically
Transient API/network errors abort the agent	Activities retry with backoff, transparently
Bad LLM output crashes the loop	Malformed output becomes an observation the model corrects on the next step
Hard to observe what the agent did	Every step is an event in the Temporal Web UI
Long-running / human-in-the-loop work is fragile	Workflows can sleep for days and wake on a signal

Features

• 🧠 Plan-then-execute loop — the agent writes a structured plan, then executes each item, turning errors into recoverable observations.
• 🛠️ Simple tool authoring — decorate an async function with @tool; the JSON schema is generated for you.
• 👥 Sub-agent delegation — agents delegate to other agents that run as isolated child workflows.
• 🧩 Composable skills — bundle a system-prompt fragment and tools into a reusable @skill.
• 📁 Built-in filesystem tools — read_file, write_file, list_dir, search_files.
• 🪶 Thin clients — the client only needs a task-queue name; no tool imports, no schemas over the wire.
• ♻️ Durable by construction — built on Temporal's deterministic workflow / activity model.

Architecture at a glance

flowchart LR
    Client["DurableAgentClient<br/>(thin trigger)"] -->|task| WF["AgentWorkflow<br/>(deterministic)"]
    WF -->|create_plan| LLM1["LLM activity"]
    WF -->|execute_plan_item| LLM2["LLM activity"]
    WF -->|dispatch_tool| Tool["Tool activity"]
    WF -->|delegate| Child["Sub-agent<br/>child workflow"]
    WF -->|synthesize_result| LLM3["LLM activity"]
    WF --> Result["Final answer"]

Loading

The agent definition lives only on the worker. See docs/03-core-concepts.md for the full model.

Quickstart

Prerequisites: Python 3.11+, an OpenAI API key, uv, and Docker (or the Temporal CLI).

# 1. Install dependencies
uv sync

# 2. Configure secrets
cp .env.example .env          # set OPENAI_API_KEY

# 3. Start a local Temporal server (Web UI at http://localhost:8233)
docker compose up -d          # or: temporal server start-dev

Run the simplest example — start the worker, then submit a task:

# Terminal 1 — worker (blocks until Ctrl-C)
uv run python examples/01_research_agent/worker.py

# Terminal 2 — client
uv run python examples/01_research_agent/client.py "What is quantum entanglement?"

Define your own agent in a few lines:

from durable_agents import create_durable_agent, tool

@tool
async def web_search(query: str) -> str:
    """Search the web for information about the given query."""
    return f"Results for {query}: ..."

agent = create_durable_agent(
    model="openai:gpt-4o-mini",
    tools=[web_search],
    system_prompt="You are a helpful research assistant.",
    task_queue="research-agent",
)

await agent.run_worker()   # worker side
# result = await agent.run("Research quantum computing")   # trigger side

Documentation

Full documentation lives in docs/:

Chapter	Contents
1 — Introduction	What it is, durable execution, design philosophy
2 — Getting Started	Install, environment, running your first agent
3 — Core Concepts	Agent-on-worker, plan-then-execute, determinism
4 — Defining Agents	create_durable_agent reference
5 — Tools	@tool, the registry, built-in filesystem tools
6 — Sub-Agents	Delegation as child workflows
7 — Skills	The @skill decorator
8 — Architecture	How it maps onto Temporal; data models
9 — Examples	Walkthrough of the bundled examples
10 — Configuration	Environment-variable reference
11 — Roadmap	What's planned and why

Roadmap

durable-agents is alpha. The core loop, sub-agents, skills, and filesystem tools work today. Planned next:

• 🧰 More built-in tools — shell execution and an MCP client.
• 🙋 Human-in-the-loop — pause for approval/input via Temporal signals.
• 🧠 Persistent memory — pluggable Postgres / Redis memory backends.
• 🔌 More model providers — beyond the current openai: prefix.
• 📈 Observability & streaming — OpenTelemetry, token streaming.

See docs/11-roadmap.md for details.

Contributing

Contributions are welcome — see CONTRIBUTING.md for dev setup, the test/lint workflow, and the Temporal determinism rules. Please open an issue to discuss substantial changes first.

License

Released under the MIT License.