From dd4ca693c4f4414905f105351e9477c5fef3df9b Mon Sep 17 00:00:00 2001 From: Asaf Varon Date: Sat, 25 Jul 2026 18:56:26 +0300 Subject: [PATCH 01/10] docs(readme): reposition and simplify product README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Lead with the product outcome — "Make your product queryable" — instead of the framework, then cut the README to what a developer needs to decide whether Extra is relevant before moving into the docs. - Restructure to Hero → Why Extra → Quick Start → Features → Architecture → Who it's for → Contributing. - State developer outcomes rather than listing primitives. - Quick Start is the smallest genuinely runnable system: one agent, no orchestrator, one prompt file, one command. Verified end-to-end. - Move advanced onboarding to documentation links: generate/stub workflow, MCP setup, agent-manager, conversation history, widget install, non-Docker setup, and the extra-setup coding-agent skill. - Fix the invoke payload: the API takes {"message": "..."}. - Keep security wording precise — the model cannot grant itself access to protected capabilities, since denied nodes are removed from the router's options. Co-Authored-By: Claude --- README.md | 236 +++++++++++++++++++++--------------------------------- 1 file changed, 93 insertions(+), 143 deletions(-) diff --git a/README.md b/README.md index 6f719b41..40494bad 100644 --- a/README.md +++ b/README.md @@ -5,10 +5,11 @@

+

Make your product queryable.

+

- 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. + Turn the APIs, tools, and business logic you already have into a secure AI + interface inside your product.

@@ -18,195 +19,144 @@

- Documentation · Quick Start · - How it works · - Learn more · + Why Extra · + Who it's for · + Documentation · Contributing

