> ## 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 agents connect where APIs don't. They sign in to websites and services on behalf of your users and operate them like a person would, so you can automate services that have no API to integrate against.

## Architecture

```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': {'darkMode': true, 'background': '#0D100F', 'primaryColor': '#1B1E1D', 'primaryTextColor': '#F6F6F6', 'primaryBorderColor': '#323534', 'lineColor': '#60917E', 'actorBkg': '#1B1E1D', 'actorBorder': '#323534', 'actorTextColor': '#F6F6F6', 'actorLineColor': '#323534', 'signalColor': '#60917E', 'signalTextColor': '#F6F6F6'}}}%%
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.

## Agent 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](https://docs.deck.co/concepts/sessions.md) is created automatically when a task runs. Deck connects to the source, optionally authenticates using the [credential](https://docs.deck.co/concepts/credentials.md), and executes the work. The session stays open after the run, so you can reuse it for more task runs by passing its `session_id` and skip signing in again.

Sessions close after 10 minutes with no task running.

## 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.

**1. 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.

**2. Execute**

Deck assigns an agent, which navigates the target website and performs the defined actions: clicking, typing, reading, downloading.

**3. 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.

Runs don't always start with a direct API call. A [workflow](https://docs.deck.co/concepts/workflows.md) chains tasks, running each step as its own task run, and a [trigger](https://docs.deck.co/concepts/triggers.md) starts a task or workflow on a schedule across your credentials. Each run follows the same cycle.

## Structured 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, such as 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, destinations being deactivated. 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

> [card] [Quickstart](https://docs.deck.co/guides/quickstart.md)
>
> Create an agent, store credentials, and run your first task.

> [card] [Concepts](https://docs.deck.co/concepts/overview.md)
>
> Agents, sources, credentials, sessions, tasks, and how they fit together.

> [card] [Building your auth flow](https://docs.deck.co/guides/building-auth-ui.md)
>
> Collect credentials and manage credential state.

> [card] [Using the API](https://docs.deck.co/api/using-the-api.md)
>
> Authentication, pagination, idempotency, and error handling.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.