Skip to content

docs(readme): reposition around "Make your product queryable" #47

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Asaf-prog wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(readme): reposition around "Make your product queryable" #47

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
236 changes: 93 additions & 143 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,11 @@
</picture>
</p>

<h1 align="center">Make your product queryable.</h1>

@AmitAvital1 AmitAvital1 Aug 3, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wdyt "An AI that actually uses your product"

@AmitAvital1 AmitAvital1 Aug 3, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't really like the queryable


<p align="center">
<b>Turn your app into an agentic product — from one YAML file.</b><br>
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.
</p>

<p align="center">
Expand All @@ -18,195 +19,144 @@
</p>

<p align="center">
<a href="https://docs.extra-ai.co/docs/introduction">Documentation</a> ·
<a href="#quick-start">Quick Start</a> ·
<a href="#how-it-works">How it works</a> ·
<a href="#learn-more">Learn more</a> ·
<a href="#why-extra">Why Extra</a> ·
<a href="#who-is-extra-for">Who it's for</a> ·
<a href="https://docs.extra-ai.co/docs/introduction">Documentation</a> ·
<a href="#contributing">Contributing</a>
</p>

---

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

@AmitAvital1 AmitAvital1 Aug 3, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Define the system in YAML ->
Maybe Deploy agentic system in YAML?

boundaries while your logic and credentials stay in your backend.

## How it works
## Why Extra

@AmitAvital1 AmitAvital1 Aug 3, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you should add it also at the end
about that extra is fast accurance and using graph models design which is best performance with answers and accuracy.. just something like that


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<br/>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

@AmitAvital1 AmitAvital1 Aug 3, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please remove Avoid model lock-in from here too much details and not really neccesery

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

@AmitAvital1 AmitAvital1 Aug 3, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

WDYT
Adding it in your product. Embed the system as a widget chat or serve by an API

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:

@AmitAvital1 AmitAvital1 Aug 3, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lets do example with orchestrator so we can see value?

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

@AmitAvital1 AmitAvital1 Aug 3, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not good, need to run generate before


## 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 \

@AmitAvital1 AmitAvital1 Aug 3, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why not run it with our command for agent manger so can use playground ui widget or via curl also

-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

@AmitAvital1 AmitAvital1 Aug 3, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lets add exact like no playground, or exac curl command with like

"Tell me about my system"

`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<br/>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

Expand Down
Loading