Getting Started

Target: a running agent in under five minutes.

Install

uv venv && source .venv/bin/activate
uv pip install "agentdeck-sdk[serve]"

The distribution on PyPI is agentdeck-sdk, and the import package is agentdeck — so you install one name and import another. The two differ because PyPI refuses agentdeck as too similar to an unrelated placeholder project; import agentdeck is what every example here uses and it is not changing.

serve is the extra for the HTTP surface. Others: durability for the Postgres/SQLite stores, observability for Langfuse tracing. Plain uv pip install agentdeck-sdk is enough for the first agent below.

Contributing to AgentDeck itself instead? Clone the repo and run make install — that path is in CONTRIBUTING.md, not here.

Point it at a model

export OPENAI_MODEL=gpt-4.1-mini
export OPENAI_API_KEY=sk-...

Unset OPENAI_BASE_URL means api.openai.com. Point it at any OpenAI-compatible server (a gateway, vLLM, Ollama); Chat-Completions-only servers also need OPENAI_USE_RESPONSES=false.

Create the project

Definitions live in a .agentdeck/ directory next to where you run. Location is registration — there is no catalog file.

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

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. Keep replies to one short sentence.")

Run it

import asyncio
 
from agentdeck import Deck
 
 
async def main() -> None:
    async with Deck.from_project() as deck:
        result = await deck.run("Greeter", "hello")
        print(result.output)
 
 
asyncio.run(main())

For a conversation that remembers across turns, pass a session_id instead:

import asyncio
 
from agentdeck import Deck
 
 
async def main() -> None:
    async with Deck.from_project() as deck:
        await deck.run("Greeter", "book me a slot Tuesday", session_id="sess-1")
        second = await deck.run("Greeter", "actually, make it Wednesday", session_id="sess-1")
        print(second.output)
 
 
asyncio.run(main())

Next

How the pieces fit → · API reference →