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

# Quickstart

> Get Extra running in minutes — engine only, or with conversation history and an embeddable widget.

## Prerequisites

* Docker (recommended) **or** Python 3.11+
* An API key for your LLM provider (Anthropic, Bedrock, etc.)

***

## Engine only

The stateless engine — no database, no widget. Good for embedding into your own backend.

<Steps>
  <Step title="Write your spec">
    Create `agents.yml` (see [YAML Reference](/docs/yaml-spec) for all fields):

    ```yaml theme={null}
    system:
      name: "Support Bot"

    defaults:
      model:
        provider: anthropic
        name: claude-sonnet-4-6

    orchestrators:
      router:
        description: "Routes the user to the right department."
        prompts:
          orchestrator: "prompts/router/orchestrator.md"

    agents:
      orders_agent:
        description: "Handles order status and tracking questions."
        prompts:
          system: "prompts/orders/system.md"

      returns_agent:
        description: "Handles return requests and refunds."
        prompts:
          system: "prompts/returns/system.md"

    graph:
      router:
        orders_agent:
        returns_agent:
    ```
  </Step>

  <Step title="Generate plugin stubs">
    ```bash theme={null}
    docker run --rm \
      -v $(pwd):/workspace \
      -w /workspace \
      ghcr.io/extra-org/extra:latest \
      generate --config agents.yml
    ```

    Creates the `plugins/` folder with stubs for your tools and resolvers. Fill them in with your business logic.
  </Step>

  <Step title="Validate">
    ```bash theme={null}
    docker run --rm \
      -v $(pwd):/workspace \
      -w /workspace \
      ghcr.io/extra-org/extra:latest \
      validate agents.yml
    ```

    Fully offline — no LLM calls, no network. Exits non-zero on any error.
  </Step>

  <Step title="Run">
    ```bash theme={null}
    docker run -d \
      -p 8090:8090 \
      -v $(pwd):/workspace \
      -w /workspace \
      -e ANTHROPIC_API_KEY=sk-... \
      ghcr.io/extra-org/extra:latest \
      serve --config agents.yml
    ```

    Call it:

    ```bash theme={null}
    curl -X POST http://localhost:8090/invoke \
      -H "Content-Type: application/json" \
      -d '{"messages": [{"role": "user", "content": "Where is my order?"}]}'
    ```
  </Step>
</Steps>

***

## With conversation history and widget

Adds persistent conversations, multi-turn sessions, SSE streaming, and an embeddable chat widget.

<Steps>
  <Step title="Same agents.yml">
    No changes to your spec.
  </Step>

  <Step title="Run with widget mode">
    ```bash theme={null}
    docker run -d \
      -p 8100:8100 \
      -v $(pwd):/workspace \
      -w /workspace \
      -e ANTHROPIC_API_KEY=sk-... \
      ghcr.io/extra-org/extra:latest \
      agent-manager --config agents.yml --port 8100
    ```
  </Step>

  <Step title="Embed the widget">
    Drop this into any HTML page — React, Vue, plain HTML, anything:

    ```html theme={null}
    <script type="module" src="http://localhost:8100/widget.js"></script>
    <agent-chat
      title="Support"
      color="#6366f1"
      greeting="Hi! How can I help you today?"
      mode="floating"
      position="bottom-right">
    </agent-chat>
    ```

    The widget handles sessions, streaming, and conversation history automatically.

    <Tip>
      See [Widget](/docs/widget) for all attributes and framework integration guides.
    </Tip>
  </Step>
</Steps>

***

## Comparison

|                      | Engine only       | With widget  |
| -------------------- | ----------------- | ------------ |
| Conversation history | You own it        | Built-in     |
| Sessions             | You manage        | Auto-managed |
| Streaming            | SSE via `/stream` | Built-in     |
| Chat widget          | No                | Yes          |
| Default port         | 8090              | 8100         |

***

## Local development (no Docker)

```bash theme={null}
git clone https://github.com/extra-org/extra.git
cd extra
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

agentctl validate agents.yml
agentctl serve --config agents.yml
```