### Setup development environment

Source: https://github.com/sagi5060/agentdeck/blob/dev/CONTRIBUTING.md

Clone the repository, create a virtual environment, and install development dependencies.

```bash
git clone https://github.com/sagi5060/agentdeck.git && cd agentdeck
uv venv && uv pip install -e ".[dev,serve]"
pre-commit install          # ruff + ty + hygiene hooks on every commit
```

--------------------------------

### Run local development and preview

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs-site/README.md

Commands to install dependencies and start the development or preview servers.

```bash
npm --prefix docs-site ci
npm --prefix docs-site run dev        # http://localhost:3030, hot reload, no search
npm --prefix docs-site run preview    # http://localhost:3031, real build, search works
```

--------------------------------

### Start the agentdeck server

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs-site/content/guides/serve-over-http.mdx

Installs the necessary dependencies and launches the FastAPI server on the specified host and port.

```bash
uv pip install "agentdeck[serve] @ git+https://github.com/sagi5060/agentdeck.git@v3.0.1"
HOST=0.0.0.0 PORT=8000 agentdeck-serve
```

--------------------------------

### Install and Run Platform Agent

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/design/agentdeck-v2-architecture.md

Commands to install the toolkit and execute a prebuilt agent.

```bash
pip install agentdeck[toolkit]
agentdeck run Summarizer "summarize this file..."
```

--------------------------------

### Initialize Project from Directory

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/review-phase4-deck.md

Example of initializing a project from a specific directory path.

```python
from_project("./.agentdeck")  # today's directory, unchanged
```

--------------------------------

### Install AgentDeck and Configure Environment

Source: https://github.com/sagi5060/agentdeck/blob/dev/README.md

Set up a virtual environment, install the package with extras, and configure the required environment variables.

```bash
uv venv && source .venv/bin/activate
uv pip install "agentdeck[serve] @ git+https://github.com/sagi5060/agentdeck.git@v3.0.1"
export OPENAI_MODEL=gpt-4.1-mini OPENAI_API_KEY=sk-...
```

--------------------------------

### Install AgentDeck via uv

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs-site/content/getting-started.mdx

Sets up a virtual environment and installs the AgentDeck package from the specified git tag.

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

--------------------------------

### Initialize and Run the Deck

Source: https://github.com/sagi5060/agentdeck/blob/dev/examples/ask-agentdeck/README.md

Example of initializing the Deck with a specific context type and executing a query.

```python
async with Deck(agents=[ask], context=DocsCorpus) as deck:
    result = await deck.run("AskAgentDeck", question, context=corpus)
```

--------------------------------

### Install Observability Dependencies

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs-site/content/reference/deck.mdx

Install the necessary extras to enable Langfuse support.

```bash
pip install "agentdeck[observability]"
```

--------------------------------

### Run the agent

Source: https://github.com/sagi5060/agentdeck/blob/dev/examples/chat-agent-with-a-tool/README.md

Commands to set up the virtual environment, install dependencies, and execute the agent script.

```bash
uv venv && source .venv/bin/activate
uv pip install "agentdeck @ git+https://github.com/sagi5060/agentdeck.git@v3.0.1"
export OPENAI_MODEL=gpt-4.1-mini OPENAI_API_KEY=sk-...
python run.py
```

--------------------------------

### Initialize and use Deck in various configurations

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/decision-v3-entry-point.md

Demonstrates common initialization patterns including directory-based projects, code-first agent definitions, FastAPI integration, and multi-tenant setups.

```python
# 1. the directory project — what every v2 user has today
from agentdeck import Deck

async with Deck.from_project() as deck:
    turn = await deck.chat("Greeter", "sess-1", "hello")
    print(turn.output, turn.usage)


# 2. code-first — no directory, no discovery, no filesystem
from agentdeck import Deck
from agentdeck.authoring import BaseAgent

class Greeter(BaseAgent):
    instructions = "You are a friendly scheduling assistant."

async with Deck(invocables=[Greeter]) as deck:
    async for event in deck.stream("Greeter", "hello", session="sess-1"):
        ...
```

```python
# 3. embedded in someone else's service, explicit infrastructure
from contextlib import asynccontextmanager
from fastapi import FastAPI
from agentdeck import Deck
from agentdeck.adapters.stores.postgres import PostgresEventStore

deck = Deck(invocables=[Greeter, ClaimPipeline], store=PostgresEventStore(DSN))

@asynccontextmanager
async def lifespan(api: FastAPI):
    async with deck:
        yield

api = FastAPI(lifespan=lifespan)
api.mount("/agents", deck.asgi())
```

