From dd4ca693c4f4414905f105351e9477c5fef3df9b Mon Sep 17 00:00:00 2001 From: Asaf Varon Date: Sat, 25 Jul 2026 18:56:26 +0300 Subject: [PATCH] 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 6f719b4..40494ba 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