Skip to content

Improve homepage, features, and use cases #737

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

Merged
ashpreetbedi merged 4 commits into from
Jul 20, 2026
Merged

Improve homepage, features, and use cases #737

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
bda938e
docs: improve homepage features and use cases
ashpreetbedi Jul 20, 2026
aedad84
docs: align Control Plane description
ashpreetbedi Jul 20, 2026
a7621bc
docs: frame Control Plane as agent governance
ashpreetbedi Jul 20, 2026
acbfa9c
docs: refine feature and use case descriptions
ashpreetbedi Jul 20, 2026
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
35 changes: 21 additions & 14 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,9 +107,11 @@
"pages": [
"features/sdk",
"features/runtime",
"features/control-plane",
"features/api",
"features/storage",
"features/observability",
"features/evaluation",
"features/security-and-auth",
"features/interfaces",
"features/scheduling"
Expand All @@ -118,18 +120,6 @@
{
"group": "Use Cases",
"pages": [
{
"group": "Data Labeling",
"pages": [
"use-cases/data-labeling/overview",
"use-cases/data-labeling/structured-extraction",
"use-cases/data-labeling/classification",
"use-cases/data-labeling/llm-as-judge",
"use-cases/data-labeling/preference-data",
"use-cases/data-labeling/multimodal-inputs",
"use-cases/data-labeling/quality-pipeline"
]
},
{
"group": "Product Copilots & Agents",
"pages": [
Expand All @@ -140,8 +130,25 @@
"use-cases/product-agents/interfaces"
]
},
"use-cases/workflow-automation",
{
"group": "Data & Analytics Agents",
"group": "Data Labeling & Classification",
"pages": [
"use-cases/data-labeling/overview",
"use-cases/data-labeling/image-search",
"use-cases/data-labeling/structured-extraction",
"use-cases/data-labeling/classification",
"use-cases/data-labeling/multimodal-inputs",
"use-cases/data-labeling/llm-as-judge",
"use-cases/data-labeling/preference-data",
"use-cases/data-labeling/quality-pipeline"
]
},
"use-cases/customer-support",
"use-cases/knowledge-agents",
"use-cases/coding-agents",
{
"group": "Data & Analytics",
"pages": [
"use-cases/data-agents/overview",
"use-cases/data-agents/querying-your-data",
Expand All @@ -153,7 +160,7 @@
]
},
{
"group": "Deep Research & Analysis",
"group": "Deep Research",
"pages": [
"use-cases/deep-research/overview",
"use-cases/deep-research/orchestration-patterns",
Expand Down
22 changes: 11 additions & 11 deletions features/api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,9 @@
---
title: Agent API
description: "REST API and optional MCP server for agents, teams, and workflows in AgentOS."
description: "Run and manage agents, teams, and workflows through REST, SSE, and MCP."
---

Shipping an agent needs more than a `/run` endpoint. A live agent needs an API that can:

- Run agents in streaming mode and as background jobs
- Manage the sessions, memory, and learnings your agents accumulate
- Inspect runs, traces, and metrics
- Schedule recurring work
- Gate sensitive tool calls on human approval
- Resume paused runs once that approval comes back
Agent-backed products need an API that covers the state and controls around every run. AgentOS provides REST endpoints for agents, teams, and workflows, plus sessions, memory, knowledge, traces, evaluations, schedules, approvals, and versioned components.

AgentOS registers run routes for your agents, teams, and workflows. Database-backed routes and opt-in features such as scheduling, tracing, and MCP depend on the AgentOS configuration. Browse the live API at `/docs` or fetch the spec from `/openapi.json`.

Expand All @@ -25,7 +18,7 @@ AgentOS registers run routes for your agents, teams, and workflows. Database-bac

## Interfaces

Agents need to be reachable over more than one interface. Define an agent once and AgentOS can expose it over any interface you opt into. REST and SSE are on by default; add an MCP server, A2A, or a Slack interface as needed. The agent code stays the same; only the interface layer changes.
AgentOS can expose the same registered component through several interfaces. REST and SSE are on by default; add an MCP server, A2A, or a Slack interface as needed. Each interface uses the same registered agent.

## The surface area

Expand Down Expand Up @@ -73,7 +66,7 @@ Pass `stream=true` for Server-Sent Events. Pass `background=true` to run async a

## Adding your own routes

AgentOS is built on FastAPI. Register additional routes for webhooks, custom dashboards, integrations:
AgentOS is built on FastAPI. Register additional routes for webhooks, dashboards, and integrations:

```python
# `agent_os` is your AgentOS instance; `agent` is an Agent registered with it
Expand All @@ -95,3 +88,10 @@ The agent is a regular Python object. Call `agent.run(...)` or `await agent.arun
When `authorization=True`, central REST routes require a valid JWT in the `Authorization: Bearer ...` header except for the public routes (`/`, `/health`, `/info`, and API docs routes such as `/docs` and `/openapi.json`). AgentOS validates the token, extracts claims, and applies RBAC scopes before agent code runs. Self-authenticating interfaces such as Slack, Telegram, and WhatsApp verify requests through their own interface middleware.

See [Security & Auth](/features/security-and-auth) for the details.

## Developer Resources

- [AgentOS API guide](/agent-os/using-the-api)
- [AgentOS API reference](/reference-api/overview)
- [AgentOS MCP interface](/agent-os/mcp/mcp)
- [AgentOS client](/agent-os/client/overview)
102 changes: 102 additions & 0 deletions features/control-plane.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
---
title: Agent Governance
sidebarTitle: Agent Governance
description: "Monitor, manage and govern your agents, teams, and workflows from one place."
---

Engineering teams use the AgentOS Control Plane to govern agents, teams, and workflows from development through production. Connect local or deployed runtimes to test components, inspect traces and sessions, manage knowledge and memory, review evaluations and approvals, and operate schedules from one web interface.

<Frame caption="Agents, teams, workflows, and connected AgentOS runtimes">
<img
src="/images/demo-os.png"
alt="AgentOS Control Plane showing agents, teams, workflows, and connected runtimes"
style={{ borderRadius: "0.5rem" }}
/>
</Frame>

## Govern the agent lifecycle

Build, test, debug, improve, and operate against local or deployed runtimes.

| Stage | Work in the Control Plane |
|-------|---------------------------|
| Build | Compose and version agents, teams, and workflows in Studio from registered models, tools, databases, schemas, and knowledge |
| Test | Run agents and teams, execute workflows, select component versions, and follow streamed output |
| Debug | Open session history and inspect trace trees for instrumented model calls, tool calls, team delegation, workflow steps, token use, latency, and errors |
| Improve | Search knowledge, review or update user memories, and inspect stored evaluations and aggregate usage metrics |
| Operate | Resolve approvals, create or trigger schedules, and switch between local and deployed runtimes |

## Follow every run

Open a session and follow the execution behind its response. Trace trees show the model calls, tool inputs and outputs, team delegation, and workflow steps recorded for the run. Spans show status and timing. Model spans also include token metrics when available.

<Frame caption="Inspect the execution path behind a run">
<img
src="/images/traces-in-os.png"
alt="AgentOS trace tree showing model calls, tool calls, delegation, latency, input, and output"
style={{ borderRadius: "0.5rem" }}
/>
</Frame>

Use the trace to move from an unexpected result to the model call, tool argument, member response, or workflow step that produced it.

## Manage the system behind each run

<CardGroup cols={2}>
<Card title="Studio" icon="diagram-project" href="/agent-os/studio/introduction">
Compose components from your Registry, save drafts, publish versions, and choose the version served by the API.
</Card>
<Card title="Knowledge and memory" icon="database" href="/agent-os/control-plane">
Search knowledge content and review or update the user memories exposed by the connected runtime.
</Card>
<Card title="Evaluations and metrics" icon="chart-line" href="/features/evaluation">
Review stored evaluation results and aggregate runtime usage from the configured database.
</Card>
<Card title="Approvals" icon="shield-check" href="/agent-os/approvals/overview">
Inspect tool arguments, approve or reject paused executions, and follow resolution history.
</Card>
<Card title="Scheduler" icon="clock" href="/agent-os/scheduler/overview">
Create recurring runs, trigger them manually, and inspect their execution history.
</Card>
<Card title="Full Control Plane guide" icon="book" href="/agent-os/control-plane">
Follow a first run, review runtime requirements, and open deeper guides.
</Card>
</CardGroup>

## Connect your runtimes

Add local, staging, and production AgentOS endpoints to the Control Plane. Select a runtime from the header to change the system you are working on.

The browser sends requests to the selected AgentOS endpoint. That runtime executes components, applies its authorization configuration, and reads or writes the state shown in the UI.

| Layer | Role |
|-------|------|
| Control Plane | Provides the browser interface and calls the AgentOS endpoint you select |
| AgentOS runtime | Runs agents, teams, and workflows, exposes their APIs, and enforces runtime authorization |
| Configured databases | Store sessions, memories, traces, evaluations, approvals, schedules, metrics, and Studio component versions |
| External services | Models, tools, interfaces, telemetry, and custom exporters follow their own configuration and data paths |

<Info>
Serve production runtimes over HTTPS and configure [Security & Auth](/agent-os/security/overview) before connecting them.
</Info>

## Runtime setup

Each Control Plane view depends on capabilities exposed by the connected runtime.

| Capability | Runtime setup |
|------------|---------------|
| Chat and workflow runs | Agents, teams, or workflows registered with AgentOS |
| Sessions, memories, metrics, and evaluations | An AgentOS database |
| Traces | `tracing=True` and a database available to AgentOS tracing |
| Studio | A `Registry` and a synchronous AgentOS `db` |
| Approvals | An AgentOS `db` and approval-enabled tools |
| Scheduled execution | An AgentOS `db` and `scheduler=True` |

## Developer Resources

- [AgentOS overview](/agent-os/introduction)
- [AgentOS API surface](/features/api)
- [Control Plane guide](/agent-os/control-plane)
- [AgentOS tracing](/agent-os/tracing/overview)
- [Security & Auth](/agent-os/security/overview)
73 changes: 73 additions & 0 deletions features/evaluation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
---
title: Agent Evaluation
description: "Catch regressions in response quality, tool use, latency, and memory."
---

Changes to models, instructions, tools, and knowledge can introduce regressions. Agno evals turn response criteria and expected tool use into executable cases. Run them during development, gate CI with their exit code, and evaluate selected production outputs through hooks.

```python evals.py
import sys

from agno.agent import Agent
from agno.eval import Case, cli
from agno.tools.calculator import CalculatorTools

calculator = Agent(
id="calculator",
model="openai:gpt-5.5",
tools=[CalculatorTools()],
instructions="Use the calculator tools for every calculation.",
)

CASES = (
Case(
name="factorial_uses_calculator",
agent=calculator,
input="What is 10 factorial?",
criteria="States that 10 factorial equals 3,628,800.",
expected_tool_calls=("factorial",),
),
)

if __name__ == "__main__":
sys.exit(cli(CASES))
```

Create a virtual environment, install the OpenAI integration, and set `OPENAI_API_KEY` before running the suite:

```bash
uv venv --python 3.12
uv pip install -U "agno[openai]"
```

```bash
uv run python evals.py --json-output tmp/evals.json
```

Each case runs the component once and applies the configured judge and reliability checks to the same output. The CLI returns a nonzero exit code when a case fails, so the suite can gate CI.

## Evaluation types

| Type | Measures | Guide |
|------|----------|-------|
| Accuracy | Correctness against an expected answer | [Accuracy evals](/evals/accuracy/overview) |
| Agent as judge | Custom quality criteria scored by an evaluator model | [Agent-as-judge evals](/evals/agent-as-judge/overview) |
| Reliability | Expected tool calls and arguments | [Reliability evals](/evals/reliability/overview) |
| Performance | Runtime latency and memory use | [Performance evals](/evals/performance/overview) |

## Where evals run

| Stage | Pattern |
|-------|---------|
| Local development | Run one case while changing an agent. |
| CI | Run tagged [eval suites](/evals/suite/overview) and keep the JSON report. |
| Production | Evaluate selected outputs with a synchronous or [background post-hook](/agent-os/usage/background-output-evaluation). |
| AgentOS | Store eval results in a configured database and manage them through the AgentOS API. |

## Next steps

| Task | Guide |
|------|-------|
| Build an eval suite | [Eval suites](/evals/suite/overview) |
| Add evals to an agent platform | [Agent platform evals](/agent-platform/evals) |
| Inspect the API surface | [Agent API](/features/api) |
33 changes: 14 additions & 19 deletions features/interfaces.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
title: Interfaces
description: "Slack, Telegram, WhatsApp, Discord, plus protocol interfaces for agents and browsers."
description: "Connect agents to chat interfaces (Slack, Telegram, WhatsApp, Discord), browser applications, and agent protocols."
---

An interface is an adapter between AgentOS and a surface where users already are. It receives events from Slack, Telegram, WhatsApp, or other channels, maps them onto AgentOS's run and session model, and routes responses back to the right thread, channel, or user.
Product and support teams can expose the same component in an application, team chat, and customer channels. AgentOS interfaces connect components to Slack, Telegram, WhatsApp, A2A, and AG-UI. Each interface handles surface-specific routing and session IDs. Chat interfaces verify their own webhooks; protocol interfaces use AgentOS authorization when it is enabled.

The agent doesn't change. The same agent definition answers a Slack DM, a Telegram message, and an AG-UI browser stream. Memory follows the user across surfaces when the interfaces resolve to the same `user_id`.
Session history stays tied to each surface's `session_id`.

## Available interfaces

Expand Down Expand Up @@ -74,19 +74,11 @@ Every interface maps surface state to AgentOS sessions, so a conversation in Sla
| A2A | A2A context ID | JWT subject, or request metadata when anonymous |
| AG-UI | Client thread ID | JWT subject, or client-supplied when anonymous |

### Resolving Slack user IDs

By default Slack hands you opaque user IDs like `U07ABCXYZ`. Set `resolve_user_identity=True` to use the member's email as `user_id` when Slack provides one:

```python
Slack(agent=agent, token=..., signing_secret=..., resolve_user_identity=True)
```

The interface calls `users.info`, uses the returned email as `user_id`, and adds the display name to run metadata. It falls back to the Slack user ID when no email is available. This option is off by default and adds a Slack API call per message.
Slack can resolve a member's email as `user_id` when `resolve_user_identity=True`. See the [Slack interface guide](/agent-os/interfaces/slack/introduction) for identity and permission setup.

## One agent, many surfaces

A single agent can answer on every surface at once. Memory follows the user across surfaces, provided you can map their Slack ID to the same `user_id` the AG-UI client passes:
A single agent can answer on every surface at once:

```python
agent_os = AgentOS(
Expand All @@ -101,11 +93,11 @@ agent_os = AgentOS(
)
```

The questions the agent answered in Slack last week show up in its memory when the user opens the AG-UI widget on your website. Session history stays scoped to each surface's `session_id`, and interfaces pass surface context along with the run, like the Slack channel name.
When user memory is enabled and each interface resolves the same person to the same `user_id`, stored memories are available across surfaces. Session history stays scoped to each surface's `session_id`, and interfaces pass surface context along with the run, such as the Slack channel name.

## Conditional registration

Don't register interfaces you don't have credentials for:
Register optional interfaces only when their credentials are available:

```python
interfaces = []
Expand All @@ -119,13 +111,13 @@ if TELEGRAM_TOKEN:
agent_os = AgentOS(agents=[agent], db=db, interfaces=interfaces)
```

The [Scout](/deploy/templates/scout/overview), [Dash](/deploy/templates/dash/overview), and [Coda](/deploy/templates/coda/overview) apps use this pattern. Slack only loads when both env vars are set, so dev runs without credentials don't crash.
The [Scout](/deploy/templates/scout/overview), [Dash](/deploy/templates/dash/overview), and [Coda](/deploy/templates/coda/overview) apps use this pattern. The Slack interface loads when both environment variables are set, which keeps development runs working before optional channel credentials are configured.

## Custom interfaces and one-off webhooks

The interface API is small. Subclass `BaseInterface`, return your routes from `get_router`, and dispatch incoming messages to the agent. See [BaseInterface](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/os/interfaces/base.py) for the full surface.
Subclass `BaseInterface`, return your routes from `get_router`, and dispatch incoming messages to the agent. See [BaseInterface](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/os/interfaces/base.py) for the full surface.

For one-off webhooks (a CRM event, a GitHub action, a custom dashboard), don't write an interface. Add a route directly to the FastAPI app:
Add a route directly to the FastAPI app for an application-specific webhook such as a CRM event, GitHub action, or custom dashboard:

```python
app = agent_os.get_app()
Expand All @@ -136,4 +128,7 @@ async def handle_stripe(event: dict):
return {"ok": True, "response": response.content}
```

A custom interface is for surfaces you'll reuse across agents and OS instances. A direct route is for one-off integrations.
| Need | Pattern |
|------|---------|
| Reusable surface shared across AgentOS applications | Subclass `BaseInterface` |
| One application-specific event source | Add a FastAPI route |
Loading
Loading