```python
# 4. deck-per-tenant over shared infrastructure
store = PostgresEventStore(DSN)                      # constructed by you
decks = {t: Deck(invocables=specs_for(t), store=store) for t in tenants}
# each deck closes only what it built; `store` outlives all of them
```

--------------------------------

### Execute core agent loop

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/beta-user-report-v3.md

Demonstrates the minimal setup required to initialize an agent and execute a task within a deck context.

```python
from agentdeck import Agent, Deck

greeter = Agent(name="greeter", instructions="You are terse.")
deck = Deck(agents=[greeter])

async with deck:
    result = await deck.run("greeter", "What is the capital of France?")
    print(result.output)   # "Paris is the capital of France."
```

--------------------------------

### Run Ask AgentDeck

Source: https://github.com/sagi5060/agentdeck/blob/dev/examples/ask-agentdeck/README.md

Commands to configure environment variables, run a single headless question, and start the local server.

```bash
export OPENAI_MODEL=gpt-4.1-mini OPENAI_API_KEY=sk-...
python run.py "how do I create an agent?"                    # one question, headless
uvicorn ask_agentdeck.server:app --port 8100                 # the route the docs panel calls
```

--------------------------------

### Session Output Example

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs-site/content/concepts/sessions-and-memory.mdx

Expected output showing the growth of session items over multiple turns.

```text
items after turn 1: 2
items after turn 2: 4
turn 1 is still there: user my name is Sagi
```

--------------------------------

### Configure Skills capability wrapper

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/deck-capability-wrapper-pattern.md

Example of initializing a Skills object with specific validation settings before passing it to the Deck.

```python
skills = Skills(
    "./skills",
    validate=True,
)

deck = Deck(
    agents=[booking_agent],
    skills=skills,
)
```

--------------------------------

### Configure networked backends for multi-worker or multi-machine setups

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs-site/content/concepts/choosing-a-store-backend.mdx

Use PostgreSQL or Redis when scaling across multiple workers or machines. The event log and checkpointer require the durability extra when using PostgreSQL.

```bash
export AGENTDECK_EVENTS=postgresql://user:pw@db/agentdeck     # or redis://cache:6379/0
export AGENTDECK_CHECKPOINT=postgresql://user:pw@db/agentdeck
export AGENTDECK_SESSION=redis://cache:6379/1
export AGENTDECK_CONTROL=sqlite:///var/lib/agentdeck/control.sqlite3
```

--------------------------------

### Run AgentDeck Server and Cloudflare Tunnel

Source: https://github.com/sagi5060/agentdeck/blob/dev/examples/ask-agentdeck/README.md

Commands to start the Uvicorn server locally and initiate the Cloudflare tunnel connection.

```bash
uvicorn ask_agentdeck.server:app --port 8100                     # binds 127.0.0.1
cloudflared tunnel run --token <TOKEN>                           # ask.agentdecksdk.com -> :8100
```

--------------------------------

### Event Log Output

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs-site/content/concepts/runs-and-the-event-log.mdx

Example output showing the sequence of events recorded in the event log for a completed run.

```text
0 run.started
1 text.delta
2 text.delta
3 usage.reported
4 message.completed
5 run.completed
gaps: []
status: completed
```

--------------------------------

### Define Agents and Workflows

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/design/agentdeck-v2-architecture.md

Example of defining a claims processing system using agent and workflow classes.

```python
class ClaimsAgent(BaseAgent):
    tools = [lookup_shipment, stdlib.tools.fetch_url]     # own function + stdlib
    mcp_servers = [MCPServer.stdio("uvx", ["jira-mcp"])]  # a whole toolset, one line

class FrontDesk(BaseAgent):                               # triage in four lines
    instructions = "Route: damage claims → ClaimsAgent, delays → TrackingAgent."
    handoffs = [ClaimsAgent, TrackingAgent]

class ClaimPipeline(BaseWorkflow):                        # the governed spine
    nodes = {
        "assess":  agent_node(ClaimsAgent),               # LLM judgment
        "report":  skill_node("damage-report"),           # deterministic, no LLM
        "approve": approval_node("Payout > ₪500"),        # durable human gate
        "payout":  tool_node(issue_refund),               # idempotency key from ctx
    }
    edges = [("assess", "report"), ("report", "approve"), ("approve", "payout")]
```

--------------------------------

### Query the Ask AgentDeck Server

Source: https://github.com/sagi5060/agentdeck/blob/dev/examples/ask-agentdeck/README.md

Example cURL request to the local server's POST /ask endpoint.

```bash
curl -N -X POST localhost:8100/ask -H 'content-type: application/json' \
  -d '{"question":"explain what this page is for","page":"concepts/skills"}'
```

--------------------------------

### Compare Engine-Specific Context Signatures

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/review-context-injection.md

Examples of how application code becomes coupled to specific execution engines without an AgentDeck abstraction.

