AgentDeck SDK

Compose. Observe. Ship.

The production runtime for agents you already have.

A harness for agents you have to operate. You write agents, workflows and skills as small Python declarations in a .agentdeck/ directory. AgentDeck supplies everything around them — discovery, layered settings, provider wiring, sessions, streaming, MCP servers, typed workflows with human approval, an HTTP surface, and one ordered event log for every run — and leaves the running of a turn to the engines underneath.

That division is the whole design. AgentDeck owns configuration; the OpenAI Agents SDK and LangGraph own execution. There is no agent loop here, no graph engine, and no reimplementation of either — an Agent compiles to an SDK agent, a Workflow compiles to a LangGraph graph, and both are run by their own engine. What AgentDeck adds is the part those libraries deliberately leave to you: where definitions live, how they are configured, and what you can see and do while a run is in flight.

Who it is for

You want this if you are putting agents somewhere they have to keep working: several agents and workflows in one project, a chat surface and a batch path over the same definitions, runs you need to inspect afterwards, approvals that outlive the process that asked for them.

You do not want this if you are writing one script that calls one model — use the Agents SDK directly, and come back when the wiring around it has become the work. You also do not want it if you have already built your own harness: AgentDeck is opinionated about project layout and configuration, and those opinions are the product.

What it deliberately does not do

• No DSL. Definitions are Python. There is no YAML agent format, and there will not be one.
• No execution engine of its own. Bugs in the agent loop or in graph execution belong upstream, and improvements there arrive without agentdeck doing anything.
• No sandbox. Tools, skills and workflow nodes are ordinary Python in your process, and a model-chosen tool call is trusted by design. See SECURITY.md before you give an agent something destructive.
• No auth, no multi-tenancy, no hosted control plane, no marketplace. namespace labels a run; it does not authenticate anyone. Put a real gateway in front of the HTTP surface.
• No model routing, evaluation framework, or prompt management. One OpenAI-compatible endpoint per process, configured by environment.

Install

uv venv && source .venv/bin/activate
uv pip install "agentdeck-sdk[serve]"
export OPENAI_MODEL=gpt-4.1-mini OPENAI_API_KEY=sk-...

The distribution is agentdeck-sdk; the import stays agentdeck. OPENAI_BASE_URL points it at any OpenAI-compatible endpoint instead (a gateway, vLLM, Ollama). Extras: serve for the HTTP surface, durability for the Postgres/SQLite stores, observability for Langfuse tracing.

Contributing to agentdeck itself is a different setup — see CONTRIBUTING.md.

The smallest real thing

Everything you define lives in a .agentdeck/ directory next to where you run. The path is the registration: no catalog file, no __init__.py, no decorator to remember.

.agentdeck/
├── agents/greeter/agent.py            # an Agent(...)
├── workflows/new_booking/workflow.py  # a Workflow(...)
└── skills/parse-request/              # SKILL.md + optional scripts

One file is a complete agent:

# .agentdeck/agents/greeter/agent.py
from agentdeck import Agent

greeter = Agent(name="Greeter", instructions="You are a friendly scheduling assistant.")

Deck discovers, compiles and validates all of it, then runs it:

import asyncio

from agentdeck import Deck


async def main() -> None:
    async with Deck.from_project() as deck:          # discovers ./.agentdeck, fails fast
        result = await deck.run("Greeter", "hello")
        print(result.output)

        turn = await deck.run("Greeter", "hi", session_id="wa-123")   # remembers across calls
        async for event in deck.stream("Greeter", "and then?", session_id="wa-123"):
            print(event.kind)                        # text.delta … run.completed


asyncio.run(main())

Three runnable projects are in examples/ — a chat agent with a tool, a workflow that pauses for a human approval, and the one below. All are built by the test suite, so none can quietly stop working.

Something built with it, that you can use right now

The assistant on agentdecksdk.com — the panel in the corner of every documentation page — is an AgentDeck agent. Ask it something about AgentDeck and it will search these docs, read the pages it finds, and cite them.

Its entire source is examples/ask-agentdeck: 617 lines of Python for three tools over one Context[DocsCorpus], streaming the run's own events to the browser over SSE. Not a demo written to look good in a README — it is the thing actually serving the site, including the parts a public endpoint needs and a demo skips: an origin check, a per-day quota, a token ceiling, and an allowlist deciding which event kinds a browser is allowed to see.

It is also the honest test of the pitch. If "agents you have to operate" meant anything, it had to survive being operated.

What you get around your definitions

• Sessions — session_id= keeps a conversation across calls and across surfaces, in memory or in Redis.
• One event log per run — every turn, however it was started, appends to the same ordered log: text deltas, tool calls, token usage, the result. Status is folded from it, not stored.
• Run control — a run in flight can be paused, resumed or cancelled by id, at documented safe points, from another process.
• Human approval — a durable=True workflow node calls interrupt(), the run parks, and deck.pending() / deck.answer() finish it later, possibly somewhere else.
• An HTTP surface — agentdeck-serve puts chat, SSE streaming, workflows, and the approval inbox behind FastAPI without any code of yours.
• Tools, skills and MCP — SDK tools as plain functions, skills as SKILL.md directories, and named MCP servers from a .mcp.json beside your project.

Documentation

The full docs are at agentdecksdk.com:

• Getting Started — install, configure, first agent
• Core Concepts — agents, workflows, skills, the event log, run control
• Choosing a Store Backend — what to set before you deploy anything
• Reference — every setting and every Deck method, generated from the code

Project

AgentDeck is beta software under active development; breaking changes are listed in CHANGELOG.md.

• Contributing — CONTRIBUTING.md. PRs target dev; make check is the gate. Framework internals are laid out in agentdeck/README.md.
• Brand — docs/brand/.
• Security — SECURITY.md, including what is deliberately out of scope.
• Code of conduct — CODE_OF_CONDUCT.md.
• License — MIT, see LICENSE.