Turn your app into an agentic product — from one YAML file.
Give any application a smart, domain-aware agent layer, without building the engine yourself.

Documentation · Quick Start · How it works · Learn more · Contributing

---

What Extra is

Extra is a lightweight engine that adds an agentic layer to any application. You describe your agents in a simple YAML file — what each one is responsible for and what it can access — and Extra turns that into a running system that routes each request to the right agent and answers it accurately.

Every agent has a single, clear responsibility and is scoped to its own domain, with its own prompt, tools, and data. That scoping is what keeps answers grounded: a request about billing never reaches the returns agent, so there's no context bleeding between domains and no hallucinated hand-off. You get tools, MCP servers, authentication, provider connectors, and observability out of the box — so your app can be agentic in a day, not a quarter.

How it works

You define a small graph in YAML: one orchestrator that routes, and focused agents that do the work. Extra runs it — picking the right agent per request and keeping each one inside its own domain.

flowchart TD
    U([User request]) --> R{{Orchestrator<br/>routes by domain}}
    R -->|billing| A1[Billing agent]
    R -->|orders| A2[Orders agent]
    R -->|docs| A3[Docs agent]

    A1 --- P1[/prompt · tools · MCP · auth/]
    A2 --- P2[/prompt · tools · MCP · auth/]
    A3 --- P3[/prompt · tools · MCP · auth/]

    A1 --> RESP([Grounded response])
    A2 --> RESP
    A3 --> RESP

Loading

Each agent only sees its own tools and data, so the model stays focused and answers correctly for that part of your business. Add a new capability by adding an agent to the file — no routing code to write.

Here's the same idea in YAML:

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

agents:
  orders_agent:
    description: "Handles order status and tracking."
    prompts:
      system: "prompts/orders_agent.md"
    tools: [get_order_status]
    mcps: [orders_api]

  returns_agent:
    description: "Handles returns and refunds."
    prompts:
      system: "prompts/returns_agent.md"
    tools: [create_return]

graph:
  router:
    orders_agent:
    returns_agent:

That's the whole system. Extra validates it, compiles it, and serves it as an API. You only write your own business logic — the tool and connector stubs Extra generates for you.

Quick Start

Write your agents.yml (like the one above), then generate the plugin stubs and serve it:

# Generate tool/resolver stubs from your spec, then fill in your logic
docker run --rm -v "$(pwd):/workspace" -w /workspace \
  ghcr.io/extra-org/extra:latest generate --config agents.yml

# Serve your system
docker run -p 8090:8090 -v "$(pwd):/workspace" -w /workspace \
  -e ANTHROPIC_API_KEY=sk-... \
  ghcr.io/extra-org/extra:latest serve --config agents.yml

Your agent API is live at http://localhost:8090. For the widget, local (non-Docker) setup, and the full walkthrough, see the Quickstart docs.

Agent setup skill

If you use Claude Code, Cursor, or Codex, you can install the official Extra setup skill to create or repair an extra project configuration interactively. The same open Agent Skills-format skill works across supported agents; it helps set up agents.yml, prompts, MCPs, tools, resolvers, plugins, generation, Docker/local execution, and validation.

List available skills:

npx skills add extra-org/extra-skills --list

Install for Claude Code:

npx skills add extra-org/extra-skills --skill '*' -a claude-code

Install for Cursor:

npx skills add extra-org/extra-skills --skill '*' -a cursor

Install for Codex:

npx skills add extra-org/extra-skills --skill '*' -a codex

Install for all three:

npx skills add extra-org/extra-skills --skill '*' -a claude-code -a cursor -a codex

Add -g to install globally for the current user instead of into the current project.

In Claude Code, open your project:

claude

Then run:

/extra-setup

Examples:

/extra-setup simple banking demo
/extra-setup repair my agents.yml
/extra-setup configure MCP tools and resolvers

In Cursor or Codex, install the same extra-setup skill and ask the agent to use it:

Use the extra-setup skill to create a simple banking demo for this project.

If your current Cursor or Codex version supports direct skill invocation, use that agent's documented invocation flow.

The skill repository is available at extra-org/extra-skills.

What you get out of the box

• Domain-focused agents — one responsibility each, scoped to their own tools and data, so answers stay accurate.
• Automatic routing — declare the graph; Extra sends each request to the right agent.
• Tools, MCP & auth — connect any tool or MCP server, with tokens that never reach the model or the logs.
• Observability — a full trace of every request.

Learn more

• Full example — build a complete multi-agent system step by step.
• YAML reference — every field you can declare.
• Architecture — how routing and execution work under the hood.

Contributing

This repository is agent-first — if you're an AI coding agent, read AGENTS.md before making changes. Human contributors should start there too, then run make check before opening a PR.

License

MIT