# AgentDeck SDK

> The production runtime for agents you have to operate: composition, human-in-the-loop approvals, sessions, streaming, run control and one ordered event log, over the OpenAI Agents SDK and native workflows.

AgentDeck SDK is a Python harness for agents you have to operate. You write agents, workflows and
skills as small declarations in a `.agentdeck/` directory; AgentDeck supplies everything around
them: discovery, layered settings, sessions, streaming, MCP servers, human-in-the-loop
approvals, run control, and one ordered event log per run.

It executes native `@workflow` and `@tool` targets alongside the OpenAI Agents SDK for agents:
an `Agent` compiles to an SDK agent, and a `@workflow` is ordinary Python awaited by AgentDeck's
own executor. AgentDeck owns configuration and orchestration, and there is no agent loop here.

Use it when the wiring around an agent has become the work: several agents and workflows in one
project, a chat surface and a batch path over the same definitions, runs you must inspect
afterwards, approvals that outlive the process that requested them.

## Documentation

- [Agentic software should feel like software](https://agentdecksdk.com/): Build agents, tools and workflows as normal software. AgentDeck gives them one execution model you can observe, control and extend.
- [What's new in 6.0](https://agentdecksdk.com/meet-agentdeck/whats-new-6): One Deck, many bindings. How the outside reaches your agents, tools and workflows changed, and what it opens.
- [CLI](https://agentdecksdk.com/reference/cli): The agentdeck command tree, generated from agentdeck/cli.py's own --help output.
- [Deck](https://agentdecksdk.com/reference/deck): The composition root  -  builds a catalog from Agent objects and @workflow definitions or a project directory, and runs every turn on it.
- [Events](https://agentdecksdk.com/reference/events): Every event kind a run can emit, with its payload fields.
- [python-api](https://agentdecksdk.com/reference/python-api)
- [run](https://agentdecksdk.com/reference/run)
- [Settings](https://agentdecksdk.com/reference/settings): Every AGENTDECK_*, OPENAI_*, ANTHROPIC_*, GEMINI_*, OLLAMA_*, OPENROUTER_*, and TAVILY_* environment variable, generated from agentdeck/runtime/settings.py.
- [Bindings](https://agentdecksdk.com/bindings): Serve one Deck over multiple protocols and surfaces at once.
- [AG-UI](https://agentdecksdk.com/bindings/agui): Project a whole Deck, or one pinned target, into the AG-UI protocol.
- [Native](https://agentdecksdk.com/bindings/native): AgentDeck's own HTTP/SSE protocol, one route per Run operation.
- [Serve](https://agentdecksdk.com/bindings/serve): Validate a set of bindings, then serve them standalone or embed them in an app you already run.
- [Terminal](https://agentdecksdk.com/bindings/terminal): The surface over stdin/stdout, one session per process.
- [Write Your Own](https://agentdecksdk.com/bindings/write-your-own): The SPI a binding is held to, in or out of tree.
- [Agents](https://agentdecksdk.com/build-your-deck/agents): Declarative agents with tools, instructions, and model configurations.
- [Context](https://agentdecksdk.com/build-your-deck/context): Typed, request-scoped access to your own application state, for tools and workflows.
- [deck](https://agentdecksdk.com/build-your-deck/deck)
- [skills](https://agentdecksdk.com/build-your-deck/skills)
- [tools](https://agentdecksdk.com/build-your-deck/tools)
- [workflows](https://agentdecksdk.com/build-your-deck/workflows)
- [index](https://agentdecksdk.com/examples)
- [Agent with a Skill](https://agentdecksdk.com/examples/agent-with-a-skill): Two tools and one skill, prose the model loads only when it decides it needs it.
- [Chat Agent with a Tool](https://agentdecksdk.com/examples/chat-agent-with-a-tool): An agent that answers order questions by calling a plain Python function.
- [Chat in the Terminal](https://agentdecksdk.com/examples/chat-in-the-terminal): A workflow that asks the questions, driven by agentdeck chat. No API key.
- [Run Events Stream](https://agentdecksdk.com/examples/run-events-stream): A run's typed event log, printed as it arrives. No API key.
- [existing-agents](https://agentdecksdk.com/integrations/existing-agents)
- [mcp](https://agentdecksdk.com/integrations/mcp)
- [openai-agents-sdk](https://agentdecksdk.com/integrations/openai-agents-sdk)
- [How Jack is built](https://agentdecksdk.com/jack): What building a real application with AgentDeck looks like, and what AgentDeck provides around your application code.
- [Implementation notes](https://agentdecksdk.com/jack/notes): The decisions behind Jack, and the alternatives each one beat.
- [Mental Model](https://agentdecksdk.com/meet-agentdeck/mental-model): The four primitives, what you declare versus what AgentDeck runs, and how one becomes the other.
- [Overview](https://agentdecksdk.com/meet-agentdeck/overview): What AgentDeck is, the problem it solves, and what you keep when you adopt it.
- [Quickstart](https://agentdecksdk.com/meet-agentdeck/quickstart): Build a Deck, start a Run, and watch its events.
- [Deployment](https://agentdecksdk.com/operate/deployment): Running a Deck as a supervised, long-lived service, not `python run.py`.
- [Changelog](https://agentdecksdk.com/resources/changelog): What changed in each release of AgentDeck, and what to do about it when upgrading.
- [Known Issues](https://agentdecksdk.com/resources/known-issues): Defects in the current release that will surprise you, what happens, and what to do until each is fixed.
- [migration-guides](https://agentdecksdk.com/resources/migration-guides)
- [troubleshooting](https://agentdecksdk.com/resources/troubleshooting)
- [Events](https://agentdecksdk.com/runs-and-control/events): One ordered log per run, how to stream it live, and how to read it back afterwards.
- [human-input](https://agentdecksdk.com/runs-and-control/human-input)
- [Lifecycle & Control](https://agentdecksdk.com/runs-and-control/lifecycle-and-control): The six states a run can be in, what moves it between them, and which ones you can act on.
- [pause-resume](https://agentdecksdk.com/runs-and-control/pause-resume)
- [Runs](https://agentdecksdk.com/runs-and-control/runs): A run is a first-class execution with a durable identity you can pick up again, in this process or another one.
- [Sessions](https://agentdecksdk.com/runs-and-control/sessions): Keep an agent's message history across multiple runs, and what happens when two runs reach for the same one at once.

## Source

- [Repository](https://github.com/agentdecksdk/agentdeck): issues, releases and examples
- [Full documentation as one file](https://agentdecksdk.com/llms-full.txt)
