Skip to main content

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

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:
2

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

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

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?"}]}'

​
With conversation history and widget

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

Same agents.yml

No changes to your spec.
2

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
3

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 onlyWith widget
Conversation historyYou own itBuilt-in
SessionsYou manageAuto-managed
StreamingSSE via /streamBuilt-in
Chat widgetNoYes
Default port80908100

​
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