===============
LIBRARY RULES
===============
From library maintainers:
- The import name is `agentdeck`. The project is branded AgentDeck SDK; there is no `agentdeck-sdk` package, and `agentdeck-ai` on PyPI is an unrelated project.
- AgentDeck is NOT on PyPI, so `pip install agentdeck` fails. Install from a tag: `uv pip install "agentdeck[serve] @ git+https://github.com/agentdecksdk/agentdeck.git@v3.0.1"`. Always pin a tag.
- `Deck` is the only composition root, with two front doors onto one catalog: `Deck(agents=..., workflows=...)` and `Deck.from_project()`, which discovers them from a `.agentdeck/` directory.
- AgentDeck owns configuration; the OpenAI Agents SDK and LangGraph own execution. An `Agent` compiles to an SDK agent and a `Workflow` to a LangGraph graph. Never say AgentDeck runs its own agent loop or graph engine.
- A tool is a plain Python function passed to `Agent(tools=[...])`; `build()` compiles it. A tool declaring an `agentdeck.Context[T]` parameter must NOT use `@function_tool` — the decorator would put that parameter in the model's schema.
- State reaches tools and nodes via `Context[T]`: declare it with `Deck(context=MyType)`, pass it per run with `deck.run(..., context=obj)`. A context cannot cross HTTP — a run served through `Deck.asgi()` always receives `None`.
- Human approval requires `durable = True`, which requires a checkpointer and the `[durability]` extra. A node calling `interrupt()` re-runs from its start on resume, so interrupt nodes must have no side effects.
- Every run appends to one ordered event log; status is folded from it by `status_of`, never stored. `type(event)` is always `Event` — switch on `event.kind` with a default case, since an unknown kind parses as `UnknownEvent`.
- Nothing is sandboxed. Tools, skills and workflow nodes are ordinary Python in the caller's process, and a model-chosen tool call is trusted by design.
- Known defects are listed at /known-issues and should be honoured when advising — notably that `Agent(model=...)` is currently ignored, and that a tool which raises still completes the run.
### Run the agent-with-a-skill example
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/examples/agent-with-a-skill.mdx
Installs the SDK, sets the model and API key, then runs the example. Filing a note writes `handover_notes.json` into the working directory; delete that file between runs for a clean observable side effect.
```bash
uv pip install agentdeck-sdk
export OPENAI_MODEL=gpt-4.1-mini OPENAI_API_KEY=sk-...
python run.py
```
--------------------------------
### Clone and run an example: git clone, cd, export OPENAI_API_KEY
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/examples/index.mdx
Setup commands for running the chat-agent-with-a-tool example: clone the agentdecksdk/agentdeckhttps://github.com/agentdecksdk/agentdeckrepository, change into the example directory, and export the OPENAI_API_KEY environment variable before running the Python script.
```bash
git clone https://github.com/agentdecksdk/agentdeck
cd agentdeck/examples/chat-agent-with-a-tool
export OPENAI_API_KEY=sk-...
python run.py
```
--------------------------------
### Install and run chat agent with a tool
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/examples/chat-agent-with-a-tool.mdx
Installs the SDK and runs the example from its own directory. Deck.from_project() discovers ./agentdeck, so the working directory picks the project. OPENAI_BASE_URL points it at any OpenAI-compatible server instead, and Chat-Completions-only servers also want OPENAI_USE_RESPONSES=false.
```bash
uv pip install agentdeck-sdk
export OPENAI_MODEL=gpt-4.1-mini OPENAI_API_KEY=sk-...
python run.py
```
--------------------------------
### Complete setup with five bindings (shipped and roadmap)
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/meet-agentdeck/whats-new-6.mdx
Full example of serving a Deck with Native, AGUI, and Terminal bindings, with commented-out roadmap bindings for A2A and WhatsApp. Shows the one-line binding pattern and port configuration.
```python
from agentdeck import Deck
from agentdeck.bindings import AGUI, Native, Terminal
# from agentdeck.bindings import A2A, WhatsApp # roadmap: #552, #553
deck = Deck.from_project()
deck.serve(
Native.http("/api"),
AGUI.http("/agui"),
Terminal.stdio(),
# A2A.http("/a2a"), # roadmap: #552
# WhatsApp.http("/whatsapp"), # roadmap: #553
port=8000,
)
```
--------------------------------
### Run the agent with a skill
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/examples/agent-with-a-skill/README.md
Commands to set up the environment, install the SDK, set required environment variables, and run the example. Must be run from this directory so Deck.from_project() discovers ./.agentdeck.
```bash
uv venv && source .venv/bin/activate
uv pip install agentdeck-sdk
export OPENAI_MODEL=gpt-4.1-mini OPENAI_API_KEY=sk-...
python run.py
```
--------------------------------
### Setup and run agentdeck chat
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/examples/chat-in-the-terminal/README.md
Sets up the environment and starts the chat. Run from the project directory so Deck.from_project() discovers ./.agentdeck. The command agentdeck chat shift_handover launches the terminal chat for the shift_handover workflow.
```bash
uv venv && source .venv/bin/activate
uv pip install agentdeck-sdk
agentdeck chat shift_handover
```
--------------------------------
### Build a Deck with Agent and Deck
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/meet-agentdeck/quickstart.mdx
Creates an Agent named "assistant" using the gpt-4o-mini model and composes it into a Deck. This is the required setup before starting a run.
```python
from agentdeck import Agent, Deck
agent = Agent(
name="assistant",
model="gpt-4o-mini",
instructions="You are a concise assistant.",
)
deck = Deck(agents=[agent])
```
--------------------------------
### Install and run events stream
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/examples/run-events-stream/README.md
Commands to set up the virtual environment, install the AgentDeck SDK, and execute the run script.
```bash
uv venv && source .venv/bin/activate
uv pip install agentdeck-sdk
python run.py
```
--------------------------------
### Install AgentDeck SDK with serve extra
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/bindings/native.mdx
Installs the AgentDeck SDK with the 'serve' extra, which pulls in starlette and uvicorn. Native.http() requires no additional dependencies beyond these.
```bash
pip install "agentdeck-sdk[serve]"
```
--------------------------------
### Install AgentDeck SDK and configure environment
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/README.md
Install the package using pip and set the required OpenAI model and API key environment variables.
```bash
pip install agentdeck-sdk
export OPENAI_MODEL=gpt-4.1-mini OPENAI_API_KEY=sk-...
```
--------------------------------
### Installing Langfuse Observer Dependencies
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/reference/deck.mdx
Command to install the necessary extras for using the LangfuseObserver.
```bash
pip install "agentdeck-sdk[observability]"
```
--------------------------------
### Install agentdeck-sdk with AG-UI extra
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/bindings/agui.mdx
Install the AgentDeck SDK with the 'agui' extra, which pulls in the official ag-ui-protocol models and encoder, plus starlette.
```bash
pip install "agentdeck-sdk[agui]"
```
--------------------------------
### File layout for agent-with-a-skill example
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/examples/agent-with-a-skill.mdx
Shows the required file layout for the agent-with-a-skill example. The directory name is the skill's name and must match the `name:` in its frontmatter; `description:` is what the agent sees when deciding whether the skill applies. Both are required, or `Deck.build()` fails naming the bundle.
```text
.agentdeck/
├── agents/handover_desk/agent.py # two @tools + Agent(..., skills=["shift-notes"])
└── skills/shift-notes/SKILL.md # frontmatter + instructions the model loads on demand
run.py # two turns on one session: a lookup, then a note
```
--------------------------------
### Complete setup with five bindings (shipped and roadmap)
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/meet-agentdeck/whats-new-6.mdx
ASCII diagram of one Deck with five bindings: Native.http, AGUI.http, Terminal.stdio, A2A.http, WhatsApp.http. Shipped bindings are marked, roadmap ones are not.
```text
one Deck
│
┬──────────────────┬──────────────────┼──────────────────┬──────────────────┬
│ │ │ │ │
Native.http() AGUI.http() Terminal.stdio() A2A.http() WhatsApp.http()
shipped shipped shipped roadmap #552 roadmap #553
```
--------------------------------
### Configure Deck Observers
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/reference/deck.mdx
Demonstrates how to initialize a Deck with specific observers, including ConsoleObserver and LangfuseObserver, and how to start the deck context.
```python
from agentdeck import Deck, views
from agentdeck.observers import ConsoleObserver, LangfuseObserver
deck = Deck(
agents=[booking],
observers=[ConsoleObserver(view=views.chat | views.reports), LangfuseObserver()],
)
async with deck: # every observer starts here, once, before any run
await deck.run("booking", "hi") # never mid-run
```
--------------------------------
### Install AgentDeck SDK with pip
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/README.md
Install the agentdeck-sdk package using pip. Requires Python 3.12 or later.
```bash
pip install agentdeck-sdk
```
--------------------------------
### Start a run with a custom key
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/runs-and-control/runs.mdx
Starts a run with a custom `key` that you can use to find the run later without storing its `id`.
```python
run = await deck.runs.start("Jack", question, key=f"ticket-{ticket_id}")
```
--------------------------------
### Install and run agentdeck chat
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/examples/chat-in-the-terminal.mdx
Installs the agentdeck SDK and runs the `shift_handover` workflow via `agentdeck chat`. The command takes any agent or workflow; omit the name only when the deck holds exactly one target.
```bash
uv pip install agentdeck-sdk
agentdeck chat shift_handover
```
--------------------------------
### Example binding usage with Deck and MyProtocol
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/bindings/write-your-own.mdx
Shows how to create a Deck from a project and mount a custom protocol's HTTP endpoint. The package name 'agentdeck_myprotocol' is a placeholder and not a real import.
```python
from agentdeck import Deck
from agentdeck_myprotocol import MyProtocol
app = Deck.from_project().asgi(MyProtocol.http())
```
--------------------------------
### Define an Agent
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/reference/deck.mdx
Example of defining an Agent instance with a name and instructions.
```python
from agentdeck import Agent
greeter = Agent(name="Greeter", instructions="You are a friendly scheduling assistant. Keep replies to one short sentence.")
```
--------------------------------
### Example output of run events stream
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/examples/run-events-stream.mdx
Shows the expected output when running the example. Each line prints the event kind and its payload, demonstrating the event envelope and typed payloads for run.started, text.delta, usage.reported, message.completed, and run.completed.
```text
run.started: {'invocable': 'Greeter', 'kind_of_invocable': 'agent', ...}
text.delta: {'message_id': 'msg_scripted_1', 'text': 'Hel'}
text.delta: {'message_id': 'msg_scripted_1', 'text': 'lo'}
usage.reported: {'model': 'fake-scripted', 'usage': {'input_tokens': 3, 'output_tokens': 4, 'usd': None}}
message.completed: {'message_id': 'msg_scripted_1', 'text': 'Hello'}
run.completed: {'output': [{'type': 'text', 'text': 'Hello'}], 'usage': {...}}
```
--------------------------------
### Start a run and await its result
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/runs-and-control/runs.mdx
Starts a run with an agent name and input, then awaits the result. The `start` method returns a handle immediately; `await run` waits for the result, which is a `TurnResult` for an agent, the workflow's own result for a workflow, a native body's return value, or a graph's final state.
```python
async with deck:
run = await deck.runs.start("Jack", "how do I pause a run?")
result = await run
```
--------------------------------
### Define AgentDeck application components
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/README.md
Example showing the definition of a tool with context, an agent, a workflow with human-in-the-loop interaction, and the final Deck composition.
```python
from agentdeck import Agent, Deck, ToolCtx, WorkflowCtx, tool, workflow
class AppContext:
def search(self, query: str) -> str:
return "Internal records found."
@tool
def lookup_records(query: str, ctx: ToolCtx[AppContext]) -> str:
"""Look up internal records."""
return ctx.data.search(query)
agent = Agent(
name="SupportBot",
instructions="Help users resolve inquiries using internal tools.",
tools=[lookup_records],
)
@workflow
async def handle_request(ctx: WorkflowCtx, ticket: dict) -> str:
"""Coordinate support tasks with human approval for sensitive changes."""
response = await ctx.invoke(agent, ticket["query"])
if ticket.get("urgent"):
approved = await ctx.ask(f"Approve urgent response for ticket {ticket['id']}?", options=[True, False])
if not approved:
return "Escalated to human supervisor."
return response
deck = Deck(agents=[agent], workflows=[handle_request], context=AppContext)
```
--------------------------------
### Start a run with await deck.runs.start
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/meet-agentdeck/quickstart.mdx
Start a run by awaiting deck.runs.start(...) inside an async function. Without await, the coroutine is never executed.
```python
run = await deck.runs.start("assistant", input="Hello!")
```
--------------------------------
### Watch run events with follow=True
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/runs-and-control/runs.mdx
Iterates over run events as they occur. Without `follow=True`, you only get what the log already holds, which for a run that just started is one event.
```python
async for event in run.events(follow=True):
print(event.kind)
```
--------------------------------
### Rehydrate a run by id, key, or list paused runs
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/runs-and-control/runs.mdx
Shows three ways to get a handle to an existing run: by canonical `id`, by your own `key`, or by listing runs with a given status. `deck.runs.get()` never creates, starts, or resumes anything; it returns a run in any state, terminal included.
```python
run = await deck.runs.get(run_id) # by canonical id
run = await deck.runs.get(key="ticket-42") # by your own key
runs = await deck.runs.list(status=RunStatus.PAUSED) # everything parked
```
--------------------------------
### Example run.completed output structures
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/reference/deck.mdx
Illustrates the structure of the output list in a run.completed event for both text-only runs and runs that include artifacts like images.
```python
[TextBlock(text="Hello")] # a text run
[ImageBlock(...), TextBlock(text="Here is the generated image")] # a run that drew something
```
--------------------------------
### Plain function as a tool
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/build-your-deck/tools.mdx
A context-free plain function used in tools= is compiled the same way as @tool, with less ceremony. It gets the same schema and failure attribution, but cannot be started as its own child run and cannot take a ToolCtx parameter.
```python
def lookup_order(order_id: str) -> str:
"""Fetch status for an order."""
return f"Order {order_id} is in transit."
```
--------------------------------
### Start, pause, resume, and answer a run
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/README.md
Starts a run, pauses and resumes it if allowed, answers a human-approval wait, and awaits the final result. The run handle is first-class and addressable.
```python
run = await deck.runs.start("handle_request", {"id": "T-100", "query": "status update", "urgent": True})
if run.can.pause:
await run.pause()
await run.resume()
# Answer an execution waiting on human approval:
await run.answer(True)
result = await run
```
--------------------------------
### Start a workflow run and answer its question
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/build-your-deck/workflows.mdx
Start a workflow run and answer its pending question. The run suspends at ctx.ask and stays waiting_answer until answered; answering True resumes it and the final value is printed.
```python
run = await deck.runs.start("resolve", {"id": "T-1"})
# ... the run is now `waiting_answer`, and shows up in deck.runs.list(status=...)
await run.answer(True)
print(await run) # "refunded"
```
--------------------------------
### Start a run and stream events
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/meet-agentdeck/quickstart.mdx
Starts a run for the "assistant" agent with input "Hello!", streams events with follow=True until a terminal event, then prints the final status and result. Note that run.status() is a coroutine, not a property.
```python
async def main():
async with deck:
run = await deck.runs.start("assistant", input="Hello!")
async for event in run.events(follow=True):
print(event.kind)
result = await run
print("Status:", await run.status())
print("Result:", result.output)
```
--------------------------------
### Project layout for chat agent with a tool
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/examples/chat-agent-with-a-tool/README.md
Shows the project layout for the chat agent with a tool example. The agent.py file is registered by its location under .agentdeck/agents/, and run.py invokes the deck with the agent name and a sample question.
```text
.agentdeck/
└── agents/order_desk/agent.py # @tool + Agent(name="OrderDesk", tools=[...])
run.py # deck.run("OrderDesk", "where is order A-1001?")
```
--------------------------------
### Project layout for chat agent with a tool
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/examples/chat-agent-with-a-tool.mdx
Shows the project layout for the chat agent example. The agent file lives under .agentdeck/agents/order_desk/ and run.py is at the project root. The file's location is the registration; nothing imports agent.py and there is no catalog file to add it to.
```text
.agentdeck/
└── agents/order_desk/agent.py # @tool + Agent(name="OrderDesk", tools=[...])
run.py # deck.run("OrderDesk", "where is order A-1001?")
```
--------------------------------
### deck.runs.start
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/reference/deck.mdx
Starts a new run for a given agent name and input, optionally with a session ID. Returns a Run handle.
```APIDOC
## `deck.runs.start`
### Description
Starts a new run for the specified agent with the given input and optional session ID. Returns a `Run` handle.
### Method
`start`
### Signature
`start(agent_name, input, *, session_id=None)`
### Parameters
- `agent_name` (str) - Required - The name of the agent to run.
- `input` (dict) - Required - The input data for the run.
- `session_id` (str, optional) - Optional - The session identifier to associate with the run.
### Returns
`Run` - A handle to the started run.
### Example
```python
run = await deck.runs.start("Approval", {"order_id": "A-1003"}, session_id="t-1")
```
```
--------------------------------
### Create a Deck with agents and workflows
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/meet-agentdeck/mental-model.mdx
Construct a Deck with lists of agent and workflow declarations. This is the composition root that compiles declarations into a working system.
Example:
```python
deck = Deck(agents=[assistant], workflows=[approve])
```
```python
deck = Deck(agents=[assistant], workflows=[approve])
```
--------------------------------
### Managing Runs with deck.runs
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/reference/deck.mdx
Demonstrates starting a new run, retrieving an existing run by ID or application identity, and listing runs filtered by namespace and status.
```python
run = await deck.runs.start("Approval", {"order_id": "A-1003"}, session_id="t-1")
same_run = await deck.runs.get(run.id) # canonical
same_run = await deck.runs.get(namespace="acme", key="order-1234") # application identity
waiting = await deck.runs.list(namespace="acme", status=RunStatus.WAITING_ANSWER)
```
--------------------------------
### Serve standalone with Native.http()
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/bindings/serve.mdx
Starts a standalone AgentDeck server with an HTTP binding. `deck.serve()` is synchronous, owns the event loop, and blocks until interrupted. At least one binding is required; `host` and `port` are ignored for stdio-only exposures.
```python
from agentdeck import Deck
from agentdeck.bindings import Native
deck = Deck.from_project()
deck.serve(Native.http("/api"), host="0.0.0.0", port=8000)
```
--------------------------------
### Run an agent turn with text and image content
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/reference/deck.mdx
Example of running an agent turn using a list of content blocks, including a text block and a base64-encoded image block.
```python
import base64
from agentdeck import ImageBlock, TextBlock
photo = base64.b64encode(open("receipt.png", "rb").read()).decode()
result = await deck.run(
"Intake",
[TextBlock(text="What is the total on this receipt?"), ImageBlock(media_type="image/png", data_b64=photo)],
)
```
--------------------------------
### runs.start
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/reference/deck.mdx
Starts a run and returns a Run handle without waiting for the run to complete or reading its events. Useful for background runs.
```APIDOC
## runs.start
### Description
Starts a turn and returns a Run handle immediately without waiting for the run to finish or reading events. The run is recorded exactly as POST /runs would record it.
### Method
runs.start
### Parameters
- **name** (string) - Required - The name of the agent or workflow.
- **input** (string or list of content blocks) - Required - The input.
- **context** (optional) - Optional - Context.
- **session_id** (string) - Optional - Session id.
- **namespace** (string) - Optional - Namespace.
- **key** (string) - Optional - Application key.
### Returns
- **Run handle** - A handle to the started run. The same admission as run/stream without waiting for or reading it.
### Example
```python
run_handle = await deck.runs.start("RefundApproval", {"order_id": "A-1003"})
```
```
--------------------------------
### Serve deck on HTTP port 8080
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/resources/troubleshooting.mdx
Start the deck's HTTP server on port 8080. The port is passed as an argument; there is no environment variable for it. Two bindings cannot claim the same path, and only one stdio binding may run per exposure, both raising ConfigError at expose() before the listener opens.
```python
deck.serve(Native.http("/api"), port=8080)
```
--------------------------------
### Example of page context as text
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/examples/jack/README.md
This snippet demonstrates how page context is represented as text rather than a live object when interacting with the server.
```text
The reader is on the documentation page: concepts/skills
explain what this page is for
```
--------------------------------
### GET /targets
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/bindings/native.mdx
Retrieves the list of available targets with their metadata and input schemas.
```APIDOC
## GET /targets
### Description
Retrieves the list of available targets with their metadata and input schemas.
### Method
GET
### Endpoint
/targets
### Parameters
None
### Response
#### Success Response (200)
- **body** (array) - List of target objects, each with fields: `name`, `kind`, `description`, `input_schema`.
#### Response Example
```json
[
{
"name": "string",
"kind": "string",
"description": "string",
"input_schema": {}
}
]
```
### Errors
- **500** - Internal server error.
```
--------------------------------
### Run the jack backend with uvicorn
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/examples/jack/README.md
Starts the jack server on port 8100, binding to 127.0.0.1. Requires a tunnel or reverse proxy with a single route to :8100 and JACK_ORIGINS set to the site's origin. The frontend must use https to avoid TLS blocking.
```bash
uvicorn jack.server:app --port 8100 # binds 127.0.0.1
```
--------------------------------
### run.events()
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/reference/events.mdx
Asynchronously iterate over events for a run, optionally starting from a sequence number and following new events.
```APIDOC
## run.events()
### Description
Asynchronously iterate over events for a run, optionally starting from a sequence number and following new events.
### Method
Async generator
### Parameters
- `from_seq` (int) - Optional - Sequence number to start from.
- `follow` (bool) - Optional - If True, keep waiting for new events.
### Example
```python
async for event in run.events(from_seq=0, follow=True):
print(event.seq, event.kind)
```
```
--------------------------------
### stream
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/reference/deck.mdx
Starts a turn and returns an asynchronous generator of canonical events for the run. Suitable for live event streaming.
```APIDOC
## stream
### Description
Starts a turn and returns an AsyncGenerator that yields the run's canonical events live.
### Method
stream
### Parameters
- **name** (string) - Required - The name of the agent or workflow to run.
- **input** (string or list of content blocks) - ...
- **context** (optional) - Optional - context.
- **session_id** (string) - Optional - session id for history.
- **namespace** (string) - Optional - namespace.
- **key** (string) - Optional - application key for idempotency.
### Returns
- **AsyncGenerator[Event]** - The run's own canonical events, live.
### Example
```python
async for event in deck.stream("Intake", "What is the total?"):
print(event)
```
```
--------------------------------
### run
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/reference/deck.mdx
Starts an agent or workflow turn and waits for the result. For agents, returns TurnResult; for workflows, the workflow's own result or an InterruptResult if the body calls ctx.ask().
```APIDOC
## run
### Description
Starts a turn by name and returns the result. For an agent, returns TurnResult; for a workflow, returns the workflow's result or an InterruptResult if the workflow uses ctx.ask(). Resolves the name against the catalog and plays it on the Runtime.
### Method
run
### Signature
`(name, input, *, context=None, session_id=None, namespace=None, key=None)`
### Parameters
- **name** (string) - Required - The name of the agent or workflow to run.
- **input** (string or list of content blocks) - Required - The input to the turn. For agents, a string is coerced to a TextBlock. For workflows, a mapping binds by name or the whole value is passed.
- **context** (optional) - Optional - Additional context for the turn.
- **session_id** (string) - Optional - For conversational agents, the same id references the same history.
- **namespace** (string) - Optional - Namespace for the run.
- **key** (string) - Optional - Stable application identifier for idempotency and lookup, not the run's address.
### Returns
- **TurnResult** for an agent; the workflow's own result or an InterruptResult for a workflow.
### Notes
- Reusing a (namespace, key) pair whose run already started raises DuplicateKeyError.
- A body that calls ctx.ask(...) makes a workflow's run return an InterruptResult.
### Example
```python
# Example calling run on an agent deck.run("intake", "What is the total?")
```
```
--------------------------------
### Implementing a Custom Observer
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/reference/deck.mdx
A custom observer class inheriting from Observer, implementing the required emit method and optional start and close lifecycle hooks.
```python
from agentdeck import Observer
class CostObserver(Observer):
async def start(self) -> None:
... # open a client or a file; called once, at deck open, before any run
async def emit(self, event) -> None:
... # in-memory work only; never awaits a round trip
async def close(self) -> None:
... # the stream has ended: write out whatever is buffered
```
--------------------------------
### Export OPENAI_API_KEY
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/meet-agentdeck/quickstart.mdx
Export the OPENAI_API_KEY environment variable before running the script to resolve the missing key error. Also set the same variable in your IDE's run configuration if you start from there.
```bash
export OPENAI_API_KEY=sk-...
```
--------------------------------
### Expected run output
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/meet-agentdeck/quickstart.mdx
Example output from the run script. It shows the ordered lifecycle and content events, the final status "completed", and the result "Hello!". text.delta is one streamed fragment and there is usually more than one; message.completed carries the finished text.
```text
run.started
text.delta
usage.reported
message.completed
run.completed
Status: completed
Result: Hello!
```
--------------------------------
### Run a turn with Deck.from_project
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/reference/deck.mdx
Demonstrates running a turn using a project directory to initialize the Deck.
```python
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)
print(result.usage)
print(result.run_id)
asyncio.run(main())
```
--------------------------------
### Invoke an agent and run parallel child executions
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/build-your-deck/workflows.mdx
Invoke an agent with ctx.invoke to get a TurnResult, then run two child executions in parallel with ctx.parallel. The parallel call resolves to a list of each awaited result in the order given, not the handles themselves.
```python
scout = await ctx.invoke("scout", said) # agent -> TurnResult
topic = str(scout.output)
card, web = await ctx.parallel(
ctx.invoke(places_lookup, topic=topic), # tool -> plain value
ctx.invoke(web_search, topic=topic),
)
```
--------------------------------
### Creating a Deck from project discovery
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/build-your-deck/deck.mdx
Automatically discover and load components from the ./.agentdeck/ directory.
```python
deck = Deck.from_project()
```
--------------------------------
### Initialize and serve an AgentDeck
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/index.mdx
Define an agent with specific instructions and tools, then initialize a Deck and serve it via HTTP, AGUI, and terminal interfaces.
```python
jack = Agent(
name="Jack",
instructions="Help developers build with AgentDeck.",
tools=[search_docs, read_doc, read_changelog],
)
deck = Deck(agents=[jack], context=DocsCorpus)
deck.serve(Native.http("/api"), AGUI.http("/agui"), Terminal.stdio())
```
--------------------------------
### Run a workflow with Deck.from_project()
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/README.md
Uses Deck.from_project() as an async context manager to discover and validate all definitions at startup, then runs the 'handle_ticket' workflow with a dictionary of inputs. Validation catches missing skills, invalid types, or broken references at build() time.
```python
async with Deck.from_project() as deck:
result = await deck.run("handle_ticket", {"id": "T-101", "query": "help"})
```
--------------------------------
### Create ASGI application in app.py
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/operate/deployment.mdx
Initializes a Deck from a project directory and exposes it as an ASGI application using Native.http().
```python
# app.py
from agentdeck import Deck
from agentdeck.bindings import Native
app = Deck.from_project("./.agentdeck").asgi(Native.http())
```
--------------------------------
### Coroutine was never awaited warning
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/meet-agentdeck/quickstart.mdx
This warning appears when deck.runs.start(...) is called without await, building a coroutine that never starts. Start it inside an async def and drive that with asyncio.run(main()).
```text
RuntimeWarning: coroutine 'Runs.start' was never awaited
```
--------------------------------
### Build a Deck with skills
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/build-your-deck/skills.mdx
Builds a Deck directly, pointing skills at the skill directory. Deck.from_project() scans ./ .agentdeck/skills/ automatically; building a Deck directly instead requires pointing skills= at the same directory (or several, or a Skills(...) object).
```python
from agentdeck import Deck
deck = Deck(agents=[triage], skills="./.agentdeck/skills")
```
--------------------------------
### Mount as an ASGI application with deck.asgi
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/reference/deck.mdx
Returns an ASGI application for mounting in existing services, managing the deck's lifecycle automatically.
```python
app = deck.asgi(Native.http(path="/api")) # uvicorn yourmodule:app
```
--------------------------------
### GET /runs/{run_id}
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/bindings/native.mdx
Retrieves a single run summary by its ID.
```APIDOC
## GET /runs/{run_id}
### Description
Retrieves a single run summary by its ID.
### Method
GET
### Endpoint
/runs/{run_id}
### Parameters
#### Path Parameters
- **run_id** (string) - Required - The unique identifier of the run.
### Response
#### Success Response (200)
- **run summary** (object) - Contains `run_id`, `namespace`, `session_id`, `status`, `can`.
#### Response Example
```json
{
"run_id": "string",
"namespace": "string",
"session_id": "string",
"status": "string",
"can": {}
}
```
### Errors
- **404** - Run not found.
- **500** - Internal server error.
```
--------------------------------
### GET /runs
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/bindings/native.mdx
Lists runs, optionally filtered by status and limited in count.
```APIDOC
## GET /runs
### Description
Lists runs, optionally filtered by status and limited in count.
### Method
GET
### Endpoint
/runs
### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter by run status.
- **limit** (integer) - Optional - Maximum number of runs to return.
### Response
#### Success Response (200)
- **body** (array) - List of run summary objects, each with `run_id`, `namespace`, `session_id`, `status`, `can`.
#### Response Example
```json
[
{
"run_id": "string",
"namespace": "string",
"session_id": "string",
"status": "string",
"can": {}
}
]
```
### Errors
- **422** - Validation error.
- **500** - Internal server error.
```
--------------------------------
### Run Jack in headless or server mode
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/examples/jack/README.md
Configure the OpenAI environment variables and execute Jack either as a single-question headless process or as a Uvicorn 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 jack.server:app --port 8100 # the route the docs panel calls
```
--------------------------------
### Catch SessionBusyError when starting a second run on a busy session
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/runs-and-control/sessions.mdx
Attempts to start a second run against a session that already has an open run, catching the raised SessionBusyError and printing its message. Use this to verify that only one run may hold a session at a time; the first run must be awaited after the second attempt fails.
```python
import asyncio
from agentdeck import Agent, Deck
from agentdeck.errors import SessionBusyError
assistant = Agent(name="Assistant", instructions="Keep replies to one short sentence.")
async def main() -> None:
async with Deck(agents=[assistant]) as deck:
first = await deck.runs.start("Assistant", "hello", session_id="conversation-2")
try:
await deck.runs.start("Assistant", "hello again", session_id="conversation-2")
except SessionBusyError as busy:
print(busy)
await first
asyncio.run(main())
```
--------------------------------
### deck.asgi(binding, *bindings)
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/reference/deck.mdx
Returns an ASGI application for serving the deck. The lifespan opens the deck on startup and closes it on shutdown.
```APIDOC
## deck.asgi(binding, *bindings)
### Description
Returns an ASGI application for serving the deck. The lifespan opens the deck on startup and closes it on shutdown, so a served deck needs no separate `async with`.
### Method
Function call returning an ASGI app
### Parameters
- **binding** (Binding) - Required - The first binding to serve.
- ***bindings** (Binding) - Optional - Additional bindings to serve.
### Request Example
```python
app = deck.asgi(Native.http(path="/api")) # uvicorn yourmodule:app
```
### Notes
- Multiple bindings can share one listener.
- If the deck was already opened by the caller, it is left alone.
```
--------------------------------
### Serve a Deck over AG-UI
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/bindings/agui.mdx
Create a Deck from the project and serve it over AG-UI at /agui on port 8000. The target is routed per request via forwardedProps.agentdeck.target.
```python
from agentdeck import Deck
from agentdeck.bindings import AGUI
deck = Deck.from_project()
deck.serve(AGUI.http("/agui"), port=8000)
```
--------------------------------
### Awaiting a Run
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/reference/deck.mdx
Awaiting a run to get its result, including error handling for suspended runs.
```APIDOC
## Awaiting a Run
### Description
Awaiting a run yields the result: a `TurnResult` for an agent, or the body's own return value for a workflow. If the run is suspended (PAUSED or WAITING_ANSWER), awaiting raises `RunSuspendedError` instead of blocking.
### Behavior
- **Success**: Returns the run's result.
- **Suspended**: Raises `RunSuspendedError` (a subclass of `RunStateError`). The exception carries `.pending` with the interrupt's payload for `WAITING_ANSWER`, or `None` for a plain pause.
### Example
```python
from agentdeck.errors import RunSuspendedError
try:
result = await run
except RunSuspendedError as parked:
print(parked.status, parked.pending) # RunStatus.WAITING_ANSWER, {"payload": ..., ...} - or PAUSED, None
```
```
--------------------------------
### GET /runs/{run_id}/pending
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/bindings/native.mdx
Retrieves the pending interrupt result for a run, or null if none.
```APIDOC
## GET /runs/{run_id}/pending
### Description
Retrieves the pending interrupt result for a run, or null if none.
### Method
GET
### Endpoint
/runs/{run_id}/pending
### Parameters
#### Path Parameters
- **run_id** (string) - Required - The unique identifier of the run.
### Response
#### Success Response (200)
- **body** (object or null) - An `InterruptResult` object or `null`.
### Errors
- **404** - Run not found.
- **500** - Internal server error.
```
--------------------------------
### Serve with Terminal.stdio()
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/bindings/terminal.mdx
Use `Deck.from_project().serve(Terminal.stdio())` to serve the deck over stdin/stdout. Equivalent to the `agentdeck chat [target]` CLI command.
```python
from agentdeck import Deck
from agentdeck.bindings import Terminal
deck = Deck.from_project()
deck.serve(Terminal.stdio())
```
--------------------------------
### GET /runs/{run_id}/events
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/bindings/native.mdx
Streams events for a run over SSE, supporting resumption via Last-Event-ID or from_seq.
```APIDOC
## GET /runs/{run_id}/events
### Description
Streams events for a run over SSE, supporting resumption via Last-Event-ID or from_seq.
### Method
GET
### Endpoint
/runs/{run_id}/events
### Parameters
#### Path Parameters
- **run_id** (string) - Required - The unique identifier of the run.
#### Headers
- **Last-Event-ID** (string) - Optional - The ID of the last received event for resumption.
#### Query Parameters
- **from_seq** (integer) - Optional - Sequence number to resume from.
### Response
#### Success Response (200)
- **body** (SSE stream) - Server-Sent Events, including `text.delta` events.
### Errors
- **404** - Run not found.
- **500** - Internal server error.
```
--------------------------------
### Creating a Deck with explicit agents
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/build-your-deck/deck.mdx
Initialize a Deck by explicitly defining a list of agents with their names and instructions.
```python
from agentdeck import Deck, Agent
deck = Deck(
agents=[Agent(name="bot", instructions="Help user.")],
)
```
--------------------------------
### Serve a Deck over multiple bindings with deck.serve()
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/bindings/index.mdx
Serve a Deck over multiple bindings from one call. The `serve` method validates the set of bindings and owns their lifecycle, allowing one process to reach the same runs through three bindings.
```python
from agentdeck import Deck
from agentdeck.bindings import AGUI, Native, Terminal
deck = Deck.from_project()
deck.serve(Native.http("/api"), AGUI.http("/agui"), Terminal.stdio(), port=8000)
```
--------------------------------
### Define a workflow with ctx.ask in Python
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/examples/chat-in-the-terminal.mdx
Defines a `shift_handover` workflow that asks the outgoing operator about an area and returns a handover note. Uses `ctx.ask` with options to enforce answers; if the answer is 'problems', it asks for details. The workflow is discovered from `.agentdeck/` rather than imported.
```python
from agentdeck import WorkflowCtx, workflow
@workflow
async def shift_handover(ctx: WorkflowCtx, area: str) -> str:
"""Write a handover note for one area, asking the outgoing operator what to flag."""
severity = await ctx.ask(
f"how did {area} run this shift?",
options=["quiet", "busy", "problems"],
)
if severity == "problems":
detail = await ctx.ask("what should the next shift look at first?")
return f"{area}: problems. First: {detail}"
return f"{area}: {severity}, nothing to escalate."
```
--------------------------------
### SKILL.md frontmatter and body
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/build-your-deck/skills.mdx
The SKILL.md file for the refund-policy skill. The name in frontmatter must match the directory name if given, and description is required. Both missing or mismatched fail Deck.build() naming the bundle. Only description reaches the agent's instructions up front; the model calls load_skill("refund-policy") to read the body.
```markdown
---
name: refund-policy
description: How to evaluate a refund request - use before approving or denying one.
---
Approve refunds under $50 without escalation. Anything over $50 needs a supervisor tag.
Never approve a refund for an order older than 90 days.
```
--------------------------------
### Serve multiple bindings with deck.serve
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/meet-agentdeck/whats-new-6.mdx
Shows the new front door for serving an AgentDeck application with multiple bindings in one call. Replaces agentdeck-serve and the v1 HTTP routes.
```python
deck.serve(Native.http("/api"), AGUI.http("/agui"), Terminal.stdio(), port=8000)
```
--------------------------------
### Validating context type with ContextTypeError
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/reference/deck.mdx
This example demonstrates how to declare a context type in the Deck constructor and catch a ContextTypeError when the provided context does not match the tool's requirements.
```python
from agentdeck import Agent, Deck, ToolCtx, tool
from agentdeck.errors import ContextTypeError
class Calendar:
def find(self, day: str) -> str:
return f"{day} 09:00"
class Warehouse:
"""A different application environment entirely."""
@tool
def find_slots(day: str, environment: ToolCtx[Calendar]) -> str:
"""Find free appointment slots on a given day."""
return environment.data.find(day)
booking = Agent(name="Booking", instructions="Book things.", tools=[find_slots])
try:
Deck(agents=[booking], context=Warehouse).build()
except ContextTypeError as refused:
print(refused)
```
--------------------------------
### agentdeck runs signal --help output
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/reference/cli.mdx
Help output for the agentdeck runs signal command, which writes a control signal directly into the SQLite ControlPort without a served deck or HTTP call. Requires --control-db and a run_id, with an optional --reason recorded in the run's log.
```text
usage: agentdeck runs signal [-h] --control-db CONTROL_DB [--reason REASON]
run_id {cancel,pause,resume}
positional arguments:
run_id the run to signal
{cancel,pause,resume}
the verb - see Run Control for what each does
options:
-h, --help show this help message and exit
--control-db CONTROL_DB
path to the ControlPort's SQLite file
--reason REASON why, recorded in the run's log with the request
```
--------------------------------
### Embed as ASGI app with deck.asgi() and run with uvicorn
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/bindings/serve.mdx
Returns an ASGI application from `deck.asgi()` for mounting inside an existing service. The accompanying uvicorn command runs the app; `deck.expose()` is the lower-level call that returns the `Exposure` object.
```python
from agentdeck import Deck
from agentdeck.bindings import Native
deck = Deck.from_project()
app = deck.asgi(Native.http("/api"))
```
```bash
uvicorn myapp:app --host 0.0.0.0 --port 8000
```
--------------------------------
### Read run events with run.events()
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/reference/events.mdx
Iterates over a run's event log starting at sequence 0, following new events as they arrive. Prints each event's sequence number and kind.
```python
async for event in run.events(from_seq=0, follow=True):
print(event.seq, event.kind)
```
--------------------------------
### Answer a question with invalid and valid options
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/build-your-deck/workflows.mdx
Answer a question with an option not in the list raises ValueError and does not resume the run; answering with a valid option resumes it. The answerer gets the error and an answer.refused event is logged.
```python
await run.answer("staging") # ValueError, nothing resumed
await run.answer("prod") # lands
```
--------------------------------
### Ask a question with options via ctx.ask
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/build-your-deck/workflows.mdx
Ask a question with a fixed set of options. The options travel with the question so pending runs can render them; an answer not in the list is refused before it is recorded.
```python
env = await ctx.ask("which environment?", options=["dev", "prod"])
```
--------------------------------
### File layout for shift_handover workflow
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/examples/chat-in-the-terminal/README.md
Shows the required file layout for the chat workflow. The workflow.py file must be placed under .agentdeck/workflows/shift_handover/ and contain the @workflow decorator and ctx.ask(...) calls. The file's location registers the workflow; nothing imports it and there is no catalog file.
```text
.agentdeck/
└── workflows/shift_handover/workflow.py # @workflow + ctx.ask(...)
```
--------------------------------
### Stream events without a handle using deck.stream
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/runs-and-control/events.mdx
Streams events and the final result in one pass without needing a run handle. Use this when you only want the output and not the handle. The example prints text deltas as they arrive.
```python
async for event in deck.stream("Jack", question):
if event.kind == "text.delta":
print(event.payload.text, end="")
```
--------------------------------
### deck.serve(binding, *bindings)
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/reference/deck.mdx
Synchronously serves a set of bindings, owning the event loop until the server exits. Validates the bindings and manages their lifecycle.
```APIDOC
## deck.serve(binding, *bindings)
### Description
Serves a set of bindings synchronously, owning the event loop until the server exits. Validates the bindings and manages their lifecycle.
### Method
Synchronous function call
### Parameters
- **binding** (Binding) - Required - The first binding to serve, which is the terminal binding.
- ***bindings** (Binding) - Optional - Additional bindings to serve.
### Request Example
```python
from agentdeck import Deck
from agentdeck.bindings import Terminal
deck = Deck.from_project("./.agentdeck")
deck.serve(Terminal.stdio())
```
### Notes
- This method is blocking and should be called from plain application code without `asyncio.run(...)`.
- The first binding is the terminal binding.
```
--------------------------------
### Define an AgentDeck Agent with Handoffs
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/integrations/openai-agents-sdk.mdx
Create an AgentDeck agent that references the previously defined SDK agent in its handoffs list.
```python
from agentdeck import Agent
triage = Agent(
name="Triage",
instructions="Handle simple requests yourself. Hand off billing disputes to Specialist.",
handoffs=[specialist],
)
```
--------------------------------
### Session already has a run in flight error
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/meet-agentdeck/quickstart.mdx
This error occurs when a second run is started on the same session_id before the first reaches a terminal event. Wait for the first with result = await run, cancel it with await run.cancel(), or give the independent conversation its own session_id.
```text
agentdeck.core.errors.SessionBusyError: session 'quickstart' already has run '' in
flight, so run '' cannot start on it
```
--------------------------------
### POST /runs
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/bindings/native.mdx
Creates a new run for a given target with optional session and key.
```APIDOC
## POST /runs
### Description
Creates a new run for a given target with optional session and key.
### Method
POST
### Endpoint
/runs
### Parameters
#### Request Body
- **target** (string) - Required - The target name.
- **input** (object) - Required - The input data for the run.
- **session_id** (string) - Optional - Session identifier.
- **key** (string) - Optional - Key for the run.
### Request Example
```json
{
"target": "string",
"input": {},
"session_id": "string",
"key": "string"
}
```
### Response
#### Success Response (200)
- **run summary** (object) - Contains `run_id`, `namespace`, `session_id`, `status`, `can`.
#### Response Example
```json
{
"run_id": "string",
"namespace": "string",
"session_id": "string",
"status": "string",
"can": {}
}
```
### Errors
- **422** - Validation error.
- **409** - Conflict.
- **500** - Internal server error.
```
--------------------------------
### Enable Raw SDK Spans
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/docs-site/content/reference/deck.mdx
Configures the LangfuseObserver with sdk_spans=True to capture detailed OpenInference traces for agent, generation, and tool calls.
```python
deck = Deck(agents=[booking], observers=[LangfuseObserver(sdk_spans=True)])
```
--------------------------------
### Execute a deck run with context
Source: https://github.com/agentdecksdk/agentdeck/blob/dev/examples/jack/README.md
Initializes the Deck with the DocsCorpus type and executes a question, allowing the system to validate context types before processing.
```python
async with Deck(agents=[ask], context=DocsCorpus) as deck:
result = await deck.run("Jack", question, context=corpus)
```