--- -## What Extra is +Your users shouldn't have to learn your UI to get an answer out of it. -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. +Extra lets them ask questions and trigger actions using the APIs and business +logic you already built. -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. +Define the system in YAML. Extra handles routing, orchestration, and access +boundaries while your logic and credentials stay in your backend. -## How it works +## Why Extra -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. +**Ship faster.** Define your agent system instead of rebuilding routing, +streaming, tool execution, and tracing. -```mermaid -flowchart TD - U([User request]) --> R{{Orchestrator
routes by domain}} - R -->|billing| A1[Billing agent] - R -->|orders| A2[Orders agent] - R -->|docs| A3[Docs agent] +**Reuse your backend.** Connect the APIs, services, and business logic you +already have. - A1 --- P1[/prompt · tools · MCP · auth/] - A2 --- P2[/prompt · tools · MCP · auth/] - A3 --- P3[/prompt · tools · MCP · auth/] +**Keep access control outside the model.** Authorization runs in trusted code — +the model cannot grant itself access to protected capabilities. - A1 --> RESP([Grounded response]) - A2 --> RESP - A3 --> RESP -``` +**Avoid model lock-in.** Switch model providers through configuration rather +than rewriting your product. -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. +**Embed it in your product.** Serve the system as an API or as an embeddable +chat component. -Here's the same idea in YAML: +## Quick Start + +You need Docker and an API key for your model provider. + +Create `agents.yml` — a single agent is a complete system: ```yaml -orchestrators: - router: - description: "Routes each request to the right department." - prompts: - orchestrator: "prompts/router.md" +system: + name: "Support Bot" -agents: - orders_agent: - description: "Handles order status and tracking." - prompts: - system: "prompts/orders_agent.md" - tools: [get_order_status] - mcps: [orders_api] +defaults: + model: + provider: anthropic + name: claude-sonnet-4-6 - returns_agent: - description: "Handles returns and refunds." +agents: + support_agent: + description: "Answers questions about orders and returns." prompts: - system: "prompts/returns_agent.md" - tools: [create_return] + system: "prompts/support.md" graph: - router: - orders_agent: - returns_agent: + support_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. +Write the prompt it references, in `prompts/support.md`: -## Quick Start +```markdown +You are a support agent for an online store. Answer questions about orders +and returns. +``` -Write your `agents.yml` (like the one above), then generate the plugin stubs -and serve it: +Run it: ```bash -# 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](https://docs.extra-ai.co/docs/quickstart). - -### 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: - -```bash -npx skills add extra-org/extra-skills --list -``` - -Install for Claude Code: +Your system is live at `http://localhost:8090` — send it a message with +`POST /invoke`. -```bash -npx skills add extra-org/extra-skills --skill '*' -a claude-code -``` +Tools, MCP servers, routing between agents, conversation history, and the chat +widget are covered in the +[Quickstart](https://docs.extra-ai.co/docs/quickstart). -Install for Cursor: +## Features -```bash -npx skills add extra-org/extra-skills --skill '*' -a cursor -``` +- YAML-defined agents and routing +- Local Python tools and remote MCP servers +- Per-node authorization +- Human-in-the-loop tool approvals +- Anthropic, OpenAI, Gemini, and Bedrock +- Streaming API +- Structured logs and Langfuse tracing +- Embeddable web component -Install for Codex: +## Architecture -```bash -npx skills add extra-org/extra-skills --skill '*' -a codex -``` - -Install for all three: +An orchestrator routes each request; focused agents do the domain work. Each +agent is scoped to its own prompt, tools, and domain data, which keeps answers +grounded in the right part of your business. -```bash -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: - -```bash -claude -``` - -Then run: - -```text -/extra-setup -``` +```mermaid +flowchart TD + U([User request]) --> R{{Orchestrator
routes by domain}} + R -->|billing| A1[Billing agent] + R -->|orders| A2[Orders agent] + R -->|docs| A3[Docs agent] -Examples: + A1 --- P1[/prompt · tools · MCP · auth/] + A2 --- P2[/prompt · tools · MCP · auth/] + A3 --- P3[/prompt · tools · MCP · auth/] -```text -/extra-setup simple banking demo -/extra-setup repair my agents.yml -/extra-setup configure MCP tools and resolvers + A1 --> RESP([Grounded response]) + A2 --> RESP + A3 --> RESP ``` -In Cursor or Codex, install the same `extra-setup` skill and ask the agent to -use it: +Extra runs the graph. Your project's plugins hold the trusted business logic — +tools, access checks, and the values resolved into prompts. -```text -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. +- **[Tutorial](https://docs.extra-ai.co/docs/tutorial)** — build a complete multi-agent system step by step. +- **[YAML reference](https://docs.extra-ai.co/docs/yaml-spec)** — every field you can declare. +- **[Architecture](https://docs.extra-ai.co/docs/architecture)** — how routing and execution work. +- **[`examples/`](examples/)** — runnable specs, including an enterprise knowledge assistant. -The skill repository is available at -[extra-org/extra-skills](https://github.com/extra-org/extra-skills). +## Who is Extra for? -## What you get out of the box +Extra is built for teams adding an AI interface to: -- **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. +- Existing SaaS products +- Internal enterprise systems +- Customer support workflows +- Multi-step business operations +- Multi-tenant products with strict access boundaries -## Learn more +### Extra may be unnecessary if -- **[Full example](https://docs.extra-ai.co/docs/tutorial)** — build a complete multi-agent system step by step. -- **[YAML reference](https://docs.extra-ai.co/docs/yaml-spec)** — every field you can declare. -- **[Architecture](https://docs.extra-ai.co/docs/architecture)** — how routing and execution work under the hood. +- You need a single prompt with a few simple tools. +- You are building a chatbot with no product or backend integration. +- You need full low-level control over the orchestration runtime. +- Your workload is primarily batch or offline processing. ## Contributing From 24de784d39bd8accde18e7dc9796aae2806b53c5 Mon Sep 17 00:00:00 2001 From: Asaf Varon Date: Sat, 8 Aug 2026 11:43:00 +0300 Subject: [PATCH 02/10] =?UTF-8?q?docs(readme):=20address=20PR=20#47=20revi?= =?UTF-8?q?ew=20=E2=80=94=20product=20hero,=20graph=20value,=20runnable=20?= =?UTF-8?q?quick=20start?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rework the README around what Extra adds to an existing product, and make the Quick Start a flow you can actually run end to end. - Hero: replace "Make your product queryable" with a product-focused headline. - Lead: "Define and deploy your agentic system from YAML." - Why Extra: drop "Avoid model lock-in", reword the embedding item, and add an explicit graph-orchestration benefit. - Quick Start: replace the single-agent example with one orchestrator routing to two focused agents, add the `agentctl generate` step that scaffolds the prompt and plugin stubs, run the system with `agent-manager` on port 8100, and show both the playground and exact conversation API calls. - Architecture: state the explicit graph model — orchestrators route to focused agents, each owning its prompts, tools, MCPs, and boundaries. - Tighten throughout: merge the prompt stubs and API calls into single blocks and condense the positioning sections. Verified against the codebase: the YAML passes `agentctl validate`, `generate` scaffolds the referenced prompts, and the documented API calls hit the real conversation routes. Co-Authored-By: Claude Opus 5 --- README.md | 131 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 84 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 40494bad..2c2ba77c 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@

