> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deck.co/llms.txt
> Use this file to discover all available pages before exploring further.

# How Deck works

> Platform architecture, agent orchestration, and the execution model.

Deck provides access to computer use agents and the infrastructure that runs them. Computer use agents operate websites and software like a human would, giving you access and automation for services that lack APIs to integrate against.

## Architecture

```mermaid theme={null}
sequenceDiagram
    participant App as Your Application
    participant API as Deck API
    participant Agent as Agent
    participant Site as External Source

    App->>API: Run task
    API->>API: Validate input schema
    API-->>App: 201, task_run (status: queued)
    API->>Agent: Assign to agent
    Agent->>Site: Navigate, interact, extract
    Site-->>Agent: Page content
    Agent->>API: Structured output
    API-->>App: Event: task_run.completed
```

Every operation follows this pattern. Your application talks to the REST API. The API validates the request, queues the work, and delegates to a managed agent. The agent does the work and reports back through the API and event deliveries.

## Compute orchestration

Deck provisions isolated sessions on demand. When you run a task, Deck spins up a session, optionally authenticates using stored credentials, and executes the required actions.

### Session management

A [session](/concepts/sessions) is created automatically when a task runs. Deck connects to the source, optionally authenticates using the [credential](/concepts/credentials), executes the work, and cleans up the session when done. You can reuse a session across multiple task runs by passing the `session_id`, which avoids re-authentication and is faster.

Sessions are cleaned up automatically after the last task run completes or after a period of inactivity.

## Execution model

All work in Deck is asynchronous. When you call the API to run a task, you get an immediate response with a `queued` status. The actual work happens in the background.

<Steps>
  <Step title="Request">
    Your application calls the Deck API with the required parameters. Deck validates the input against the task's schema and rejects malformed requests synchronously.
  </Step>

  <Step title="Execute">
    Deck assigns an agent, which navigates the target website and performs the defined actions: clicking, typing, reading, downloading.
  </Step>

  <Step title="Return">
    The agent extracts data according to the task's output schema. Deck validates the output, stores it on the task run, and emits a completion event.
  </Step>
</Steps>

## Deterministic output

Every task defines an input schema and an output schema. Regardless of how the underlying website renders its data, Deck returns a consistent JSON structure. The output schema guides what the agent extracts, but fields may be `null` if the data isn't available on the source.

This contract means you write your integration code once and it works across sources. A "fetch reservations" task returns the same shape whether the source is Hilton, Marriott, or Hyatt.

## Handling interactions

Some operations require human input midway through execution. MFA codes, security questions, and other verification prompts. The agent can't proceed without your user's involvement.

When this happens, Deck pauses the agent and notifies your application:

1. The agent encounters a prompt it can't resolve autonomously
2. Deck sets the status to `interaction_required` and emits an event
3. Your application collects the required input from the user
4. You submit the input via the interaction endpoint
5. The agent resumes exactly where it left off

The session stays open while waiting.

## Event-driven integration

Deck is built for event-driven architectures. Rather than polling for status changes, you register event destinations and Deck pushes events to your infrastructure as they happen.

Events cover the full lifecycle: credential verification, sessions starting and completing, task runs progressing, interactions required, deliveries failing. Every event includes a summary of the resource so your handler has the context it needs without additional API calls.

Deck delivers events to webhooks, AWS SQS, GCP Pub/Sub, and other cloud-native destinations, with built-in retries and delivery tracking.

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/guides/quickstart">
    Create an agent, store credentials, and run your first task.
  </Card>

  <Card title="Concepts" icon="compass" href="/concepts/overview">
    Agents, sources, credentials, sessions, tasks, and how they fit together.
  </Card>

  <Card title="Building your auth flow" icon="key" href="/guides/building-auth-ui">
    Collect credentials and manage credential state.
  </Card>

  <Card title="Using the API" icon="code" href="/api/using-the-api">
    Authentication, pagination, idempotency, and error handling.
  </Card>
</CardGroup>