Quickstart

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.

Write your spec

Create agents.yml (see YAML Reference for all fields):

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:

Generate plugin stubs

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.

Validate

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.

Run

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:

curl -X POST http://localhost:8090/invoke \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Where is my order?"}]}'

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

Same agents.yml

No changes to your spec.

Run with widget mode

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

Embed the widget

Drop this into any HTML page — React, Vue, plain HTML, anything:

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

See Widget for all attributes and framework integration guides.

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)

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

Get Started

Core Concepts

Features

Widget

Reference

Prerequisites

Engine only

With conversation history and widget

Comparison

Local development (no Docker)

​Prerequisites

​Engine only

​With conversation history and widget

​Comparison

​Local development (no Docker)

Prerequisites

Engine only

With conversation history and widget

Comparison

Local development (no Docker)