Skip to Content
Getting Started

Getting Started

Target: a running agent in under five minutes.

Install

uv venv && source .venv/bin/activate
uv pip install "agentdeck[serve] @ git+https://github.com/sagi5060/agentdeck.git@v3.0.1"

Installs from git at a tag. The repository is public, so no credentials are needed — swap https for ssh://git@ if you prefer keys.

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 →

Last updated on
OverviewOverview