-

Make your product queryable.

+

Add AI to the product you already built.

Turn the APIs, tools, and business logic you already have into a secure AI @@ -28,13 +28,13 @@ --- -Your users shouldn't have to learn your UI to get an answer out of it. +Your users shouldn't have to learn your UI to get an answer out of it. Extra +lets them ask questions and trigger actions using the APIs and business logic +you already built. -Extra lets them ask questions and trigger actions using the APIs and business -logic you already built. - -Define the system in YAML. Extra handles routing, orchestration, and access -boundaries while your logic and credentials stay in your backend. +Define and deploy your agentic system from YAML. Extra handles routing, +orchestration, and access boundaries while your logic and credentials stay in +your backend. ## Why Extra @@ -47,75 +47,119 @@ already have. **Keep access control outside the model.** Authorization runs in trusted code — the model cannot grant itself access to protected capabilities. -**Avoid model lock-in.** Switch model providers through configuration rather -than rewriting your product. +**Graph-based orchestration.** Extra routes requests through an explicit graph +of orchestrators and focused agents, keeping execution predictable, observable, +easy to debug, and easy to extend. -**Embed it in your product.** Serve the system as an API or as an embeddable -chat component. +**Add it to your product.** Embed the system as a chat widget or expose it +through an API. ## Quick Start You need Docker and an API key for your model provider. -Create `agents.yml` — a single agent is a complete system: +Create `agents.yml` — an orchestrator that routes to two focused agents: ```yaml system: - name: "Support Bot" + name: "Support Assistant" defaults: model: provider: anthropic name: claude-sonnet-4-6 +orchestrators: + support_router: + description: "Routes each request to the agent that owns it." + prompts: + orchestrator: prompts/support_router/orchestrator.md + agents: - support_agent: - description: "Answers questions about orders and returns." + orders_agent: + description: "Answers questions about orders, shipping, and returns." + prompts: + system: prompts/orders_agent/system.md + + billing_agent: + description: "Answers questions about invoices, plans, and refunds." prompts: - system: "prompts/support.md" + system: prompts/billing_agent/system.md +# Indentation is the hierarchy: the orchestrator routes to both agents. graph: - support_agent: + support_router: + orders_agent: + billing_agent: +``` + +Scaffold the prompt and plugin stubs the YAML references. It never overwrites a +file you already wrote: + +```bash +agentctl generate --config agents.yml + +# or via the Docker image, which supplies the `agentctl` prefix for you: +docker run --rm -v "$(pwd):/workspace" -w /workspace \ + ghcr.io/extra-org/extra:latest generate --config agents.yml ``` -Write the prompt it references, in `prompts/support.md`: +Fill in the three prompt stubs it created: ```markdown -You are a support agent for an online store. Answer questions about orders -and returns. + +Route orders, shipping, and returns to orders_agent. +Route invoices, plans, and refunds to billing_agent. + + +You answer questions about orders, shipping, and returns. + + +You answer questions about invoices, plans, and refunds. ``` -Run it: +Run it with Agent Manager, which serves the conversation API, history, and the +chat widget: ```bash -docker run -p 8090:8090 -v "$(pwd):/workspace" -w /workspace \ +docker run -p 8100:8100 -v "$(pwd):/workspace" -w /workspace \ -e ANTHROPIC_API_KEY=sk-... \ - ghcr.io/extra-org/extra:latest serve --config agents.yml + ghcr.io/extra-org/extra:latest \ + agent-manager --config agents.yml --port 8100 ``` -Your system is live at `http://localhost:8090` — send it a message with -`POST /invoke`. +Talk to it in the browser at **http://localhost:8100/playground**, or over the +API — create a conversation with an id you choose, then send it a message: + +```bash +curl -X POST http://localhost:8100/conversations \ + -H "Content-Type: application/json" \ + -d '{"session_id":"readme-demo"}' -Tools, MCP servers, routing between agents, conversation history, and the chat -widget are covered in the +curl -X POST http://localhost:8100/conversations/readme-demo/messages \ + -H "Content-Type: application/json" \ + -d '{"message":"Tell me about my system"}' +``` + +Tools, MCP servers, deeper routing, per-node authorization, and embedding the +chat widget are covered in the [Quickstart](https://docs.extra-ai.co/docs/quickstart). ## Features - YAML-defined agents and routing - Local Python tools and remote MCP servers -- Per-node authorization -- Human-in-the-loop tool approvals +- Per-node authorization and human-in-the-loop tool approvals - Anthropic, OpenAI, Gemini, and Bedrock -- Streaming API +- Streaming API and embeddable web component - Structured logs and Langfuse tracing -- Embeddable web component ## Architecture -An orchestrator routes each request; focused agents do the domain work. Each -agent is scoped to its own prompt, tools, and domain data, which keeps answers -grounded in the right part of your business. +Extra is built around an explicit graph you declare in YAML. Orchestrators route +each request to focused agents, and every agent owns its own prompts, tools, MCP +servers, and boundaries. Nothing routes implicitly — which keeps answers grounded +in the right part of your business, and every run predictable and traceable. ```mermaid flowchart TD @@ -143,20 +187,13 @@ tools, access checks, and the values resolved into prompts. ## Who is Extra for? -Extra is built for teams adding an AI interface to: - -- Existing SaaS products -- Internal enterprise systems -- Customer support workflows -- Multi-step business operations -- Multi-tenant products with strict access boundaries - -### Extra may be unnecessary if +Teams adding an AI interface to existing SaaS products, internal enterprise +systems, customer support workflows, or multi-tenant products with strict access +boundaries. -- You need a single prompt with a few simple tools. -- You are building a chatbot with no product or backend integration. -- You need full low-level control over the orchestration runtime. -- Your workload is primarily batch or offline processing. +It may be unnecessary if you need a single prompt with a few tools, a chatbot +with no backend integration, low-level control over the orchestration runtime, +or batch processing. ## Contributing From d72f8a27ad597164c459e961e6409e877ef7d519 Mon Sep 17 00:00:00 2001 From: Asaf Varon Date: Sat, 8 Aug 2026 12:11:38 +0300 Subject: [PATCH 03/10] fix: explain why using extra --- README.md | 53 ++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 46 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 2c2ba77c..33c19067 100644 --- a/README.md +++ b/README.md @@ -8,8 +8,8 @@