```python
async def find_slots(
    ctx: RunContextWrapper[MiddleContext],
    date: str,
):
    ...
```

```python
async def reserve(
    state: BookingState,
    runtime: Runtime[MiddleContext],
):
    ...
```

--------------------------------

### Initialize Runtime as Entry Point

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/decision-v3-entry-point.md

Demonstrates the minimal approach using an async context manager to build and close a wired Runtime without a convenience facade.

```python
import uuid
from agentdeck import open_runtime
from agentdeck.core.content import coerce_input
from agentdeck.core.context import RunContext

async with open_runtime() as rt:
    ctx = RunContext(
        tenant="local", principal="user:local",
        run_id=str(uuid.uuid4()), trace_id=str(uuid.uuid4()),
        session_id="sess-1",
    )
    async for event in rt.run("Greeter", coerce_input("hello"), ctx):
        ...   # reduce the stream yourself
```

--------------------------------

### AgentDeck Error Messages

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/beta-user-report-v3.md

Examples of descriptive error messages provided by the SDK to guide developers in troubleshooting common configuration and lifecycle issues.

```text
this Deck is not open: use `async with deck:` (or `await deck.__aenter__()`) first.
two entries in agents= both use the name 'd'; one name is one invocable — rename one of them.
SKILL.md: frontmatter declares name 'WRONG', which must match its directory name 'broken'.
Agent is immutable; build a new one instead of setting 'name'.
```

--------------------------------

### Context Type Error Example

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/plan-context-injection.md

Example of a type mismatch error when the provided context does not match the required slot type.

```text
ContextTypeError:
find_slots requires MiddleContext, but this deck provides GitHubContext.
```

--------------------------------

### Prohibited Context Data

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/review-context-injection.md

Examples of objects that should not be stored in graph state.

```python
db
calendar client
authenticated principal
service handles
```

--------------------------------

### Avoiding engine-specific leakage

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/review-context-injection.md

Example of an engine-specific property that should not be exposed in the public context.

```python
ctx.langgraph_store
```

--------------------------------

### Initialize Agent with Skills

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/review-phase4-deck.md

Demonstrates the mapping of skill identifiers to parent directory names.

```python
Agent(skills=["booking"])
```

--------------------------------

### Deck Context Declaration

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/review-context-injection.md

Example of declaring a deck with a specific context type.

```python
Deck(context=MiddleContext)
```

--------------------------------

### Application-owned Data Injection

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/review-context-injection.md

Example of supplying application-owned data to the run method.

```python
deck.run(context=...)
```

--------------------------------

### Initialize Deck from project

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/decision-v3-entry-point.md

Use the from_project constructor to initialize the Deck instance using the current directory's .agentdeck configuration.

```python
from agentdeck import Deck

async with Deck.from_project() as deck:            # today's ./.agentdeck, unchanged
    turn = await deck.chat("Greeter", "sess-1", "hello")
    print(turn.output)
```

--------------------------------

### Sandboxed Skill Context Configuration

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/review-context-injection.md

Example of non-serializable objects that should not cross process boundaries.

```python
db
calendar_client
http_client
transaction
credentials
service handles
```

--------------------------------

### Run the workflow

Source: https://github.com/sagi5060/agentdeck/blob/dev/examples/workflow-with-an-approval/README.md

Commands to set up the environment and execute the deterministic refund workflow.

```bash
uv venv && source .venv/bin/activate
uv pip install "agentdeck[durability] @ git+https://github.com/sagi5060/agentdeck.git@v3.0.1"
export OPENAI_MODEL=none OPENAI_API_KEY=none
python run.py
```

--------------------------------

### Define Zero Context Parameters

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/review-context-injection.md

Example of a standard callable without context injection.

```python
def foo(a: str):
    ...
```

--------------------------------

### Initialize Project with Deck

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs-site/content/concepts/index.mdx

Discovers, imports, and compiles project components using the Deck class.

```python
import asyncio

from agentdeck import Deck


async def main() -> None:
    async with Deck.from_project() as deck:
        print(sorted(deck.agents), sorted(deck.workflows))


asyncio.run(main())
```

--------------------------------

### Example Chat Input Format

Source: https://github.com/sagi5060/agentdeck/blob/dev/examples/ask-agentdeck/README.md

The expected text-based context and message format for the chat interface.

```text
<context>
The reader is on the documentation page: concepts/skills
</context>

explain what this page is for
```

--------------------------------

### Scaffold New Project from Template

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/design/agentdeck-v2-architecture.md

Command to copy a template into the user's project directory for full ownership.

```bash
agentdeck new my-support --template customer-support
```

--------------------------------

### Deck.from_project

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs-site/content/reference/deck.mdx

