# 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.
- [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.
- [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)
- [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.
- [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)