Add AI to the product you already built.

- Turn the APIs, tools, and business logic you already have into a secure AI - interface inside your product. + Turn the APIs, tools, and business logic you already have into an AI-powered + assistant — a team of AI specialists inside your product.

@@ -20,6 +20,7 @@

Quick Start · + Why not a chatbot · Why Extra · Who it's for · Documentation · @@ -29,13 +30,51 @@ --- Your users shouldn't have to learn your UI to get an answer out of it. Extra -lets them ask questions and trigger actions using the APIs and business logic -you already built. +lets them ask questions, trigger actions, and complete multi-step workflows +using the APIs and business logic you already built. Define and deploy your agentic system from YAML. Extra handles routing, orchestration, and access boundaries while your logic and credentials stay in your backend. +## Why not just use a chatbot? + +A chatbot is usually one general-purpose model with one prompt and one set of +tools. It can answer questions *about* your product. It doesn't *use* your +product. + +Extra turns your product into a team of AI specialists. Instead of one AI trying +to understand your entire product, you build focused agents that each own a +specific domain — a billing specialist, a support specialist, an account +specialist, a technical specialist, a sales specialist — and an orchestrator that +reads the user's intent and routes each request to the right one. + +Each specialist has its own prompt and instructions, tools, APIs, MCP servers, +business context, and permissions and access boundaries. It gets exactly what its +domain needs, and nothing else. + +The result is an AI-powered assistant that doesn't only answer questions. It can: + +- understand the user's intent +- route the request to the right specialist +- use your product's APIs and tools +- access the right business context +- perform actions and carry multi-step workflows through to the end +- return a focused answer or decision + +``` +Regular chatbot + User → General AI → Answer + +Extra + User → AI-powered assistant → Orchestrator → Specialist AI + → tools / APIs / MCP / business data → decision, action, or answer +``` + +Users feel like they're talking to a product-aware specialist inside your +product, not a generic chatbot — one with the domain expertise to help them make +faster, better-informed decisions. + ## Why Extra **Ship faster.** Define your agent system instead of rebuilding routing, @@ -149,7 +188,7 @@ chat widget are covered in the - YAML-defined agents and routing - Local Python tools and remote MCP servers -- Per-node authorization and human-in-the-loop tool approvals +- Per-node authorization and human-in-the-loop approval workflows - Anthropic, OpenAI, Gemini, and Bedrock - Streaming API and embeddable web component - Structured logs and Langfuse tracing @@ -188,8 +227,8 @@ tools, access checks, and the values resolved into prompts. ## Who is Extra for? Teams adding an AI interface to existing SaaS products, internal enterprise -systems, customer support workflows, or multi-tenant products with strict access -boundaries. +systems, customer support and multi-step business workflows, or multi-tenant +products with strict access boundaries. It may be unnecessary if you need a single prompt with a few tools, a chatbot with no backend integration, low-level control over the orchestration runtime, From 00d1f86b9a50f7891a4d428986d4f6f1958c4f0d Mon Sep 17 00:00:00 2001 From: Asaf Varon Date: Sat, 8 Aug 2026 12:13:57 +0300 Subject: [PATCH 04/10] Revert "fix: explain why using extra" This reverts commit d72f8a27ad597164c459e961e6409e877ef7d519. --- README.md | 53 +++++++---------------------------------------------- 1 file changed, 7 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 33c19067..2c2ba77c 100644 --- a/README.md +++ b/README.md @@ -8,8 +8,8 @@