Initializes a Deck instance by discovering agents, workflows, skills, and MCP configurations from a project directory.

```APIDOC
## Deck.from_project(path=".agentdeck")

### Description
Creates a Deck instance by scanning the specified project directory for agent and workflow bundles, skills, and MCP configurations.

### Parameters
#### Path Parameters
- **path** (str) - Optional - The directory path containing the project configuration. Defaults to ".agentdeck".
```

--------------------------------

### Initialize Deck with capability wrappers

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/deck-capability-wrapper-pattern.md

Use dedicated capability objects for subsystems that require their own configuration or lifecycle management.

```python
deck = Deck(
    agents=[booking_agent],
    workflows=[booking_workflow],
    skills=Skills("./skills"),
    mcp=MCP("mcp.json"),
)
```

--------------------------------

### Define Context Hierarchy

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/review-context-injection.md

Example of base and derived context classes for type compatibility testing.

```python
class BaseContext: ...

class MiddleContext(BaseContext): ...
```

--------------------------------

### Define Single Context Parameter

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/review-context-injection.md

Example of a callable with exactly one injected context parameter.

```python
def foo(
    a: str,
    environment: Context[MiddleContext],
):
    ...
```

--------------------------------

### Define Agents and Decks

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/plan-phase4-deck.md

Demonstrates the initialization of agents with tools and skills, and the construction of a deck with context and execution.

```python
booking_agent = Agent(
    name="booking",
    instructions=booking_instructions,     # str or a Context-taking callable
    tools=[find_slots, book_slot],
    skills=["booking", "rescheduling"],    # names, resolved from the deck's skill roots
    mcp=["calendar", "crm"],               # names, resolved from the deck's MCP file
)

deck = Deck(
    agents=[booking_agent, support_agent],
    workflows=[onboarding_workflow],
    skills=["./skills", "./company-skills"],     # coerced to Skills(...)
    mcp=".mcp.json",                             # coerced to MCP(...)
    context=MiddleContext,
)

# the same, when a subsystem needs options of its own
deck = Deck(
    agents=[booking_agent],
    skills=Skills("./skills", validate=False),
    mcp=MCP(".mcp.json"),
    context=MiddleContext,
)
deck.build()

async with deck:
    result = await deck.run(
        "booking", message,
        session_id=conversation_id,
        namespace=f"business:{business_id}",
        context=MiddleContext(business=..., customer=..., calendar=...),
    )
```

--------------------------------

### Exposing AgentDeck-level semantics

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/review-context-injection.md

Examples of properties that align with AgentDeck's independent definitions of progress and control.

```python
ctx.reporter
ctx.checkpoint()
```

--------------------------------

### Deck Construction Patterns

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/plan-phase4-deck.md

Shows the two primary ways to instantiate a deck: direct constructor usage and project-based discovery.

```python
Deck(agents=..., workflows=..., skills=..., mcp=..., context=...)   # code-first
Deck.from_project("./.agentdeck")                                   # today's layout, unchanged
```

--------------------------------

### Define Workflow State and Context Separation

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/review-context-injection.md

Example of the signature separation between workflow state and execution context.

```python
async def reserve(
    state: BookingState,
    ctx: Context[MiddleContext],
):
    ...
```

--------------------------------

### Represent engine-specific context wrappers

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/review-context-injection.md

Examples of engine-specific wrappers that the AgentDeck API should abstract away from the user.

```text
RunContextWrapper
Runtime
SomeFutureEngineContext
```

--------------------------------

### Construct a Deck

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs-site/content/reference/deck.mdx

Initialize a Deck with explicit agents, workflows, skills, MCP configurations, and observers.

```python
Deck(
    agents=[...],                   # Agent instances
    workflows=[...],                # Workflow instances
    skills="./skills",              # a path, a sequence of paths, or a Skills(...) object
    mcp=".mcp.json",                # a path, or an MCP(...) object
    context=Calendar,               # the *type* of the per-run context, if this catalog wants one
    observers=[Langfuse()],         # taps on the event stream; None reads settings, () means none
)
```

--------------------------------

### Initialize Deck with direct components

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/deck-capability-wrapper-pattern.md

Pass top-level executable components like agents and workflows directly into the Deck constructor.

```python
deck = Deck(
    agents=[booking_agent, support_agent],
    workflows=[booking_workflow],
)
```

--------------------------------

### Agent declaration definition

Source: https://github.com/sagi5060/agentdeck/blob/dev/docs/delivery/beta-user-report-v3.md

Example of an agent declaration that fails to instantiate silently, leading to an empty deck.

```python
# .agentdeck/agents/ghost/agent.py
class Ghost(AgentDeclaration):
    instructions = "boo"
```