Skip to Content
Meet AgentDeckQuickstart

Quickstart

Build a Deck, start a Run, and watch its events.

◆ 01 : INSTALL

pip install agentdeck-sdk

◆ 02 : BUILD YOUR DECK

Compose an agent into a Deck:

from agentdeck import Agent, Deck
 
agent = Agent(
    name="assistant",
    model="gpt-4o-mini",
    instructions="You are a concise assistant.",
)
 
deck = Deck(agents=[agent])

◆ 03 : START A RUN

Execute the agent within the Deck’s runtime context:

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)

follow=True streams until the run reaches a terminal event. Without it you get only what the log already holds, which for a run this young is one event. run.status() is a coroutine, not a property.

◆ 04 : WATCH WHAT HAPPENED

Running the script emits an ordered sequence of lifecycle and content events:

run.started
text.delta
usage.reported
message.completed
run.completed

Status: completed
Result: Hello!

text.delta is one streamed fragment and there is usually more than one; message.completed carries the finished text. Every kind a run can emit is listed in the events reference.

What you just used

  • Agent: Your executable component.
  • Deck: The composition root for your agents, workflows, tools, and skills.
  • Run: A first-class execution you can observe and control.
  • Events: The ordered record of what happened during that Run.
A RUN IS CONTROLLABLE

A Run is not just a return value. It is a living, controllable execution with safe-point pause, resume, and cancellation:

await run.pause()
await run.resume()
await run.cancel()

Next

OverviewMental Model