Add AI to the product you already built.

- Turn the APIs, tools, and business logic you already have into an AI-powered - assistant — a team of AI specialists inside your product. + Turn the APIs, tools, and business logic you already have into a secure AI + interface inside your product.

@@ -20,7 +20,6 @@

Quick Start · - Why not a chatbot · Why Extra · Who it's for · Documentation · @@ -30,51 +29,13 @@ --- Your users shouldn't have to learn your UI to get an answer out of it. Extra -lets them ask questions, trigger actions, and complete multi-step workflows -using the APIs and business logic you already built. +lets them ask questions and trigger actions using the APIs and business logic +you already built. Define and deploy your agentic system from YAML. Extra handles routing, orchestration, and access boundaries while your logic and credentials stay in your backend. -## Why not just use a chatbot? - -A chatbot is usually one general-purpose model with one prompt and one set of -tools. It can answer questions *about* your product. It doesn't *use* your -product. - -Extra turns your product into a team of AI specialists. Instead of one AI trying -to understand your entire product, you build focused agents that each own a -specific domain — a billing specialist, a support specialist, an account -specialist, a technical specialist, a sales specialist — and an orchestrator that -reads the user's intent and routes each request to the right one. - -Each specialist has its own prompt and instructions, tools, APIs, MCP servers, -business context, and permissions and access boundaries. It gets exactly what its -domain needs, and nothing else. - -The result is an AI-powered assistant that doesn't only answer questions. It can: - -- understand the user's intent -- route the request to the right specialist -- use your product's APIs and tools -- access the right business context -- perform actions and carry multi-step workflows through to the end -- return a focused answer or decision - -``` -Regular chatbot - User → General AI → Answer - -Extra - User → AI-powered assistant → Orchestrator → Specialist AI - → tools / APIs / MCP / business data → decision, action, or answer -``` - -Users feel like they're talking to a product-aware specialist inside your -product, not a generic chatbot — one with the domain expertise to help them make -faster, better-informed decisions. - ## Why Extra **Ship faster.** Define your agent system instead of rebuilding routing, @@ -188,7 +149,7 @@ chat widget are covered in the - YAML-defined agents and routing - Local Python tools and remote MCP servers -- Per-node authorization and human-in-the-loop approval workflows +- Per-node authorization and human-in-the-loop tool approvals - Anthropic, OpenAI, Gemini, and Bedrock - Streaming API and embeddable web component - Structured logs and Langfuse tracing @@ -227,8 +188,8 @@ tools, access checks, and the values resolved into prompts. ## Who is Extra for? Teams adding an AI interface to existing SaaS products, internal enterprise -systems, customer support and multi-step business workflows, or multi-tenant -products with strict access boundaries. +systems, customer support workflows, or multi-tenant products with strict access +boundaries. It may be unnecessary if you need a single prompt with a few tools, a chatbot with no backend integration, low-level control over the orchestration runtime, From 127199bafda4dbea29875f61188a8bb7001f20a4 Mon Sep 17 00:00:00 2001 From: Asaf Varon Date: Sat, 8 Aug 2026 12:59:45 +0300 Subject: [PATCH 05/10] docs: simplify README messaging and clarify Extra's AI specialist architecture --- README.md | 69 ++++++++++++++++++++++++------------------------------- 1 file changed, 30 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index 2c2ba77c..87b1869f 100644 --- a/README.md +++ b/README.md @@ -5,11 +5,10 @@

-

Add AI to the product you already built.

+

Turn your product into an AI-powered assistant that understands your business.

- Turn the APIs, tools, and business logic you already have into a secure AI - interface inside your product. + Extra lets you build AI-powered assistants that understand your workflows, use your existing APIs and business logic, and delegate work to AI specialists.

@@ -21,38 +20,35 @@

Quick Start · Why Extra · - Who it's for · Documentation · Contributing

--- +Instead of navigating complex UIs, users simply ask. -Your users shouldn't have to learn your UI to get an answer out of it. Extra -lets them ask questions and trigger actions using the APIs and business logic -you already built. +Extra translates those requests into your existing APIs, business logic, +and workflows. -Define and deploy your agentic system from YAML. Extra handles routing, -orchestration, and access boundaries while your logic and credentials stay in -your backend. ## Why Extra -**Ship faster.** Define your agent system instead of rebuilding routing, -streaming, tool execution, and tracing. +Most AI frameworks start with prompts. -**Reuse your backend.** Connect the APIs, services, and business logic you -already have. +Extra starts with your product. -**Keep access control outside the model.** Authorization runs in trusted code — -the model cannot grant itself access to protected capabilities. +It connects your existing backend to a network of focused AI specialists. -**Graph-based orchestration.** Extra routes requests through an explicit graph -of orchestrators and focused agents, keeping execution predictable, observable, -easy to debug, and easy to extend. +* **Specialized by design.** Each specialist understands one part of your business. + +* **Built on your backend.** Your existing APIs, tools, and services remain the source of truth. + +* **Explicit workflows.** Requests move through predictable, inspectable execution paths. + +* **Authorization outside the model.** Access decisions stay in trusted code. + +* **Easy to embed.** Expose Extra through an API or add it directly to your product. -**Add it to your product.** Embed the system as a chat widget or expose it -through an API. ## Quick Start @@ -147,19 +143,23 @@ chat widget are covered in the ## Features -- YAML-defined agents and routing -- Local Python tools and remote MCP servers -- Per-node authorization and human-in-the-loop tool approvals +- AI specialists +- Workflow orchestration +- Local tools and MCP +- Authorization outside the LLM +- Human approvals +- Streaming API +- Embeddable chat widget - Anthropic, OpenAI, Gemini, and Bedrock -- Streaming API and embeddable web component -- Structured logs and Langfuse tracing +- Langfuse tracing ## Architecture -Extra is built around an explicit graph you declare in YAML. Orchestrators route -each request to focused agents, and every agent owns its own prompts, tools, MCP -servers, and boundaries. Nothing routes implicitly — which keeps answers grounded -in the right part of your business, and every run predictable and traceable. +Extra executes an explicit graph. + +Orchestrators route requests to AI specialists. Each specialist owns its own prompts, tools, MCP servers, and authorization. + +Your business logic stays in your backend. Extra only orchestrates execution. ```mermaid flowchart TD @@ -185,15 +185,6 @@ tools, access checks, and the values resolved into prompts. - **[Architecture](https://docs.extra-ai.co/docs/architecture)** — how routing and execution work. - **[`examples/`](examples/)** — runnable specs, including an enterprise knowledge assistant. -## Who is Extra for? - -Teams adding an AI interface to existing SaaS products, internal enterprise -systems, customer support workflows, or multi-tenant products with strict access -boundaries. - -It may be unnecessary if you need a single prompt with a few tools, a chatbot -with no backend integration, low-level control over the orchestration runtime, -or batch processing. ## Contributing From 20362d894656be6ee0d64043846487603ba4a239 Mon Sep 17 00:00:00 2001 From: Asaf Varon Date: Sat, 8 Aug 2026 14:12:41 +0300 Subject: [PATCH 06/10] docs: refine README messaging and simplify value proposition --- README.md | 59 +++++++++++++++++++++++++------------------------------ 1 file changed, 27 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 87b1869f..1162d074 100644 --- a/README.md +++ b/README.md @@ -5,10 +5,10 @@

-

Turn your product into an AI-powered assistant that understands your business.

+

Turn your product into an AI-powered assistant.

- Extra lets you build AI-powered assistants that understand your workflows, use your existing APIs and business logic, and delegate work to AI specialists. + Extra turns your existing APIs, business logic, and workflows into an AI-powered assistant. Users can ask, act, and get things done through a single interface.

@@ -27,27 +27,21 @@ --- Instead of navigating complex UIs, users simply ask. -Extra translates those requests into your existing APIs, business logic, -and workflows. +Extra routes each request to the right AI specialist and executes the workflow through your existing backend. ## Why Extra -Most AI frameworks start with prompts. +**Not just a chatbot.** Extra doesn't stop at answering questions. It can execute real product workflows using your existing APIs and tools. -Extra starts with your product. +* **Specialized by design.** Each AI specialist owns a specific part of your business. -It connects your existing backend to a network of focused AI specialists. +* **Your backend stays in control.** Business logic, data, credentials, and authorization remain in trusted code. -* **Specialized by design.** Each specialist understands one part of your business. +* **Explicit orchestration.** Work moves between specialists through predictable and inspectable execution paths. -* **Built on your backend.** Your existing APIs, tools, and services remain the source of truth. +* **Built for your product.** Expose Extra through an API or embed the assistant directly into your application. -* **Explicit workflows.** Requests move through predictable, inspectable execution paths. - -* **Authorization outside the model.** Access decisions stay in trusted code. - -* **Easy to embed.** Expose Extra through an API or add it directly to your product. ## Quick Start @@ -73,12 +67,12 @@ orchestrators: agents: orders_agent: - description: "Answers questions about orders, shipping, and returns." + description: "Handles order status, shipping changes, and returns." prompts: system: prompts/orders_agent/system.md billing_agent: - description: "Answers questions about invoices, plans, and refunds." + description: "Handles invoices, subscriptions, and refunds." prompts: system: prompts/billing_agent/system.md @@ -108,10 +102,10 @@ Route orders, shipping, and returns to orders_agent. Route invoices, plans, and refunds to billing_agent. -You answer questions about orders, shipping, and returns. +Handle order status, shipping changes, and returns using the available tools. -You answer questions about invoices, plans, and refunds. +Handle invoices, subscriptions, and refunds using the available tools. ``` Run it with Agent Manager, which serves the conversation API, history, and the @@ -145,8 +139,8 @@ chat widget are covered in the - AI specialists - Workflow orchestration -- Local tools and MCP - Authorization outside the LLM +- Local tools and MCP - Human approvals - Streaming API - Embeddable chat widget @@ -155,7 +149,7 @@ chat widget are covered in the ## Architecture -Extra executes an explicit graph. +Extra executes an explicit orchestration graph. Orchestrators route requests to AI specialists. Each specialist owns its own prompts, tools, MCP servers, and authorization. @@ -163,18 +157,19 @@ Your business logic stays in your backend. Extra only orchestrates execution. ```mermaid flowchart TD - U([User request]) --> R{{Orchestrator
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 + U([User request]) --> R{{Orchestrator}} + + R --> A1[Billing specialist] + R --> A2[Orders specialist] + R --> A3[Docs specialist] + + A1 --> T1[Business logic / APIs] + A2 --> T2[Business logic / APIs] + A3 --> T3[Business logic / APIs] + + T1 --> RESP([Response]) + T2 --> RESP + T3 --> RESP ``` Extra runs the graph. Your project's plugins hold the trusted business logic — From 59e5bd9661d779754c5dc038532ef9272dd55b71 Mon Sep 17 00:00:00 2001 From: Asaf Varon Date: Sat, 8 Aug 2026 14:36:53 +0300 Subject: [PATCH 07/10] docs: refine the hero README messaging and simplify value proposition --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 1162d074..678a8d12 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@

Turn your product into an AI-powered assistant.

- Extra turns your existing APIs, business logic, and workflows into an AI-powered assistant. Users can ask, act, and get things done through a single interface. + Give your users an AI-powered way to use your product.

@@ -25,12 +25,12 @@

--- -Instead of navigating complex UIs, users simply ask. -Extra routes each request to the right AI specialist and executes the workflow through your existing backend. +## Why Extra +Extra gives your customers an AI-powered way to use your product. -## Why Extra +It routes each request to the right AI specialist and executes real workflows through your existing backend. **Not just a chatbot.** Extra doesn't stop at answering questions. It can execute real product workflows using your existing APIs and tools. From 651591efd0b60464ca7b7f73e2f6b8678e4527c1 Mon Sep 17 00:00:00 2001 From: Asaf Varon Date: Sat, 8 Aug 2026 14:46:18 +0300 Subject: [PATCH 08/10] docs: refine README mark the word zero in the subtitle --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 678a8d12..e16c5ca7 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@

Turn your product into an AI-powered assistant.

- Give your users an AI-powered way to use your product. + Give your users an AI-powered way to use your product—with zero backend rewrites.

@@ -30,9 +30,10 @@ Extra gives your customers an AI-powered way to use your product. -It routes each request to the right AI specialist and executes real workflows through your existing backend. +It works with the APIs, business logic, and workflows you already have — without requiring you to redesign your product around AI. -**Not just a chatbot.** Extra doesn't stop at answering questions. It can execute real product workflows using your existing APIs and tools. + +* **No backend rewrite.** Keep your existing APIs, services, and business logic as they are. * **Specialized by design.** Each AI specialist owns a specific part of your business. @@ -42,6 +43,7 @@ It routes each request to the right AI specialist and executes real workflows th * **Built for your product.** Expose Extra through an API or embed the assistant directly into your application. +**Not just a chatbot.** Extra doesn't stop at answering questions. It can execute real product workflows using your existing APIs and tools. ## Quick Start From 0552bb4011fae3118b9a6dbc8c1a1a699245b4e2 Mon Sep 17 00:00:00 2001 From: Asaf Varon Date: Sat, 8 Aug 2026 14:55:41 +0300 Subject: [PATCH 09/10] docs: refine README quick start section --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index e16c5ca7..3fb8ffe2 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,9 @@ It works with the APIs, business logic, and workflows you already have — witho ## Quick Start -You need Docker and an API key for your model provider. +You need Docker and a language model. + +Use a supported cloud provider with an API key, or run open-source models locally with Ollama. Create `agents.yml` — an orchestrator that routes to two focused agents: From d499f857ecf2d0b81fe9c75cf4aef243fee61e18 Mon Sep 17 00:00:00 2001 From: Asaf Varon Date: Sat, 8 Aug 2026 14:58:18 +0300 Subject: [PATCH 10/10] docs: refine README remove agentctl command --- README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/README.md b/README.md index 3fb8ffe2..22cbcbbc 100644 --- a/README.md +++ b/README.md @@ -91,9 +91,6 @@ Scaffold the prompt and plugin stubs the YAML references. It never overwrites a file you already wrote: ```bash -agentctl generate --config agents.yml - -# or via the Docker image, which supplies the `agentctl` prefix for you: docker run --rm -v "$(pwd):/workspace" -w /workspace \ ghcr.io/extra-org/extra:latest generate --config agents.yml ```