From cada5b29949005367b485ad27e79640c68c7495f Mon Sep 17 00:00:00 2001 From: Ashpreet Date: Sun, 19 Jul 2026 09:11:54 +0100 Subject: [PATCH 01/21] docs: expand homepage features and use cases --- docs.json | 32 +++--- features/evaluation.mdx | 73 ++++++++++++++ index.mdx | 70 ++++--------- use-cases/coding-agents.mdx | 139 ++++++++++++++++++++++++++ use-cases/customer-support.mdx | 113 +++++++++++++++++++++ use-cases/knowledge-assistants.mdx | 112 +++++++++++++++++++++ use-cases/product-agents/overview.mdx | 3 +- use-cases/workflow-automation.mdx | 79 +++++++++++++++ 8 files changed, 559 insertions(+), 62 deletions(-) create mode 100644 features/evaluation.mdx create mode 100644 use-cases/coding-agents.mdx create mode 100644 use-cases/customer-support.mdx create mode 100644 use-cases/knowledge-assistants.mdx create mode 100644 use-cases/workflow-automation.mdx diff --git a/docs.json b/docs.json index be79f9dc6..91ebe91a8 100644 --- a/docs.json +++ b/docs.json @@ -107,9 +107,11 @@ "pages": [ "features/sdk", "features/runtime", + "agent-os/control-plane", "features/api", "features/storage", "features/observability", + "features/evaluation", "features/security-and-auth", "features/interfaces", "features/scheduling" @@ -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": [ @@ -140,6 +130,9 @@ "use-cases/product-agents/interfaces" ] }, + "use-cases/customer-support", + "use-cases/knowledge-assistants", + "use-cases/coding-agents", { "group": "Data & Analytics Agents", "pages": [ @@ -174,7 +167,20 @@ "use-cases/document-processing/batch-and-durability", "use-cases/document-processing/human-routing-and-eval" ] - } + }, + { + "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" + ] + }, + "use-cases/workflow-automation" ] } ] diff --git a/features/evaluation.mdx b/features/evaluation.mdx new file mode 100644 index 000000000..5cf5f8224 --- /dev/null +++ b/features/evaluation.mdx @@ -0,0 +1,73 @@ +--- +title: Agent Evaluation +description: "Measure agent and team quality with accuracy, reliability, performance, and agent-as-judge evals." +--- + +Run eval cases during development and in CI: + +```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 +``` + +The case checks the response against a quality criterion and verifies the expected tool call. 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) | diff --git a/index.mdx b/index.mdx index 81bb5bac3..b8ee453c3 100644 --- a/index.mdx +++ b/index.mdx @@ -7,11 +7,19 @@ mode: wide Agno provides an SDK, a runtime, and a control plane for building agent platforms. | Product | Description | -|-------|-------------| +|---------|-------------| | **SDK** | Build agents, teams, and workflows with memory, knowledge, guardrails, and 100+ integrations. | | **AgentOS** | Run your agent platform in production with a stateless, secure FastAPI backend. | | **Control Plane** | Monitor and manage your system using the AgentOS UI. | +## Get started + +| Task | Guide | +|------|-------| +| Build your first agent | [First Agent](/first-agent) | +| Connect your coding agent to the Agno documentation | [Coding Agents](/coding-agents) | +| Deploy AgentOS and add your first production agent | [Agent Platform](/agent-platform/overview) | + -AgentOS runs your agent platform as a FastAPI application in your cloud. The fastest way to get started is to give your coding agent this prompt (select your cloud provider). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -## Common use cases - -| Team | Use cases | -|------|-----------| -| Product | Product copilots, chatbots, and agentic application features | -| ML and AI | Data labeling, extraction, classification, synthetic data, and eval generation | -| Data science | Data enrichment, segmentation, and training data curation | -| Data engineering | Data quality audits, failure analysis, and recurring reports | - -## Get started - -| Task | Guide | -|------|-------| -| Build your first agent | [First Agent](/first-agent) | -| Build an agent platform with a coding agent | [Agent Platform](/agent-platform/overview) | +## Use cases + +| Use case | What you can build | +|----------|--------------------| +| [Product copilots and agents](/use-cases/product-agents/overview) | Serve agents across product surfaces with database-backed sessions and memory. | +| [Customer support agents](/use-cases/customer-support) | Resolve requests with product knowledge, specialist routing, controlled actions, and human escalation. | +| [Knowledge assistants and RAG](/use-cases/knowledge-assistants) | Ground answers in indexed documents with ingestion, retrieval, metadata filters, and source updates. | +| [Coding agents](/use-cases/coding-agents) | Inspect codebases, implement changes, run tests, and return verified results. | +| [Data and analytics agents](/use-cases/data-agents/overview) | Query operational data with business context and database-enforced access boundaries. | +| [Deep research and analysis](/use-cases/deep-research/overview) | Investigate complex questions in parallel and deliver grounded, structured reports. | +| [Document processing](/use-cases/document-processing/overview) | Turn PDFs and scanned documents into typed rows for production systems. | +| [Data labeling and classification](/use-cases/data-labeling/overview) | Label and classify text, images, audio, video, and PDFs. | +| [Workflow automation](/use-cases/workflow-automation) | Run repeatable processes with workflows, background execution, human review, and schedules. | diff --git a/use-cases/coding-agents.mdx b/use-cases/coding-agents.mdx new file mode 100644 index 000000000..2a5358ffc --- /dev/null +++ b/use-cases/coding-agents.mdx @@ -0,0 +1,139 @@ +--- +title: Coding Agents +sidebarTitle: Build Coding Agents +description: "Build coding agents that inspect repositories, edit files, run commands, and verify changes." +--- + +A coding agent needs a scoped project, a focused change, and a verification command. + +```python coding_agent.py +import tempfile +from pathlib import Path + +from agno.agent import Agent +from agno.tools.coding import CodingTools + +project = Path(tempfile.mkdtemp(prefix="coding-agent-")) + +(project / "math_utils.py").write_text( + "def factorial(n: int) -> int:\n" + " return 1 if n <= 1 else n * factorial(n - 1)\n" +) + +(project / "test_math_utils.py").write_text( + "import unittest\n\n" + "from math_utils import factorial\n\n\n" + "class TestFactorial(unittest.TestCase):\n" + " def test_factorial(self):\n" + " self.assertEqual(factorial(5), 120)\n\n\n" + "if __name__ == '__main__':\n" + " unittest.main()\n" +) + +coding_agent = Agent( + name="Coding Agent", + model="openai:gpt-5.5", + tools=[ + CodingTools( + base_dir=project, + restrict_to_base_dir=True, + all=True, + allowed_commands=["python3"], + ) + ], + instructions=[ + "Read existing files before changing them.", + "Make focused edits.", + "Run the test suite after every change.", + "Report the files changed and the final test result.", + ], +) + +coding_agent.print_response( + "Update factorial() to reject negative inputs, add a regression test, " + "then run python3 -m unittest -v.", + stream=True, +) +``` + +Create a virtual environment, install the OpenAI integration, and set `OPENAI_API_KEY` before running the agent: + +```bash +uv venv --python 3.12 +uv pip install -U "agno[openai]" +export OPENAI_API_KEY="your_openai_api_key" +uv run python coding_agent.py +``` + +The example creates a fresh fixture on every run. `base_dir` scopes file operations to that directory. `allowed_commands` limits shell entry points to `python3`. + + +`base_dir` limits file paths. The process still inherits the host environment, network access, and operating-system permissions. Run untrusted code inside a dedicated container, virtual machine, or remote sandbox. + + + +This page covers building coding agents with Agno. To give Codex, Claude Code, Cursor, or another client access to Agno documentation, see [Connect your coding agent](/coding-agents). + + +## Common patterns + +| Pattern | Agent task | +|---------|------------| +| Repository onboarding | Map the project and answer questions with file references. | +| Bug fixing | Reproduce a failure, make a focused change, and rerun the failing tests. | +| Code review | Inspect a diff, run targeted checks, and return prioritized findings. | +| Dependency upgrades | Update a dependency, resolve compatibility failures, and run the project gates. | +| CI remediation | Read failure logs, reproduce the failure, patch the cause, and verify the fix. | +| Migrations | Apply repeatable changes across files and report unresolved cases. | + +## Choose the execution boundary + +| Requirement | Use | +|-------------|-----| +| Compact tools for a trusted local project | [`CodingTools`](/tools/toolkits/local/coding) with a scoped `base_dir` and narrow `allowed_commands`. | +| Read-only repository analysis | [`Workspace`](/tools/toolkits/local/workspace) with `allowed=["read", "list", "search"]`. | +| Approval before edits or shell commands | `Workspace` with its default confirmation policy and `require_read_before_write=True`. | +| Execute untrusted code remotely | [Daytona](/tools/toolkits/others/daytona) or [E2B](/tools/toolkits/others/e2b). | +| Execute untrusted code on your infrastructure | Run the agent inside a dedicated container or virtual machine. | + +## Define the engineering loop + +| Stage | Boundary | +|-------|----------| +| Understand | Read and search the relevant files before proposing a change. | +| Change | Keep edits focused and require confirmation when the workspace is not disposable. | +| Verify | Run the repository's tests, lint, type checks, and build inside the execution environment. | +| Review | Return changed files, command results, and unresolved risks. | +| Publish | Keep commits, pushes, pull requests, and deployments outside the default loop or expose them as separately gated tools. | + +## Production path + +| Need | Agno capability | +|------|-----------------| +| Serve coding tasks through an API | Register the agent with [AgentOS](/agent-os/overview). | +| Continue after the client disconnects | Use [background execution](/background-execution/overview). | +| Pause before edits or shell commands | Use `Workspace` confirmation with [AgentOS HITL](/agent-os/usage/hitl). | +| Authenticate CI and machine callers | Mint a scoped [service account](/agent-os/security/authorization/service-accounts). | +| Inspect model calls, tool arguments, and failures | Configure a database and enable [observability](/features/observability). | +| Catch behavioral regressions | Run coding tasks against fresh fixture repositories with an [eval suite](/evals/suite/overview). | + +## Evaluate coding agents + +| Quality layer | Check | +|---------------|-------| +| Project gates | Compile the project and run its unit, integration, lint, and type checks inside the execution environment. | +| Reliability | Verify required tool calls such as reading the target file and running the test command. | +| Agent as judge | Score whether the change follows the request, stays in scope, and explains its verification. | +| Performance | Track end-to-end runtime and memory use. | + +Restore the fixture before every eval case so one run cannot affect the next. + +## Next steps + +| Task | Guide | +|------|-------| +| Configure the compact coding toolkit | [CodingTools](/tools/toolkits/local/coding) | +| Add confirmation-gated workspace access | [Workspace](/tools/toolkits/local/workspace) | +| Isolate remote execution | [Daytona](/tools/toolkits/others/daytona) or [E2B](/tools/toolkits/others/e2b) | +| Add behavioral regression cases | [Agent Evaluation](/features/evaluation) | +| Serve the agent in production | [Agent API](/features/api) | diff --git a/use-cases/customer-support.mdx b/use-cases/customer-support.mdx new file mode 100644 index 000000000..6d4b0ade3 --- /dev/null +++ b/use-cases/customer-support.mdx @@ -0,0 +1,113 @@ +--- +title: Customer Support Agents +description: "Resolve customer requests with specialist routing, product knowledge, controlled actions, and human escalation." +--- + +A support system needs persistent conversation history, access to approved information, and clear boundaries for customer-impacting actions. + +```python support_team.py +from agno.agent import Agent +from agno.db.sqlite import SqliteDb +from agno.team import Team + +model = "openai:gpt-5.5" + +billing = Agent( + name="Billing Support", + role="Answer questions about invoices, payments, subscriptions, and refunds.", + model=model, +) + +technical = Agent( + name="Technical Support", + role="Diagnose product errors and provide troubleshooting steps.", + model=model, +) + +support_team = Team( + name="Customer Support", + model=model, + members=[billing, technical], + db=SqliteDb(db_file="tmp/support.db"), + add_history_to_context=True, + num_history_runs=5, + instructions=[ + "Route each request to the relevant specialist.", + "Consult both specialists when an issue crosses billing and product behavior.", + ], +) + +support_team.print_response( + "My card was charged twice after checkout returned HTTP 500.", + user_id="customer-42", + session_id="ticket-1842", +) +``` + +Create a virtual environment, install the OpenAI and SQLite integrations, and set `OPENAI_API_KEY` before running the team: + +```bash +uv venv --python 3.12 +uv pip install -U "agno[openai,sqlite]" +uv run python support_team.py +``` + +The team can consult both specialists for this request. Reuse the `session_id` for later messages on the same ticket and the `user_id` for the same customer. This example routes requests and stores session history. Add confirmation-required tools before permitting account changes or refunds. + +## Build the resolution path + +| Stage | Agno capability | Purpose | +|-------|-----------------|---------| +| Receive | [AgentOS API](/features/api) or [interfaces](/features/interfaces) | Accept requests from a product, Slack, WhatsApp, or another service. | +| Identify | [Sessions](/sessions/overview) and [authorization](/agent-os/security/overview) | Associate the request with a customer, preserve its conversation history, and establish the caller's identity. | +| Ground | [Knowledge](/knowledge/overview) and [context providers](/context-providers/overview) | Search approved product content and retrieve current account or order data. | +| Route | [Teams](/teams/overview) or [workflows](/workflows/overview) | Select a specialist or follow a fixed triage policy. | +| Act | [Tools](/tools/overview) and [human-in-the-loop](/hitl/overview) | Create tickets, update records, or request approval for sensitive work. | +| Improve | [Learning](/learning/overview), [evaluation](/features/evaluation), and [observability](/features/observability) | Reuse resolved cases, measure quality, and inspect failures. | + +## Choose the execution model + +| Requirement | Use | +|-------------|-----| +| One support policy and one set of tools | [Agent](/agents/overview) | +| Dynamic routing among billing, technical, and account specialists | [Team](/teams/overview) | +| Deterministic triage, service-level rules, or escalation steps | [Workflow](/workflows/overview) | + +Teams let the model choose the relevant specialist. Workflows encode branches and required steps in code. A support system can use a workflow for intake and escalation, with a team inside a step for specialist investigation. + +## Set action boundaries + +| Action | Boundary | +|--------|----------| +| Answer from approved product documentation | Give the agent read-only knowledge. | +| Read an order, subscription, or account | Establish the caller's identity, enforce account-level access inside the provider or tool, and keep it read-only. | +| Change a plan, issue a refund, or cancel an order | Require [confirmation](/hitl/user-confirmation) before the tool runs. | +| Create an engineering ticket with missing fields | Request [user input](/hitl/user-input) before the tool runs. | +| Send an external message | Gate the send tool and record the action in the run history. | + +## Serve support channels + +| Channel | Guide | +|---------|-------| +| Product UI or backend | [Serve as an API](/use-cases/product-agents/serve-as-an-api) | +| Slack | [Support team](/agent-os/usage/interfaces/slack/support-team) | +| WhatsApp | [WhatsApp interface](/agent-os/interfaces/whatsapp/introduction) | +| Custom clients | [AgentOS client](/agent-os/client/overview) | + +## Improve from resolved requests + +| Goal | Pattern | +|------|---------| +| Preserve the current ticket | Reuse its `session_id` and store session history. | +| Remember customer preferences | Store user-scoped [memory](/memory/overview). | +| Reuse successful resolutions | Start with the [support learning pattern](/examples/learning/patterns/support-agent). Configure a tenant-scoped namespace for every shared production store. | +| Monitor response quality | Run [background output evaluation](/agent-os/usage/background-output-evaluation). | +| Prevent regressions | Add support conversations to an [eval suite](/evals/suite/overview). | + +## Next steps + +| Task | Guide | +|------|-------| +| Route technical and general requests through fixed branches | [Conditional workflow example](/examples/workflows/conditional-execution/condition-with-else) | +| Collect ticket fields from a Slack requester | [Human input example](/examples/agent-os/interfaces/slack/hitl-user-input) | +| Connect live customer systems | [Connecting your data](/use-cases/product-agents/connecting-your-data) | diff --git a/use-cases/knowledge-assistants.mdx b/use-cases/knowledge-assistants.mdx new file mode 100644 index 000000000..13f7ab9e5 --- /dev/null +++ b/use-cases/knowledge-assistants.mdx @@ -0,0 +1,112 @@ +--- +title: Knowledge Assistants & RAG +description: "Ground agent responses in indexed content with controlled ingestion, retrieval, filtering, and source updates." +--- + +A knowledge assistant indexes a maintained corpus and retrieves relevant content when needed. + +```python knowledge_assistant.py +from agno.agent import Agent +from agno.knowledge.embedder.openai import OpenAIEmbedder +from agno.knowledge.knowledge import Knowledge +from agno.vectordb.chroma import ChromaDb +from agno.vectordb.search import SearchType + +knowledge = Knowledge( + name="Company handbook", + vector_db=ChromaDb( + collection="company_handbook", + path="tmp/chromadb", + persistent_client=True, + search_type=SearchType.hybrid, + embedder=OpenAIEmbedder(id="text-embedding-3-small"), + ), +) + +knowledge.insert( + name="Travel policy", + text_content=( + "Domestic travel under $2,000 requires manager approval. " + "International travel and travel costing $2,000 or more require VP approval." + ), + skip_if_exists=True, +) + +assistant = Agent( + name="Policy Assistant", + model="openai:gpt-5.5", + knowledge=knowledge, + search_knowledge=True, + instructions=[ + "Use the knowledge base for policy questions.", + "Say when the answer is not in the knowledge base.", + ], +) + +assistant.print_response("When does travel need VP approval?", stream=True) +``` + +Create a virtual environment, install the OpenAI and ChromaDB integrations, and set `OPENAI_API_KEY` before running the assistant: + +```bash +uv venv --python 3.12 +uv pip install -U "agno[chromadb,openai]" +export OPENAI_API_KEY="your_openai_api_key" +uv run python knowledge_assistant.py +``` + +The assistant decides when to search the indexed policy. ChromaDB persists the embedded content under `tmp/chromadb` for later runs. + +## Choose the information path + +| Information | Pattern | +|-------------|---------| +| Policies, manuals, and product documentation | Index the corpus with [Knowledge](/knowledge/overview). | +| Current account, order, or operational data | Query a [context provider](/context-providers/overview), tool, or MCP server at run time. | +| Policies plus current records | Retrieve the rules from Knowledge, then call a tool for the current record. | +| Typed fields extracted from incoming files | Use [Document Processing](/use-cases/document-processing/overview). | + +Knowledge owns indexed content and retrieval. Context providers and tools query live systems. Product agents add sessions, authentication, and interfaces around either pattern. + +## Choose retrieval behavior + +| Behavior | Configuration | Use when | +|----------|---------------|----------| +| Agentic search | `search_knowledge=True` | The agent may need several searches or no search. | +| Automatic context | `add_knowledge_to_context=True`, `search_knowledge=False` | Each string input should receive retrieved context before the model runs. | +| Custom retrieval | Set a custom `knowledge_retriever` | An existing search service owns query rewriting, ranking, or access checks. | + +Start with agentic search. Add automatic context when each string input depends on the corpus. Use a custom retriever when retrieval policy lives outside Agno. + +## Protect corpus boundaries + +| Requirement | Control | +|-------------|---------| +| Several named corpora share one vector database | Give each `Knowledge` instance a unique name and set [`isolate_vector_search=True`](/knowledge/concepts/isolate-vector-search). | +| Results should match document attributes | Insert metadata and apply [knowledge filters](/knowledge/concepts/filters/overview). | +| Tenant or user authorization | Authenticate and authorize the caller before retrieval. Apply metadata filters from the verified identity to narrow results. | +| Users can submit remote URLs | Configure reader `allowed_hosts` and follow the [SSRF hardening pattern](/examples/knowledge/production/ssrf-allowed-hosts). | + +Reindex older content before enabling isolated vector search if its vectors do not contain `linked_to` metadata. + +## Production path + +| Need | Guide | +|------|-------| +| Ingest files, URLs, and text | [Knowledge quickstart](/knowledge/quickstart) | +| Track content state and updates | [Contents database](/knowledge/concepts/contents-db) and [knowledge lifecycle example](/examples/knowledge/production/knowledge-lifecycle) | +| Choose a production vector database | [Vector stores](/knowledge/vector-stores/index) | +| Choose vector, keyword, or hybrid retrieval | [Search and retrieval](/knowledge/concepts/search-and-retrieval/overview) | +| Tune how documents are split | [Chunking](/knowledge/concepts/chunking/overview) | +| Isolate customer corpora | [Multi-tenant example](/examples/knowledge/production/multi-tenant) | +| Manage content through AgentOS | [Manage knowledge](/agent-os/knowledge/manage-knowledge) | +| Catch retrieval or answer regressions | [Agent Evaluation](/features/evaluation) | + +## Next steps + +| Task | Guide | +|------|-------| +| Build the first indexed assistant | [Knowledge quickstart](/knowledge/quickstart) | +| Combine several source types | [Multi-source RAG](/examples/knowledge/production/multi-source-rag) | +| Share retrieval across specialists | [Knowledge for teams](/knowledge/teams/overview) | +| Query live systems instead of an index | [Connecting your data](/use-cases/product-agents/connecting-your-data) | diff --git a/use-cases/product-agents/overview.mdx b/use-cases/product-agents/overview.mdx index 598f6955e..271d5a8a4 100644 --- a/use-cases/product-agents/overview.mdx +++ b/use-cases/product-agents/overview.mdx @@ -51,7 +51,8 @@ Stored memory can follow a user when surfaces call the same agent with the same |----------|----------|------------| | A B2B SaaS product | JWT authentication and opt-in per-user isolation | [Serve as an API](/use-cases/product-agents/serve-as-an-api) | | Users in Slack or the browser | The same agent where they already work | [Interfaces](/use-cases/product-agents/interfaces) | -| Internal docs, Drive, databases | An agent grounded in external company data | [Connecting your data](/use-cases/product-agents/connecting-your-data) | +| An indexed document corpus | Answers grounded in retrieved content | [Knowledge assistants and RAG](/use-cases/knowledge-assistants) | +| Live systems such as Slack, Drive, or databases | Current records queried at run time | [Connecting your data](/use-cases/product-agents/connecting-your-data) | | Multi-day user relationships | Memory that persists per user across surfaces | [Sessions and memory](/use-cases/product-agents/sessions-and-memory) | ## Explore diff --git a/use-cases/workflow-automation.mdx b/use-cases/workflow-automation.mdx new file mode 100644 index 000000000..2e7443be5 --- /dev/null +++ b/use-cases/workflow-automation.mdx @@ -0,0 +1,79 @@ +--- +title: Workflow Automation +description: "Run repeatable processes with workflows, background execution, human review, and schedules." +--- + +A workflow gives agents and functions a defined execution path: + +```python incident_workflow.py +from agno.agent import Agent +from agno.db.sqlite import SqliteDb +from agno.workflow import Workflow + +triage = Agent( + name="Triage", + model="openai:gpt-5.5", + instructions="Extract the issue, severity, and responsible team.", +) + +action_plan = Agent( + name="Action Plan", + model="openai:gpt-5.5", + instructions="Turn the triage result into a short action plan.", +) + +incident_workflow = Workflow( + name="Incident Triage", + steps=[triage, action_plan], + db=SqliteDb(db_file="tmp/workflows.db"), +) + +incident_workflow.print_response( + "Checkout requests return HTTP 500 after the latest deployment." +) +``` + +Create a virtual environment, install the OpenAI, AgentOS, and SQLite integrations, and set `OPENAI_API_KEY` before running the workflow: + +```bash +uv venv --python 3.12 +uv pip install -U "agno[openai,os,sqlite]" +uv run python incident_workflow.py +``` + +Each step receives the previous step's output. The database stores workflow runs so they can be inspected after execution. + +## Choose the control model + +| Requirement | Use | +|-------------|-----| +| One model-driven task | [Agent](/agents/overview) | +| Dynamic delegation among specialists | [Team](/teams/overview) | +| Fixed steps, branches, loops, or parallel groups | [Workflow](/workflows/overview) | + +## Production building blocks + +| Need | Capability | +|------|------------| +| Continue work after the client disconnects | [Background execution](/background-execution/overview) | +| Pause before sensitive or irreversible work | [Human-in-the-loop workflows](/workflows/hitl/overview) | +| Run recurring jobs | [Scheduling](/features/scheduling) | +| Trigger work from another service | [Agent API](/features/api) | +| Inspect runs, latency, and failures | [Observability](/features/observability) | + +## Common patterns + +| Pattern | Workflow shape | +|---------|----------------| +| Intake and triage | Extract input, classify it, route it, and request review when needed. | +| Data enrichment | Fetch records, enrich them in parallel, validate output, and persist results. | +| Recurring reports | Collect data, analyze it, render a report, and run on a schedule. | +| Long-running research | Start in the background, persist events, and reconnect to the stream. | + +## Next steps + +| Task | Guide | +|------|-------| +| Define workflow steps | [Building workflows](/workflows/building-workflows) | +| Choose an orchestration pattern | [Workflow patterns](/workflows/workflow-patterns/overview) | +| Run a workflow through AgentOS | [Using the AgentOS API](/agent-os/using-the-api) | From c52184c7bbba172afd7777a0523b3d1e1a3e2f52 Mon Sep 17 00:00:00 2001 From: Ashpreet Date: Sun, 19 Jul 2026 09:16:36 +0100 Subject: [PATCH 02/21] docs: restore the homepage flow --- index.mdx | 93 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 71 insertions(+), 22 deletions(-) diff --git a/index.mdx b/index.mdx index b8ee453c3..bf12d9759 100644 --- a/index.mdx +++ b/index.mdx @@ -7,19 +7,11 @@ mode: wide Agno provides an SDK, a runtime, and a control plane for building agent platforms. | Product | Description | -|---------|-------------| +|-------|-------------| | **SDK** | Build agents, teams, and workflows with memory, knowledge, guardrails, and 100+ integrations. | | **AgentOS** | Run your agent platform in production with a stateless, secure FastAPI backend. | | **Control Plane** | Monitor and manage your system using the AgentOS UI. | -## Get started - -| Task | Guide | -|------|-------| -| Build your first agent | [First Agent](/first-agent) | -| Connect your coding agent to the Agno documentation | [Coding Agents](/coding-agents) | -| Deploy AgentOS and add your first production agent | [Agent Platform](/agent-platform/overview) | - -## Use cases - -| Use case | What you can build | -|----------|--------------------| -| [Product copilots and agents](/use-cases/product-agents/overview) | Serve agents across product surfaces with database-backed sessions and memory. | -| [Customer support agents](/use-cases/customer-support) | Resolve requests with product knowledge, specialist routing, controlled actions, and human escalation. | -| [Knowledge assistants and RAG](/use-cases/knowledge-assistants) | Ground answers in indexed documents with ingestion, retrieval, metadata filters, and source updates. | -| [Coding agents](/use-cases/coding-agents) | Inspect codebases, implement changes, run tests, and return verified results. | -| [Data and analytics agents](/use-cases/data-agents/overview) | Query operational data with business context and database-enforced access boundaries. | -| [Deep research and analysis](/use-cases/deep-research/overview) | Investigate complex questions in parallel and deliver grounded, structured reports. | -| [Document processing](/use-cases/document-processing/overview) | Turn PDFs and scanned documents into typed rows for production systems. | -| [Data labeling and classification](/use-cases/data-labeling/overview) | Label and classify text, images, audio, video, and PDFs. | -| [Workflow automation](/use-cases/workflow-automation) | Run repeatable processes with workflows, background execution, human review, and schedules. | +AgentOS runs your agent platform as a FastAPI application in your cloud. The fastest way to get started is to give your coding agent this prompt (select your cloud provider). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +## Get started + +| Task | Guide | +|------|-------| +| Build your first agent | [First Agent](/first-agent) | +| Build an agent platform with a coding agent | [Agent Platform](/agent-platform/overview) | + +## Common use cases + + + + Serve agents across product surfaces with database-backed sessions and memory. + + + Resolve requests with product knowledge, specialist routing, controlled actions, and human escalation. + + + Ground answers in indexed documents with ingestion, retrieval, metadata filters, and source updates. + + + Inspect codebases, implement changes, run tests, and return verified results. + + + Query operational data with business context and database-enforced access boundaries. + + + Investigate complex questions in parallel and deliver grounded, structured reports. + + + Turn PDFs and scanned documents into typed rows for production systems. + + + Label and classify text, images, audio, video, and PDFs. + + + Run repeatable processes with workflows, background execution, human review, and schedules. + + From 482972f83f144970e6a7315e736d1438fef1347a Mon Sep 17 00:00:00 2001 From: Ashpreet Date: Sun, 19 Jul 2026 09:35:28 +0100 Subject: [PATCH 03/21] docs: use a table for homepage use cases --- index.mdx | 40 +++++++++++----------------------------- 1 file changed, 11 insertions(+), 29 deletions(-) diff --git a/index.mdx b/index.mdx index bf12d9759..dee7360d7 100644 --- a/index.mdx +++ b/index.mdx @@ -61,32 +61,14 @@ AgentOS runs your agent platform as a FastAPI application in your cloud. The fas ## Common use cases - - - Serve agents across product surfaces with database-backed sessions and memory. - - - Resolve requests with product knowledge, specialist routing, controlled actions, and human escalation. - - - Ground answers in indexed documents with ingestion, retrieval, metadata filters, and source updates. - - - Inspect codebases, implement changes, run tests, and return verified results. - - - Query operational data with business context and database-enforced access boundaries. - - - Investigate complex questions in parallel and deliver grounded, structured reports. - - - Turn PDFs and scanned documents into typed rows for production systems. - - - Label and classify text, images, audio, video, and PDFs. - - - Run repeatable processes with workflows, background execution, human review, and schedules. - - +| Use case | What you can build | +|----------|--------------------| +| [Product copilots and agents](/use-cases/product-agents/overview) | Serve agents across product surfaces with database-backed sessions and memory. | +| [Customer support agents](/use-cases/customer-support) | Resolve requests with product knowledge, specialist routing, controlled actions, and human escalation. | +| [Knowledge assistants and RAG](/use-cases/knowledge-assistants) | Ground answers in indexed documents with ingestion, retrieval, metadata filters, and source updates. | +| [Coding agents](/use-cases/coding-agents) | Inspect codebases, implement changes, run tests, and return verified results. | +| [Data and analytics agents](/use-cases/data-agents/overview) | Query operational data with business context and database-enforced access boundaries. | +| [Deep research and analysis](/use-cases/deep-research/overview) | Investigate complex questions in parallel and deliver grounded, structured reports. | +| [Document processing](/use-cases/document-processing/overview) | Turn PDFs and scanned documents into typed rows for production systems. | +| [Data labeling and classification](/use-cases/data-labeling/overview) | Label and classify text, images, audio, video, and PDFs. | +| [Workflow automation](/use-cases/workflow-automation) | Run repeatable processes with workflows, background execution, human review, and schedules. | From 9c4bec88299fee79048c9fd883dc982482beceab Mon Sep 17 00:00:00 2001 From: Ashpreet Date: Sun, 19 Jul 2026 09:42:32 +0100 Subject: [PATCH 04/21] docs: tighten homepage section spacing --- index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.mdx b/index.mdx index dee7360d7..995f8f8dc 100644 --- a/index.mdx +++ b/index.mdx @@ -52,14 +52,14 @@ AgentOS runs your agent platform as a FastAPI application in your cloud. The fas -## Get started +

Get started

| Task | Guide | |------|-------| | Build your first agent | [First Agent](/first-agent) | | Build an agent platform with a coding agent | [Agent Platform](/agent-platform/overview) | -## Common use cases +

Common use cases

| Use case | What you can build | |----------|--------------------| From 2eebc2aaa8d820609db793de2d6f3aa3886babe6 Mon Sep 17 00:00:00 2001 From: Ashpreet Date: Sun, 19 Jul 2026 10:06:49 +0100 Subject: [PATCH 05/21] docs: refine homepage use cases table --- index.mdx | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/index.mdx b/index.mdx index 995f8f8dc..8c2659ac3 100644 --- a/index.mdx +++ b/index.mdx @@ -61,14 +61,9 @@ AgentOS runs your agent platform as a FastAPI application in your cloud. The fas

Common use cases

-| Use case | What you can build | -|----------|--------------------| -| [Product copilots and agents](/use-cases/product-agents/overview) | Serve agents across product surfaces with database-backed sessions and memory. | -| [Customer support agents](/use-cases/customer-support) | Resolve requests with product knowledge, specialist routing, controlled actions, and human escalation. | -| [Knowledge assistants and RAG](/use-cases/knowledge-assistants) | Ground answers in indexed documents with ingestion, retrieval, metadata filters, and source updates. | -| [Coding agents](/use-cases/coding-agents) | Inspect codebases, implement changes, run tests, and return verified results. | -| [Data and analytics agents](/use-cases/data-agents/overview) | Query operational data with business context and database-enforced access boundaries. | -| [Deep research and analysis](/use-cases/deep-research/overview) | Investigate complex questions in parallel and deliver grounded, structured reports. | -| [Document processing](/use-cases/document-processing/overview) | Turn PDFs and scanned documents into typed rows for production systems. | -| [Data labeling and classification](/use-cases/data-labeling/overview) | Label and classify text, images, audio, video, and PDFs. | -| [Workflow automation](/use-cases/workflow-automation) | Run repeatable processes with workflows, background execution, human review, and schedules. | +| Team | Use cases | +|------|-----------| +| Product | Product copilots, chatbots, and agentic application features | +| ML and AI | Data labeling, extraction, classification, synthetic data, and eval generation | +| Data science | Data enrichment, segmentation, and training data curation | +| Data engineering | Data quality audits, failure analysis, and recurring reports | From 7ca8109cb5e2e1b354069a5b284c4beab786264e Mon Sep 17 00:00:00 2001 From: Ashpreet Date: Sun, 19 Jul 2026 11:19:30 +0100 Subject: [PATCH 06/21] docs: simplify homepage getting started links --- index.mdx | 15 ++------------- 1 file changed, 2 insertions(+), 13 deletions(-) diff --git a/index.mdx b/index.mdx index 8c2659ac3..241f033ff 100644 --- a/index.mdx +++ b/index.mdx @@ -54,16 +54,5 @@ AgentOS runs your agent platform as a FastAPI application in your cloud. The fas

Get started

-| Task | Guide | -|------|-------| -| Build your first agent | [First Agent](/first-agent) | -| Build an agent platform with a coding agent | [Agent Platform](/agent-platform/overview) | - -

Common use cases

- -| Team | Use cases | -|------|-----------| -| Product | Product copilots, chatbots, and agentic application features | -| ML and AI | Data labeling, extraction, classification, synthetic data, and eval generation | -| Data science | Data enrichment, segmentation, and training data curation | -| Data engineering | Data quality audits, failure analysis, and recurring reports | +- [Build your first agent](/first-agent) with the Agno SDK. +- [Build your agent platform](/agent-platform/overview) with a coding agent. From 3b9fb360f3fdc89cd1e069558df016a91f243b6a Mon Sep 17 00:00:00 2001 From: Ashpreet Date: Sun, 19 Jul 2026 11:31:13 +0100 Subject: [PATCH 07/21] docs: prioritize flagship use cases --- docs.json | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs.json b/docs.json index 91ebe91a8..115ec8e41 100644 --- a/docs.json +++ b/docs.json @@ -130,6 +130,19 @@ "use-cases/product-agents/interfaces" ] }, + "use-cases/workflow-automation", + { + "group": "Data Labeling & Classification", + "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" + ] + }, "use-cases/customer-support", "use-cases/knowledge-assistants", "use-cases/coding-agents", @@ -167,20 +180,7 @@ "use-cases/document-processing/batch-and-durability", "use-cases/document-processing/human-routing-and-eval" ] - }, - { - "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" - ] - }, - "use-cases/workflow-automation" + } ] } ] From ff5e2ae56935d371c71eea0b0220a697610473e3 Mon Sep 17 00:00:00 2001 From: Ashpreet Date: Sun, 19 Jul 2026 12:01:45 +0100 Subject: [PATCH 08/21] docs: refine flagship use cases and navigation --- docs.json | 15 ++- features/control-plane.mdx | 91 ++++++++++++++++ use-cases/coding-agents.mdx | 4 +- use-cases/customer-support.mdx | 3 +- use-cases/data-labeling/image-search.mdx | 100 ++++++++++++++++++ ...ge-assistants.mdx => knowledge-agents.mdx} | 22 ++-- use-cases/product-agents/interfaces.mdx | 6 +- use-cases/product-agents/overview.mdx | 8 +- use-cases/product-agents/serve-as-an-api.mdx | 2 +- use-cases/workflow-automation.mdx | 2 +- 10 files changed, 225 insertions(+), 28 deletions(-) create mode 100644 features/control-plane.mdx create mode 100644 use-cases/data-labeling/image-search.mdx rename use-cases/{knowledge-assistants.mdx => knowledge-agents.mdx} (86%) diff --git a/docs.json b/docs.json index 115ec8e41..78b141509 100644 --- a/docs.json +++ b/docs.json @@ -107,7 +107,7 @@ "pages": [ "features/sdk", "features/runtime", - "agent-os/control-plane", + "features/control-plane", "features/api", "features/storage", "features/observability", @@ -135,19 +135,20 @@ "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/multimodal-inputs", "use-cases/data-labeling/quality-pipeline" ] }, "use-cases/customer-support", - "use-cases/knowledge-assistants", + "use-cases/knowledge-agents", "use-cases/coding-agents", { - "group": "Data & Analytics Agents", + "group": "Data & Analytics", "pages": [ "use-cases/data-agents/overview", "use-cases/data-agents/querying-your-data", @@ -159,7 +160,7 @@ ] }, { - "group": "Deep Research & Analysis", + "group": "Deep Research", "pages": [ "use-cases/deep-research/overview", "use-cases/deep-research/orchestration-patterns", @@ -8973,6 +8974,10 @@ ] }, "redirects": [ + { + "source": "/use-cases/knowledge-assistants", + "destination": "/use-cases/knowledge-agents" + }, { "source": "/examples/agent-os/mcp-demo/enable-mcp-example", "destination": "/examples/agent-os/mcp-demo/mcp-server-example" diff --git a/features/control-plane.mdx b/features/control-plane.mdx new file mode 100644 index 000000000..19b816e16 --- /dev/null +++ b/features/control-plane.mdx @@ -0,0 +1,91 @@ +--- +title: AgentOS Control Plane +description: "Test, inspect, and manage an AgentOS runtime from a web interface." +--- + +The AgentOS Control Plane is the web interface for working with the agents, teams, and workflows served by your AgentOS runtime. + + + AgentOS Control Plane showing agents, teams, workflows, and connected runtimes + + +Start a local runtime with a database, tracing, and the scheduler: + +```bash +uv pip install -U "agno[openai,os,sqlite]" +export OPENAI_API_KEY=*** +``` + +```python control_plane.py +from agno.agent import Agent +from agno.db.sqlite import SqliteDb +from agno.models.openai import OpenAIResponses +from agno.os import AgentOS + +db = SqliteDb(db_file="tmp/agent.db") + +agent = Agent( + id="assistant", + model=OpenAIResponses(id="gpt-5.5"), + db=db, +) + +agent_os = AgentOS( + agents=[agent], + db=db, + tracing=True, + scheduler=True, +) +app = agent_os.get_app() + +if __name__ == "__main__": + agent_os.serve(app="control_plane:app", reload=True) +``` + +Open [os.agno.com](https://os.agno.com), add a local AgentOS, and connect `http://localhost:7777`. + +## What you can do + +| Developer task | Control Plane capability | +|----------------|--------------------------| +| Test components | Chat with registered agents and teams, run workflows, and follow streamed output | +| Debug runs | Browse sessions and inspect model, tool, agent, team, and workflow spans when tracing is enabled | +| Manage context | Search knowledge content and view or update memories exposed by the runtime | +| Build in Studio | Compose and version agents, teams, and workflows from a registered component catalog | +| Review approvals | Inspect and resolve approval records created by approval-enabled tools | +| Operate schedules | Create, enable, disable, trigger, and inspect schedules backed by the AgentOS database | + +Studio uses a `Registry` and an AgentOS `db`. Approvals and schedules also require an AgentOS `db`. Set `scheduler=True` to run enabled cron schedules automatically. + +## How the connection works + +| Layer | Responsibility | +|-------|----------------| +| Browser | Loads the control plane and sends requests to the AgentOS endpoint you connect | +| AgentOS runtime | Runs components, exposes FastAPI endpoints, and applies the authentication and authorization you configure | +| Configured databases | Store the sessions, memories, traces, approvals, schedules, and Studio component versions available through the runtime | + +Runtime records shown in the control plane are read through your AgentOS API. Model providers, tools, telemetry, interfaces, and custom exporters follow their own configuration and data paths. + +For production, serve AgentOS over HTTPS and configure [Security & Auth](/agent-os/security/overview) before connecting the endpoint. + +## Development workflow + +1. Register your agents, teams, and workflows with AgentOS. +2. Start the runtime and connect its endpoint. +3. Run representative inputs from the chat interface. +4. Inspect the session and trace when a result needs attention. +5. Update the component in Python or Studio, then run it again. +6. Connect the deployed runtime and apply its production access controls. + +## Developer Resources + +- [Full Control Plane guide](/agent-os/control-plane) +- [Build and version components in Studio](/agent-os/studio/introduction) +- [Configure AgentOS tracing](/agent-os/tracing/overview) +- [Review and resolve approvals](/agent-os/approvals/overview) +- [Configure Security & Auth](/agent-os/security/overview) diff --git a/use-cases/coding-agents.mdx b/use-cases/coding-agents.mdx index 2a5358ffc..c325b1322 100644 --- a/use-cases/coding-agents.mdx +++ b/use-cases/coding-agents.mdx @@ -1,6 +1,6 @@ --- title: Coding Agents -sidebarTitle: Build Coding Agents +sidebarTitle: Coding Agents description: "Build coding agents that inspect repositories, edit files, run commands, and verify changes." --- @@ -72,7 +72,7 @@ The example creates a fresh fixture on every run. `base_dir` scopes file operati -This page covers building coding agents with Agno. To give Codex, Claude Code, Cursor, or another client access to Agno documentation, see [Connect your coding agent](/coding-agents). +To give Codex, Claude Code, Cursor, or another client access to Agno documentation, see [Connect your coding agent](/coding-agents). ## Common patterns diff --git a/use-cases/customer-support.mdx b/use-cases/customer-support.mdx index 6d4b0ade3..c0414ada6 100644 --- a/use-cases/customer-support.mdx +++ b/use-cases/customer-support.mdx @@ -1,5 +1,6 @@ --- title: Customer Support Agents +sidebarTitle: Customer Support description: "Resolve customer requests with specialist routing, product knowledge, controlled actions, and human escalation." --- @@ -52,7 +53,7 @@ uv pip install -U "agno[openai,sqlite]" uv run python support_team.py ``` -The team can consult both specialists for this request. Reuse the `session_id` for later messages on the same ticket and the `user_id` for the same customer. This example routes requests and stores session history. Add confirmation-required tools before permitting account changes or refunds. +The team can consult both specialists for this request. Reuse the `session_id` for later messages on the same ticket and the `user_id` for the same customer. Add confirmation-required tools before permitting account changes or refunds. ## Build the resolution path diff --git a/use-cases/data-labeling/image-search.mdx b/use-cases/data-labeling/image-search.mdx new file mode 100644 index 000000000..4b3b3c641 --- /dev/null +++ b/use-cases/data-labeling/image-search.mdx @@ -0,0 +1,100 @@ +--- +title: "Build an image search application" +sidebarTitle: "Image Search" +description: "Describe images with an agent, index the descriptions in PgVector, and search the collection from a browser UI." +--- + +Run the complete Image Search application from the Agno repository: + +```bash +uv venv .venvs/image_search --python 3.12 +source .venvs/image_search/bin/activate +uv pip install -e "libs/agno[os,google]" "fastapi[standard]" pgvector "psycopg[binary]" +./cookbook/scripts/run_pgvector.sh +export GOOGLE_API_KEY="..." +fastapi dev cookbook/data_labeling/image_search/run.py --port 7777 +``` + +Open [http://localhost:7777/ui](http://localhost:7777/ui), then click **Reindex** to label and index the configured images. + +## Application structure + +The application registers one `Knowledge` instance and one ingest workflow with AgentOS. A small FastAPI route serves the browser UI. + +```python +from agno.os import AgentOS +from db import get_knowledge +from fastapi import FastAPI +from workflows.ingest import ingest_workflow + + +base_app = FastAPI(title="Image Search") + +agent_os = AgentOS( + id="image_search", + name="Image Search", + knowledge=[get_knowledge()], + workflows=[ingest_workflow], + base_app=base_app, +) + +app = agent_os.get_app() +``` + +| Part | Implementation | +|------|----------------| +| Label | A Gemini agent returns an `ImageDescription` with a caption, subjects, scene, visual style, and tags. | +| Index | `to_searchable_text()` flattens those fields into the text sent to `GeminiEmbedder`. | +| Search | `PgVector` combines vector and keyword search with `SearchType.hybrid`. | +| Metadata | `Knowledge` stores the image URL and structured description for the gallery. | +| Ingest | A `Workflow` downloads each image, creates a searchable description, and stores the embedded description, structured metadata, and source URL. | +| UI | A single HTML file renders the gallery, search results, and reindex status. | + +## Search-tuned labels + +The schema separates fields that help with different queries: + +```python +from typing import List + +from pydantic import BaseModel, Field + + +class ImageDescription(BaseModel): + caption: str + subjects: List[str] = Field(default_factory=list) + scene: str + visual_style: str + tags: List[str] = Field(default_factory=list) +``` + +The caption captures a natural description. Subjects and tags add the concrete terms users search for. Scene and visual style support queries about setting, lighting, mood, and composition. + +## Reindex behavior + +Reindexing performs a full rebuild. The workflow removes the existing knowledge content, then processes every URL in `IMAGE_URLS` with a bounded thread pool. This makes prompt and schema changes visible across the complete demo collection. + +The workflow uses `PostgresDb` so AgentOS can persist background workflow runs. The same Postgres instance stores knowledge content, while PgVector stores embeddings and serves hybrid search. + +## Routes + +| Action | Route | +|--------|-------| +| Open the UI | `GET /ui` | +| List gallery content | `GET /knowledge/content` | +| Search the image index | `POST /knowledge/search` | +| Start a reindex run | `POST /workflows/image-ingest/runs` | + +## Next steps + +| Task | Guide | +|------|-------| +| Build the minimal extract-and-index pipeline | [Data extraction](/use-cases/data-labeling/structured-extraction#extract-then-index) | +| Define a different media schema | [Multimodal inputs](/use-cases/data-labeling/multimodal-inputs) | +| Configure knowledge search | [Knowledge](/knowledge/overview) | + +## Developer Resources + +- [Image Search source](https://github.com/agno-agi/agno/tree/main/cookbook/data_labeling/image_search) +- [Image extraction to vector database cookbook](https://github.com/agno-agi/agno/tree/main/cookbook/data_labeling/_09_image_extraction_to_vectordb) +- [AgentOS](/agent-os/introduction) diff --git a/use-cases/knowledge-assistants.mdx b/use-cases/knowledge-agents.mdx similarity index 86% rename from use-cases/knowledge-assistants.mdx rename to use-cases/knowledge-agents.mdx index 13f7ab9e5..dc194f001 100644 --- a/use-cases/knowledge-assistants.mdx +++ b/use-cases/knowledge-agents.mdx @@ -1,11 +1,11 @@ --- -title: Knowledge Assistants & RAG -description: "Ground agent responses in indexed content with controlled ingestion, retrieval, filtering, and source updates." +title: Knowledge Agents +description: "Build agents that answer from indexed content with controlled ingestion, retrieval, filtering, and source updates." --- -A knowledge assistant indexes a maintained corpus and retrieves relevant content when needed. +A knowledge agent indexes a maintained corpus and retrieves relevant content when needed. -```python knowledge_assistant.py +```python knowledge_agent.py from agno.agent import Agent from agno.knowledge.embedder.openai import OpenAIEmbedder from agno.knowledge.knowledge import Knowledge @@ -32,8 +32,8 @@ knowledge.insert( skip_if_exists=True, ) -assistant = Agent( - name="Policy Assistant", +agent = Agent( + name="Policy Agent", model="openai:gpt-5.5", knowledge=knowledge, search_knowledge=True, @@ -43,19 +43,19 @@ assistant = Agent( ], ) -assistant.print_response("When does travel need VP approval?", stream=True) +agent.print_response("When does travel need VP approval?", stream=True) ``` -Create a virtual environment, install the OpenAI and ChromaDB integrations, and set `OPENAI_API_KEY` before running the assistant: +Create a virtual environment, install the OpenAI and ChromaDB integrations, and set `OPENAI_API_KEY` before running the agent: ```bash uv venv --python 3.12 uv pip install -U "agno[chromadb,openai]" export OPENAI_API_KEY="your_openai_api_key" -uv run python knowledge_assistant.py +uv run python knowledge_agent.py ``` -The assistant decides when to search the indexed policy. ChromaDB persists the embedded content under `tmp/chromadb` for later runs. +The agent decides when to search the indexed policy. ChromaDB persists the embedded content under `tmp/chromadb` for later runs. ## Choose the information path @@ -106,7 +106,7 @@ Reindex older content before enabling isolated vector search if its vectors do n | Task | Guide | |------|-------| -| Build the first indexed assistant | [Knowledge quickstart](/knowledge/quickstart) | +| Build your first indexed agent | [Knowledge quickstart](/knowledge/quickstart) | | Combine several source types | [Multi-source RAG](/examples/knowledge/production/multi-source-rag) | | Share retrieval across specialists | [Knowledge for teams](/knowledge/teams/overview) | | Query live systems instead of an index | [Connecting your data](/use-cases/product-agents/connecting-your-data) | diff --git a/use-cases/product-agents/interfaces.mdx b/use-cases/product-agents/interfaces.mdx index 44ef9b1cc..f32146758 100644 --- a/use-cases/product-agents/interfaces.mdx +++ b/use-cases/product-agents/interfaces.mdx @@ -1,9 +1,9 @@ --- title: "Interfaces" -description: "Slack, Telegram, WhatsApp, and browser surfaces, all through the AgentOS." +description: "Connect agents to Slack, Telegram, WhatsApp, and browser clients through AgentOS." --- -Interfaces plug your agent into Slack, Telegram, WhatsApp, and browser clients. +Register an agent with Slack, Telegram, WhatsApp, or a browser interface. ```python from agno.agent import Agent @@ -53,7 +53,7 @@ For Telegram and WhatsApp, `/new` preserves earlier sessions and creates a sessi Stored memory can follow a user across surfaces when the interfaces resolve to the same `user_id` and use the same agent database and memory configuration. Session history remains scoped to each interface-generated `session_id`. Interfaces can add surface metadata and dependencies to a run. -## One agent, every surface +## Register several interfaces ```python from agno.os.interfaces.a2a import A2A diff --git a/use-cases/product-agents/overview.mdx b/use-cases/product-agents/overview.mdx index 271d5a8a4..5ef43452e 100644 --- a/use-cases/product-agents/overview.mdx +++ b/use-cases/product-agents/overview.mdx @@ -4,7 +4,7 @@ sidebarTitle: "Overview" description: "Serve agents across product surfaces with shared database-backed sessions and memory." --- -A product agent can serve chat, inline actions, background jobs, and messaging interfaces from one AgentOS. Configure a shared database when those surfaces need the same sessions or user memories. +Serve the same product agent through chat, inline actions, background jobs, and messaging interfaces. A shared AgentOS database keeps sessions and user memory available across those surfaces. ```python copilot.py from agno.agent import Agent @@ -32,7 +32,7 @@ if __name__ == "__main__": This configuration provides an HTTP API, persistent multi-turn history, and per-user memory. Authentication is disabled until you enable it. See [Serve as an API](/use-cases/product-agents/serve-as-an-api#auth) for JWT authorization and opt-in per-user isolation. -## The mental model +## How product surfaces connect The agent runs in your AgentOS as a service. Every product surface is a client that calls it over HTTP. @@ -45,13 +45,13 @@ The agent runs in your AgentOS as a service. Every product surface is a client t Stored memory can follow a user when surfaces call the same agent with the same `user_id` and database. Session history continues only when they also reuse the same `session_id`. Messaging interfaces usually create surface-specific session IDs. -## Guided paths +## Choose a path | You have | You want | Start with | |----------|----------|------------| | A B2B SaaS product | JWT authentication and opt-in per-user isolation | [Serve as an API](/use-cases/product-agents/serve-as-an-api) | | Users in Slack or the browser | The same agent where they already work | [Interfaces](/use-cases/product-agents/interfaces) | -| An indexed document corpus | Answers grounded in retrieved content | [Knowledge assistants and RAG](/use-cases/knowledge-assistants) | +| An indexed document corpus | Answers grounded in retrieved content | [Knowledge agents](/use-cases/knowledge-agents) | | Live systems such as Slack, Drive, or databases | Current records queried at run time | [Connecting your data](/use-cases/product-agents/connecting-your-data) | | Multi-day user relationships | Memory that persists per user across surfaces | [Sessions and memory](/use-cases/product-agents/sessions-and-memory) | diff --git a/use-cases/product-agents/serve-as-an-api.mdx b/use-cases/product-agents/serve-as-an-api.mdx index a085475b7..1d34bd8a6 100644 --- a/use-cases/product-agents/serve-as-an-api.mdx +++ b/use-cases/product-agents/serve-as-an-api.mdx @@ -119,7 +119,7 @@ async function askCopilot(message, threadId, jwt) { | Long job, poll later | `background=true` and `stream=false` | | User and thread attribution | `user_id` and a per-thread `session_id` | -## What you get without building it +## AgentOS endpoints | Endpoint group | Covers | |-----------------|--------| diff --git a/use-cases/workflow-automation.mdx b/use-cases/workflow-automation.mdx index 2e7443be5..99b923fb9 100644 --- a/use-cases/workflow-automation.mdx +++ b/use-cases/workflow-automation.mdx @@ -3,7 +3,7 @@ title: Workflow Automation description: "Run repeatable processes with workflows, background execution, human review, and schedules." --- -A workflow gives agents and functions a defined execution path: +Use a workflow when each run should follow the same steps, branches, or approval gates. ```python incident_workflow.py from agno.agent import Agent From 1a785f1faadf01193ba8a33b3dca8b1d06f1beb0 Mon Sep 17 00:00:00 2001 From: Ashpreet Date: Sun, 19 Jul 2026 12:02:00 +0100 Subject: [PATCH 09/21] docs: deepen data labeling guides --- use-cases/data-labeling/classification.mdx | 8 +- use-cases/data-labeling/llm-as-judge.mdx | 4 +- use-cases/data-labeling/multimodal-inputs.mdx | 4 +- use-cases/data-labeling/overview.mdx | 89 +++------- use-cases/data-labeling/quality-pipeline.mdx | 167 ++++++++---------- .../data-labeling/structured-extraction.mdx | 23 +-- 6 files changed, 115 insertions(+), 180 deletions(-) diff --git a/use-cases/data-labeling/classification.mdx b/use-cases/data-labeling/classification.mdx index 4d09e5063..823892f80 100644 --- a/use-cases/data-labeling/classification.mdx +++ b/use-cases/data-labeling/classification.mdx @@ -3,7 +3,7 @@ title: "Classification and span labeling" description: "Assign one label, a set of labels, a taxonomy path, or marked spans." --- -Classification is extraction where the schema is a closed set. Use a `Literal` for one label, a `List[Literal]` for many. +Use a `Literal` for one label and a `List[Literal]` for multiple labels. ```python from typing import Literal @@ -29,7 +29,7 @@ result = agent.run("It works as described, nothing special.").content # Classification(label='neutral') ``` -The `Literal` constrains the model to the closed set. There is no invalid label to clean up downstream. +The `Literal` constrains the result to the labels defined in the schema. ## Multi-label @@ -51,7 +51,7 @@ class Tagging(BaseModel): ## Hierarchical -For a taxonomy, return the path instead of a flat label. +For a taxonomy, return the parent and child path. ```python from typing import List, Literal @@ -138,7 +138,7 @@ Image, audio, video, and document classification follow the same schema pattern | Task | Guide | |------|-------| -| Extract fields instead of labels | [Data extraction](/use-cases/data-labeling/structured-extraction) | +| Extract typed fields | [Data extraction](/use-cases/data-labeling/structured-extraction) | | Score outputs against a rubric | [LLM as judge](/use-cases/data-labeling/llm-as-judge) | | Add reviewer agreement | [Quality pipeline](/use-cases/data-labeling/quality-pipeline) | diff --git a/use-cases/data-labeling/llm-as-judge.mdx b/use-cases/data-labeling/llm-as-judge.mdx index ecab5487f..147ed4d9d 100644 --- a/use-cases/data-labeling/llm-as-judge.mdx +++ b/use-cases/data-labeling/llm-as-judge.mdx @@ -73,11 +73,11 @@ class RubricScore(BaseModel): | One quality number | `int` with `ge=1, le=5` | | Number plus justification | Add a `rationale` field | | Per-criterion breakdown | One bounded `int` field per dimension | -| A vs B instead of a score | [Preference data](/use-cases/data-labeling/preference-data) | +| Pairwise comparison | [Preference data](/use-cases/data-labeling/preference-data) | ## Relationship to evals -This is the same primitive as single-label classification, pointed at model outputs instead of raw data. When the judge is the deliverable, it lives here. When it scores a system under test, see [Evals](/evals/overview). +This applies a classification schema to model outputs. When the judge is the deliverable, it lives here. When it scores a system under test, see [Evals](/evals/overview). ## Next steps diff --git a/use-cases/data-labeling/multimodal-inputs.mdx b/use-cases/data-labeling/multimodal-inputs.mdx index 71598e7a5..04a600de4 100644 --- a/use-cases/data-labeling/multimodal-inputs.mdx +++ b/use-cases/data-labeling/multimodal-inputs.mdx @@ -3,7 +3,7 @@ title: "Multimodal inputs" description: "Feed images, audio, video, and PDFs into any labeling or extraction agent." --- -Every labeler on the other pages takes text. To label other modalities, change the input argument and the model. The schema and the `output_schema` pattern stay the same. +Pass media through the matching `Agent.run()` argument and choose a model that supports the input modality. The `output_schema` pattern stays the same. ```python from typing import Literal @@ -89,7 +89,7 @@ class BoundingBox(BaseModel): ``` -The per-field `description` on `x`, `y`, `width`, and `height` is load-bearing. Without it, and without the `[0, 1]` convention spelled out in the instructions, models return degenerate boxes (all-zero or whole-image). Spell out the coordinate system in both places. +State the `[0, 1]` coordinate system in both the field descriptions and the agent instructions. This keeps the four values consistent across images. The [bounding boxes cookbook](https://github.com/agno-agi/agno/tree/main/cookbook/data_labeling/_08_image_bounding_boxes) has runnable single-object, multi-object, and per-box confidence variants. diff --git a/use-cases/data-labeling/overview.mdx b/use-cases/data-labeling/overview.mdx index 59cef9628..132e000ff 100644 --- a/use-cases/data-labeling/overview.mdx +++ b/use-cases/data-labeling/overview.mdx @@ -1,27 +1,15 @@ --- title: "Data labeling and classification" sidebarTitle: "Overview" -description: "Label and classify text, images, audio, video, and PDFs." +description: "Classify data, extract records, build preference datasets, and review labels with agents." --- -Agents can: - -- Turn text, images, audio, video, and PDFs into structured records. -- Assign labels, label sets, taxonomy paths, and labeled spans. -- Score and rank model outputs for evals and preference data. -- Add a reviewer and an adjudicator when label quality matters. - -Each task follows a similar pattern: an agent with an `output_schema`. - -`Agent.run()` accepts text and media inputs. Set `output_schema` to validate the response against a Pydantic model. - -## Example +Use an `output_schema` to turn text, images, audio, video, and PDFs into validated labels and records. ```python from typing import Literal from agno.agent import Agent -from agno.models.google import Gemini from pydantic import BaseModel, Field @@ -32,7 +20,7 @@ class Classification(BaseModel): agent = Agent( - model=Gemini(id="gemini-3.5-flash"), + model="google:gemini-3.5-flash", instructions="You classify product reviews by sentiment.", output_schema=Classification, ) @@ -41,68 +29,41 @@ result = agent.run("Broken on arrival, total waste of money.").content # Classification(label='negative') ``` -Swap the schema and instructions and the same pattern covers data extraction, span labeling, scoring, and preference ranking. - - +`Agent.run()` validates the response against the Pydantic model. Change the schema and instructions to extract fields, label spans, score responses, or rank preferences. -If you're looking to jump straight into code, the [data labeling cookbook](https://github.com/agno-agi/agno/tree/main/cookbook/data_labeling) contains 40+ runnable recipes across 18 data labeling patterns. +## What you can build - +| Outcome | Input | Pattern | +|---------|-------|---------| +| Classify feedback, support requests, or documents | Text or files | [Classification](/use-cases/data-labeling/classification) | +| Extract contacts, line items, action items, or attributes | Any supported modality | [Data extraction](/use-cases/data-labeling/structured-extraction) | +| Detect entities and PII spans | Text | [Classification and span labeling](/use-cases/data-labeling/classification) | +| Search an image library in natural language | Images | [Image Search](/use-cases/data-labeling/image-search) | +| Build pairwise preference datasets | Prompt and two responses | [Preference data](/use-cases/data-labeling/preference-data) | +| Score generated responses against a rubric | Prompt and response | [LLM as judge](/use-cases/data-labeling/llm-as-judge) | +| Review and adjudicate important labels | Any labeling task | [Quality pipeline](/use-cases/data-labeling/quality-pipeline) | +| Label images, audio, video, and PDFs | Media or files | [Multimodal inputs](/use-cases/data-labeling/multimodal-inputs) | -## Data labeling workflows +The [data labeling cookbook](https://github.com/agno-agi/agno/tree/main/cookbook/data_labeling) contains 18 labeling patterns and a complete Image Search application. The patterns cover text, image, audio, video, and document inputs. -Pick the page that matches what you need. +## Run the examples -| Workload | Input | Output | Page | -|----------|-------|--------|------| -| Data extraction | Any modality | Typed Pydantic object | [Data extraction](/use-cases/data-labeling/structured-extraction) | -| Classification | Any modality | One label, label set, or spans | [Classification](/use-cases/data-labeling/classification) | -| Scoring / evaluation | Prompt + response | Rubric scores | [LLM as judge](/use-cases/data-labeling/llm-as-judge) | -| Preference ranking | Prompt + two responses | Winner + rationale | [Preference data](/use-cases/data-labeling/preference-data) | -| Non-text input | Image, audio, video, PDF | Any of the above | [Multimodal inputs](/use-cases/data-labeling/multimodal-inputs) | -| Reviewed labels | Any input | Adjudicated label + audit trail | [Quality pipeline](/use-cases/data-labeling/quality-pipeline) | - -## Model choice - -The cookbooks use `gemini-3.5-flash` for text, image, audio, video, and PDF examples. A replacement model must support the input modality and structured output used by the recipe. - -To run the examples, install the Google provider and set your API key: +Create an environment and install the Google provider: ```bash -pip install -U "agno[google]" -export GOOGLE_API_KEY=*** +uv venv .venv --python 3.12 +source .venv/bin/activate +uv pip install "agno[google]" +export GOOGLE_API_KEY="..." ``` -The [Quality pipeline](/use-cases/data-labeling/quality-pipeline) runs its second labeler, reviewer, and adjudicator on Anthropic for provider diversity. That page needs a second provider and key: +The quality review workflow also uses Anthropic: ```bash -pip install -U "agno[anthropic]" -export ANTHROPIC_API_KEY=*** +uv pip install "agno[anthropic]" +export ANTHROPIC_API_KEY="..." ``` -## Explore - - - - Turn any modality into a typed object, with optional per-field confidence. - - - Single-label, multi-label, hierarchical, and span labeling. - - - Score outputs against a rubric. The same machinery, used for evals. - - - Rank A vs B for RLHF and DPO datasets. - - - Feed images, audio, video, and PDFs into any labeler. - - - Two labelers, a reviewer, and an adjudicator with an audit trail. - - - ## Developer Resources - [Data labeling cookbook](https://github.com/agno-agi/agno/tree/main/cookbook/data_labeling) diff --git a/use-cases/data-labeling/quality-pipeline.mdx b/use-cases/data-labeling/quality-pipeline.mdx index afdd69b26..f1737429f 100644 --- a/use-cases/data-labeling/quality-pipeline.mdx +++ b/use-cases/data-labeling/quality-pipeline.mdx @@ -1,122 +1,101 @@ --- -title: "Quality pipeline" -description: "Two labelers from different providers, a reviewer that diffs them, and an adjudicator that resolves disagreement." +title: "Quality review pipeline" +description: "Run two labelers concurrently, persist each workflow run, and adjudicate disagreements." --- -Run two labelers from different providers, compare their outputs, and adjudicate where they disagree. Persist the disagreement report when you need an audit trail. +Use a `Workflow` to run two labelers in parallel, review their outputs, and call an adjudicator when the reviewer finds a disagreement. The [complete cookbook](https://github.com/agno-agi/agno/blob/main/cookbook/data_labeling/_18_quality_review/basic.py) defines the schemas, agents, and executor functions used in this workflow composition: ```python -from typing import List, Optional - -from agno.agent import Agent -from agno.models.anthropic import Claude -from agno.models.google import Gemini -from pydantic import BaseModel, Field - - -class Contact(BaseModel): - name: Optional[str] = None - email: Optional[str] = None - company: Optional[str] = None - - -class FieldDisagreement(BaseModel): - field: str = Field(..., description="Top-level Contact field name") - value_a: Optional[str] = None - value_b: Optional[str] = None - reason: str = Field(..., description="Why this field needs adjudication") - - -class DisagreementReport(BaseModel): - disagreements: List[FieldDisagreement] = Field(default_factory=list) - needs_adjudication: bool = Field(..., description="True if any field disagrees") - - -class FinalLabel(BaseModel): - contact: Contact - notes: Optional[str] = None - - -LABELER = "Extract contact info. Use exactly what the text shows. Null if missing." - -labeler_a = Agent(model=Gemini(id="gemini-3.5-flash"), instructions=LABELER, output_schema=Contact) -labeler_b = Agent(model=Claude(id="claude-opus-4-7"), instructions=LABELER, output_schema=Contact) - -reviewer = Agent( - model=Claude(id="claude-opus-4-7"), - instructions=( - "Compare two labelers' Contact outputs field by field. A field " - "needs adjudication whenever the values differ, including when one " - "value is null. Set " - "needs_adjudication=true if any field does." - ), - output_schema=DisagreementReport, +from agno.db.sqlite import SqliteDb +from agno.workflow import Step, Workflow +from agno.workflow.condition import Condition +from agno.workflow.parallel import Parallel + + +label_a = Step(name="Labeler A", agent=labeler_a) +label_b = Step(name="Labeler B", agent=labeler_b) +review = Step(name="Reviewer", executor=run_reviewer) +adjudicate = Step(name="Adjudicator", executor=run_adjudicator) + +workflow = Workflow( + name="Quality review labeling", + db=SqliteDb(db_file="tmp/labeling.db"), + steps=[ + Parallel(label_a, label_b, name="Label"), + review, + Condition( + name="Adjudicate", + evaluator=has_disagreement, + steps=[adjudicate], + ), + ], ) +``` -adjudicator = Agent( - model=Claude(id="claude-opus-4-7"), - instructions=( - "Re-read the original text and resolve every reported " - "disagreement. Return a FinalLabel with the correct values." - ), - output_schema=FinalLabel, -) +## Execution flow +| Step | What it does | +|------|--------------| +| `Parallel` | Runs a Google labeler and an Anthropic labeler concurrently against the same input. | +| `Reviewer` | Reads both step outputs and returns a typed `DisagreementReport`. | +| `Condition` | Reads `needs_adjudication` from the reviewer output. | +| `Adjudicator` | Receives the original input, both labels, and the disagreement report. It runs only when the condition passes. | +| `SqliteDb` | Persists workflow runs in `tmp/labeling.db`. | -def label_with_quality_review(text: str) -> FinalLabel: - a = labeler_a.run(text).content - b = labeler_b.run(text).content +The cookbook reviewer flags a field when both labelers return non-null, different values. Change the reviewer instructions if a null value and a populated value should also trigger adjudication. - report = reviewer.run( - f"Labeler A:\n{a.model_dump_json()}\n\nLabeler B:\n{b.model_dump_json()}" - ).content +## Pass step outputs to the reviewer - if not report.needs_adjudication: - return FinalLabel(contact=a, notes="Labelers agreed.") +`StepInput.get_step_output()` finds named steps inside the `Parallel` block. The reviewer executor uses those outputs to build its prompt. - return adjudicator.run( - f"Original input:\n{text}\n\n" - f"Labeler A:\n{a.model_dump_json()}\n\n" - f"Labeler B:\n{b.model_dump_json()}\n\n" - f"Reviewer report:\n{report.model_dump_json()}" - ).content +```python +from agno.workflow.types import StepInput, StepOutput + + +def run_reviewer(step_input: StepInput) -> StepOutput: + a = step_input.get_step_output("Labeler A").content + b = step_input.get_step_output("Labeler B").content + prompt = ( + f"Labeler A:\n{a.model_dump_json(indent=2)}\n\n" + f"Labeler B:\n{b.model_dump_json(indent=2)}" + ) + report = reviewer.run(prompt).content + return StepOutput(content=report) ``` -## The flow +The condition reads the reviewer output from `previous_step_content`: -1. **Two labelers, two providers.** Provider disagreement identifies records that need review. -2. **Reviewer diffs them.** It emits one `FieldDisagreement` per conflicting field and a single `needs_adjudication` flag. Agreement short-circuits the expensive step. -3. **Adjudicator runs only on disagreement.** It re-reads the original input with both labels and the reviewer's report, then returns the final record. - -Agreement does not prove that a label is correct. Measure this pipeline on a labeled validation set. Persisted disagreement rates by field, provider, and prompt version can identify areas for review. - -## Production composition +```python +def has_disagreement(step_input: StepInput) -> bool: + report = step_input.previous_step_content + return bool(report and getattr(report, "needs_adjudication", False)) +``` -The example above runs the agents sequentially so the pattern is readable. For a million-document job, wrap labelers in a `Parallel` step and gate the adjudicator behind a `Condition` in a `Workflow`. See [parallel workflows](/workflows/workflow-patterns/parallel-workflow) and [conditional workflows](/workflows/workflow-patterns/conditional-workflow). +## Run the workflow -## Production checklist +From the Agno repository root: -Agno gives you the orchestration primitives. These concerns are yours to add. +```bash +uv venv .venv --python 3.12 +source .venv/bin/activate +uv pip install "agno[google,anthropic]" +export GOOGLE_API_KEY="..." +export ANTHROPIC_API_KEY="..." +python cookbook/data_labeling/_18_quality_review/basic.py +``` -| Concern | What to add | -|---------|-------------| -| Rate limiting | Wrap the agent call with a per-provider limiter, or front it with a gateway. Agno does not throttle outbound calls. | -| Bounded concurrency | An `asyncio.Semaphore` around the batch fan-out. | -| Dead-letter queue | Record failed item IDs and re-run them through a stricter pass. | -| Idempotency | A deterministic item ID and an output-store lookup before each run. Store results by item ID and prompt version. | -| Provider Batch APIs | Call provider batch endpoints directly when the workload needs them. Agno does not wrap these APIs. | -| Prompt versioning | Track a `prompt_version` in run metadata so historical labels stay joinable. | -| Authoritative cost | `RunMetrics.cost` is populated only when the provider returns it. Attach a token-rate table downstream if you need exact numbers. | +Test the workflow against a labeled validation set before using its output. Track reviewer decisions and final labels by prompt and model version so changes remain measurable. ## Next steps | Task | Guide | |------|-------| -| Build the labelers | [Data extraction](/use-cases/data-labeling/structured-extraction) | -| Compose as a workflow | [Workflows](/workflows/overview) | -| Run agents concurrently | [Async execution](/agents/running-agents) | +| Define the label schema | [Data extraction](/use-cases/data-labeling/structured-extraction) | +| Inspect workflow patterns | [Workflows](/workflows/overview) | +| Run independent branches | [Parallel workflows](/workflows/workflow-patterns/parallel-workflow) | +| Gate a step on a result | [Conditional workflows](/workflows/workflow-patterns/conditional-workflow) | ## Developer Resources - [Quality review cookbook](https://github.com/agno-agi/agno/tree/main/cookbook/data_labeling/_18_quality_review) -- [Workflows overview](/workflows/overview) +- [Workflow reference](/reference/workflows/workflow) diff --git a/use-cases/data-labeling/structured-extraction.mdx b/use-cases/data-labeling/structured-extraction.mdx index c23b6b718..5d975f24c 100644 --- a/use-cases/data-labeling/structured-extraction.mdx +++ b/use-cases/data-labeling/structured-extraction.mdx @@ -5,10 +5,6 @@ description: "Extract typed Pydantic objects from text, images, audio, video, an Define the schema, pass the input, get a validated object back. - -Use a fast, low-cost model like `gemini-3.5-flash` for high-volume extraction. - - ```python from typing import Optional @@ -42,7 +38,7 @@ result = agent.run( # phone='+1-555-0102', company='Acme Corp.', title='VP of Marketing') ``` -The hard part is getting missing fields back as `null` instead of a hallucinated value. Spell it out in the instructions: "If a field is missing, leave it null. Do not guess." +Tell the agent how to handle missing fields: "If a field is missing, leave it null. Do not guess." ## Nested objects @@ -108,11 +104,7 @@ confidence_agent = Agent( ) ``` -Define the levels in the instructions. Without a rubric the model has nothing to anchor `high` against `medium`, and the confidence values come back arbitrary. - - -OpenAI strict structured output rejects a `description` on a field whose type is itself a referenced model. Keep `Field(..., description=...)` off fields typed as a sub-model; put the explanation in a comment or the instructions instead. - +Define each confidence level in the instructions so labels use the same criteria across records. ## Any modality, same pattern @@ -126,21 +118,24 @@ The input argument changes per modality. Use a model that supports both that mod | Video | `videos=[Video(content=..., format="mp4")]` | [video_extraction](https://github.com/agno-agi/agno/tree/main/cookbook/data_labeling/_14_video_extraction) | | PDF | `files=[File(url=...)]` | [document_extraction](https://github.com/agno-agi/agno/tree/main/cookbook/data_labeling/_16_document_extraction) | -## Extract then embed +## Extract then index -`image_extraction_to_vectordb` extends extraction with an embed-and-store step: describe each image into a typed object, flatten it to a searchable string, embed it, and store it in LanceDb for similarity search. See the [cookbook](https://github.com/agno-agi/agno/tree/main/cookbook/data_labeling/_09_image_extraction_to_vectordb). +The [image extraction to vector database cookbook](https://github.com/agno-agi/agno/tree/main/cookbook/data_labeling/_09_image_extraction_to_vectordb) is the minimal pipeline. It describes each image as a typed object, flattens the object into searchable text, embeds it, and stores it in LanceDb. This recipe needs LanceDb on top of the Google provider: ```bash -pip install lancedb tantivy +uv pip install lancedb tantivy ``` +The [Image Search application](/use-cases/data-labeling/image-search) expands the same pattern into an ingest workflow, PgVector hybrid search, AgentOS endpoints, and a browser UI. + ## Next steps | Task | Guide | |------|-------| -| Assign labels instead of fields | [Classification](/use-cases/data-labeling/classification) | +| Assign labels | [Classification](/use-cases/data-labeling/classification) | +| Build a searchable image library | [Image Search](/use-cases/data-labeling/image-search) | | Feed non-text input | [Multimodal inputs](/use-cases/data-labeling/multimodal-inputs) | | Add a reviewer and adjudicator | [Quality pipeline](/use-cases/data-labeling/quality-pipeline) | From 0a1dc32f4b3db2fda12b2076c288abafbdbc0fa7 Mon Sep 17 00:00:00 2001 From: Ashpreet Date: Sun, 19 Jul 2026 12:02:15 +0100 Subject: [PATCH 10/21] docs: tighten data and research use cases --- .../data-agents/grounding-in-context.mdx | 16 ++++++------- use-cases/data-agents/materialization.mdx | 24 +++++++++---------- use-cases/data-agents/overview.mdx | 4 ++-- use-cases/data-agents/querying-your-data.mdx | 2 +- use-cases/data-agents/safe-data-access.mdx | 8 +++---- use-cases/data-agents/serve-and-embed.mdx | 10 ++++---- .../deep-research/grounding-research.mdx | 24 +++++++++---------- .../deep-research/institutional-learning.mdx | 22 ++++++++--------- .../deep-research/orchestration-patterns.mdx | 10 ++++---- use-cases/deep-research/overview.mdx | 14 +++++------ .../deep-research/parallel-investigation.mdx | 16 ++++++------- use-cases/deep-research/serve-and-embed.mdx | 12 +++++----- .../deep-research/structured-deliverable.mdx | 24 +++++++++---------- 13 files changed, 93 insertions(+), 93 deletions(-) diff --git a/use-cases/data-agents/grounding-in-context.mdx b/use-cases/data-agents/grounding-in-context.mdx index 7ced6daca..6eb779465 100644 --- a/use-cases/data-agents/grounding-in-context.mdx +++ b/use-cases/data-agents/grounding-in-context.mdx @@ -3,7 +3,7 @@ title: "Grounding in context" description: "Ground every query in validated SQL, table metadata, and business rules." --- -A model knows SQL but it does not know that `revenue` was replaced by `revenue_v2` last March, that "active" excludes trialing accounts, or that MRR is computed net of credits. Grounding provides the missing context. The agent retrieves the relevant context for each question before it writes a line of SQL. +Data agents need your table history and business definitions to write reliable SQL. Add validated queries, table metadata, and business rules to the agent's knowledge. The agent retrieves the relevant context before writing SQL. ```bash uv pip install "agno[openai,pgvector,psycopg,sql]" @@ -39,9 +39,9 @@ agent = Agent( agent.print_response("How many active subscriptions are on the Pro plan?") ``` -With `knowledge` attached, the agent searches it per question and pulls only the matching context, instead of carrying the entire data dictionary in every prompt. Knowledge search is on by default. Set `search_knowledge=False` to turn it off. +With `knowledge` attached, the agent searches it for each question and retrieves the matching context. Knowledge search is on by default. Set `search_knowledge=False` to turn it off. -## The layers worth curating +## Context to curate A production data agent grounds each answer in several layers. The first set is curated and stored in a vector database. The rest are live. @@ -54,18 +54,18 @@ A production data agent grounds each answer in several layers. The first set is | Learnings | Fixes the agent captured from past errors | Live, see [Self-correcting agents](/use-cases/data-agents/self-correcting-agents) | | Runtime schema | `describe_table` at query time | Live | -## Validated queries are the highest-leverage layer +## Start with validated queries -One known-good query for "monthly recurring revenue" is worth more than a page of schema notes. When the agent retrieves a validated query for a similar question, it adapts a correct shape instead of inventing one. Seed the store with the queries your analysts already trust: the question, the SQL, the tables used, and any data-quality notes. +Validated queries give the agent a trusted starting point for recurring questions such as monthly recurring revenue. For a related request, the agent can retrieve a known-good query and adapt its structure. Store the question, SQL, tables used, and data-quality notes for queries your analysts already trust. ## Grounding vs raw text-to-SQL | Raw text-to-SQL | Grounded data agent | |-----------------|---------------------| | Guesses column meaning from names | Reads curated table metadata | -| Reinvents each query from scratch | Adapts a validated query | -| "Active" means whatever the model assumes | "Active" means what your business rule says | -| Wrong in a way that looks right | Wrong in a way you can trace to a missing rule | +| Generates each query from schema alone | Adapts a validated query when one matches | +| Infers business meaning | Applies curated business definitions | +| Depends on implicit assumptions | Uses retrieved rules and query patterns | ## Next steps diff --git a/use-cases/data-agents/materialization.mdx b/use-cases/data-agents/materialization.mdx index 0e599d4e0..ef2c46ae9 100644 --- a/use-cases/data-agents/materialization.mdx +++ b/use-cases/data-agents/materialization.mdx @@ -3,17 +3,17 @@ title: "Materialization" description: "Turn validated recurring queries into reusable views in an agent-owned schema." --- -The third time someone asks "what's MRR by plan," the agent should be reading a view it built the first time. Materialization is the data agent turning recurring questions into durable, reusable structure in a schema it owns. +Materialization turns recurring, validated queries into reusable views in an agent-owned schema. Later requests can read the same view and use consistent query logic. ## The pattern -A recurring question is a signal. The agent promotes it from an ad-hoc query to a view in an agent-managed schema, then answers from the view. +A recurring question is a candidate for a view. The agent promotes the validated query to an agent-managed schema and answers future requests from that view. 1. A question repeats, or a query gets validated as correct. 2. The agent proposes the view and a human approves the write. 3. The Engineer builds the view in its own schema (for example `dash`), never in `public`. 4. The new object's schema and an example query go into knowledge, so later runs can discover it. -5. The next ask reads the view directly, which is faster, cheaper, and consistent across users. +5. The next request reads the view directly and uses the same query logic across users. ```bash uv pip install "agno[openai,psycopg,sql]" @@ -42,35 +42,35 @@ engineer = Agent( Configure `dash_writer` as a non-owner role with read access to source data and write access only to `dash`. `requires_confirmation_tools` pauses every `run_sql_query` call. After the client continues the run with approval, `SQLTools` executes the statement. The role's grants must enforce the schema boundary because `SQLTools` does not restrict SQL by schema. -After creation, add the object's columns, purpose, and example queries to the agent's knowledge, so later runs discover the view instead of rebuilding the query. Attach the `knowledge` store from [grounding](/use-cases/data-agents/grounding-in-context) to the Engineer and set `update_knowledge=True`. That gives the agent an `add_to_knowledge` tool, which writes the description back into the same store it searches. +After creation, add the object's columns, purpose, and example queries to the agent's knowledge so later runs can discover the view. Attach the `knowledge` store from [grounding](/use-cases/data-agents/grounding-in-context) to the Engineer and set `update_knowledge=True`. That gives the agent an `add_to_knowledge` tool, which writes the description back into the same store it searches. ## Why an agent-owned schema -The agent writes structure, so that structure needs a sandbox. A dedicated schema keeps generated views away from the tables your product depends on. +Give generated views a dedicated schema. This keeps them separate from the tables your product depends on. | | `public` (your data) | `dash` (agent-owned) | |--|----------------------|----------------------| | Who writes | Your application and pipelines | The Engineer agent only | | Holds | Source tables | Generated views and summary tables | -| Blast radius of a bad write | Catastrophic | Contained, droppable, rebuildable | +| Effect of an incorrect write | Production tables may be affected | Limited to generated objects; the schema can be rebuilt | -Because the schema is disposable, a wrong view is a cheap mistake. Drop it and let the agent rebuild. +Treat the agent-owned schema as rebuildable. Review and drop incorrect views, then generate them again. ## Materialize from validated queries -The best materialization candidates are the validated queries from [grounding](/use-cases/data-agents/grounding-in-context). A query analysts already trust, asked often, is exactly what should become a view. Review the generated DDL before approving the write. +Validated queries from [grounding](/use-cases/data-agents/grounding-in-context) are good materialization candidates. A frequently requested query that analysts already trust can become a view. Review the generated DDL before approving the write. A regular view evaluates its query when read. Summary tables and materialized views need explicit refresh logic; this example does not schedule that work. -## How it compounds +## Reuse validated work -Each repeat question promoted to a view is one less query generated from scratch: +Reusable views reduce repeated query generation: - Captured corrections inform later runs ([self-correction](/use-cases/data-agents/self-correcting-agents)). - Validated query shapes sit in the knowledge stores ([grounding](/use-cases/data-agents/grounding-in-context)). -- The agent-owned schema accumulates the views your team relies on, with no hand-written migration. +- The agent-owned schema stores reusable views for recurring questions. -Repeated work becomes structure instead of recomputation, so the agent gets faster and more consistent the more it is used. +Each approved view gives later runs a consistent query path for the same question. ## Next steps diff --git a/use-cases/data-agents/overview.mdx b/use-cases/data-agents/overview.mdx index a2c0c0a28..4463c7452 100644 --- a/use-cases/data-agents/overview.mdx +++ b/use-cases/data-agents/overview.mdx @@ -1,10 +1,10 @@ --- title: "Data and analytics agents" sidebarTitle: "Overview" -description: "Agents that work on your data, grounded in business context." +description: "Build agents that query operational data, apply business definitions, and return the SQL behind each answer." --- -Data agents query operational data, apply business definitions, and can return the SQL behind an answer. Reliable implementations combine curated context, captured corrections, and database-enforced write boundaries. +Data agents answer questions from operational data, apply your business definitions, and return the SQL behind each result. For production, add curated context, captured corrections, and database-enforced access boundaries. ## Where to start diff --git a/use-cases/data-agents/querying-your-data.mdx b/use-cases/data-agents/querying-your-data.mdx index c9303582b..c78832e5a 100644 --- a/use-cases/data-agents/querying-your-data.mdx +++ b/use-cases/data-agents/querying-your-data.mdx @@ -40,7 +40,7 @@ The agent's `db` and the `SQLTools` connection are separate. `db` stores the age ## Introspect before generating -A data agent that guesses column names is wrong confidently. `SQLTools` ships `list_tables` and `describe_table` so the agent grounds SQL in the real schema. The instruction to introspect first is what makes it reliable. +`SQLTools` provides `list_tables` and `describe_table` so the agent can read the current schema before generating SQL. The instruction above makes schema introspection part of each request. | Tool | Use | |------|-----| diff --git a/use-cases/data-agents/safe-data-access.mdx b/use-cases/data-agents/safe-data-access.mdx index b20aeacd5..f81bb2b21 100644 --- a/use-cases/data-agents/safe-data-access.mdx +++ b/use-cases/data-agents/safe-data-access.mdx @@ -3,7 +3,7 @@ title: "Safe data access" description: "Enforce read and write boundaries with database permissions and transaction settings." --- -A prompt that says "only run SELECT" is a suggestion. A connection that cannot write is a guarantee. A production data agent answers from a read-only connection and isolates any writes to a schema it owns. The boundary holds even when the model goes off-script. +Enforce read-only access with database roles and grants. Use a separate connection with schema-scoped permissions for approved write operations. These controls remain in effect when model output is unexpected. ```bash uv pip install "agno[openai,psycopg,sql]" @@ -28,11 +28,11 @@ analyst = Agent( ) ``` -Create the `readonly` role without write grants before using this connection. The `default_transaction_read_only=on` setting blocks ordinary write statements, but it is a configurable session default. Database ownership and grants remain the security boundary. +Create the `readonly` role without write grants before using this connection. The `default_transaction_read_only=on` setting blocks ordinary write statements. This setting is a configurable session default. Database ownership and grants remain the security boundary. ## Split the roles -Most data-agent questions are read-only. Writes (building a summary table, recording a correction) are rarer and riskier. Separate them into different agents on different connections. +Most data-agent questions are read-only. Separate approved writes, such as building a summary table or recording a correction, into agents with dedicated connections. | Member | Connection | Can do | Cannot do | |--------|-----------|--------|-----------| @@ -56,7 +56,7 @@ def materialize_view(name: str, sql: str) -> str: ... ``` -For a dedicated writer built on `SQLTools`, set `requires_confirmation_tools=["run_sql_query"]`. That pauses every call to the tool, reads included, so a narrow custom write tool gives finer control. Gate the irreversible actions and leave reads ungated, so approval fatigue does not set in. +For a dedicated writer built on `SQLTools`, set `requires_confirmation_tools=["run_sql_query"]`. This pauses every call to the tool, including reads. A narrow custom write tool gives finer control. Gate irreversible actions and leave reads ungated so approval fatigue does not set in. ## Layers of defense diff --git a/use-cases/data-agents/serve-and-embed.mdx b/use-cases/data-agents/serve-and-embed.mdx index abdd2b28e..14dab61d6 100644 --- a/use-cases/data-agents/serve-and-embed.mdx +++ b/use-cases/data-agents/serve-and-embed.mdx @@ -1,9 +1,9 @@ --- title: "Serve and embed" -description: "Put the data agent behind an API so a dashboard, a Slack channel, or a product widget can ask it questions." +description: "Serve a data agent through AgentOS for use in dashboards, Slack, and product interfaces." --- -A data agent that only runs in a notebook helps one analyst. Behind an API, it answers questions from a Slack channel, a BI dashboard's natural-language box, or an "explain this metric" widget in your product. `AgentOS` turns the agent into that API. +`AgentOS` exposes the data agent through a FastAPI application. Slack, BI dashboards, scheduled jobs, and product widgets can call the same agent endpoint. ```python data_agent.py from agno.agent import Agent @@ -37,7 +37,7 @@ curl -X POST http://localhost:7777/agents/data-agent/runs \ -F 'stream=false' ``` -## Surfaces a data agent lives on +## Where to use a data agent | Surface | Shape | |---------|-------| @@ -46,7 +46,7 @@ curl -X POST http://localhost:7777/agents/data-agent/runs \ | Scheduled digest | A cron job runs the agent and posts "yesterday's numbers" every morning | | Backend check | A pipeline calls the agent to sanity-check a metric before publishing | -The serving model is identical to a [product agent](/use-cases/product-agents/serve-as-an-api). The difference is what the agent does, not how it is served. `user_id` and `session_id` select the conversation history for a run. +Data agents use the same serving model as [product agents](/use-cases/product-agents/serve-as-an-api). `user_id` and `session_id` select the conversation history for a run. This example leaves AgentOS authorization disabled. Callers can supply their own user and session identifiers. Enable AgentOS authorization before network exposure, and connect `SQLTools` with a database role that enforces read-only access. @@ -54,7 +54,7 @@ The serving model is identical to a [product agent](/use-cases/product-agents/se ## Shared learnings, separate sessions -A data agent's value compounds when corrections are shared across the team. Conversation threads stay scoped by `user_id` and `session_id`. `learning=True` only enables the per-user profile and memory stores, so to share what the agent learns, pass a knowledge base to `LearningMachine` instead. That enables the [Learned Knowledge store](/learning/stores/learned-knowledge), whose namespace defaults to `"global"`, so a fix triggered by one analyst's question helps everyone. +Share diagnosed warehouse corrections across the team while keeping conversation threads scoped by `user_id` and `session_id`. `learning=True` enables the per-user profile and memory stores. To share corrections, pass a knowledge base to `LearningMachine`. This enables the [Learned Knowledge store](/learning/stores/learned-knowledge), whose namespace defaults to `"global"`. ```python from agno.knowledge import Knowledge diff --git a/use-cases/deep-research/grounding-research.mdx b/use-cases/deep-research/grounding-research.mdx index 7cb197631..b6859951b 100644 --- a/use-cases/deep-research/grounding-research.mdx +++ b/use-cases/deep-research/grounding-research.mdx @@ -1,9 +1,9 @@ --- title: "Grounding research" -description: "Ground every agent in a mandate, a research library, and prior work, so conclusions are defensible." +description: "Give each research agent a mandate, a shared research library, and access to prior work." --- -Ungrounded research is confident and wrong. A research agent needs to know the rules it operates under, the body of knowledge it can draw on, and what was decided before. Agno layers these so each agent carries the right context without carrying everything. +Ground each research agent with three forms of context: rules in the prompt, shared source material in a knowledge base, and complete prior work in an archive. Each layer supports a distinct part of the review. | Layer | Holds | Mechanism | |-------|-------|-----------| @@ -13,7 +13,7 @@ Ungrounded research is confident and wrong. A research agent needs to know the r ## Layer 1: static context in the prompt -Rules that apply to every question belong in the prompt, not in retrieval. Load them once and inject them into every agent. +Place rules that apply to every question in the prompt. Load them once and inject them into every agent. ```python from pathlib import Path @@ -64,7 +64,7 @@ reply = analyst.run("What does our research say about semiconductor supply?").co # The instruction tells the analyst to search and cite retrieved material. ``` -`search_knowledge` is on by default. The agent pulls the relevant profiles and analyses per question instead of carrying the whole library in context. +`search_knowledge` is on by default. The agent retrieves relevant profiles and analyses for each question, which keeps the full library out of the prompt. ## Layer 3: prior work on disk @@ -92,17 +92,17 @@ archivist = Agent( ) ``` -The agent that writes new memos gets write access; this one only receives read and search tools. Keep sensitive files outside `memos_dir` because every file under the tool's base directory may be readable. +Give the memo writer write access. This archival agent receives read and search tools. Keep sensitive files outside `memos_dir` because every file under the tool's base directory may be readable. -## Why three layers, not one +## What each layer contributes -| Without | You would lose | -|---------|----------------| -| The prompt | Instructions and context shared across queries | -| RAG | A corpus too large to inline | -| The archive | The reasoning trail behind past decisions | +| Layer | Contribution | +|-------|--------------| +| Prompt | Instructions and context shared across queries | +| RAG | Retrieval from a corpus too large to inline | +| Archive | The reasoning trail behind past decisions | -Each layer answers a different question: what are the rules, what do we know, what did we decide. +Together, the layers cover operating rules, available research, and prior decisions. ## Next steps diff --git a/use-cases/deep-research/institutional-learning.mdx b/use-cases/deep-research/institutional-learning.mdx index a99b25468..49123ef5b 100644 --- a/use-cases/deep-research/institutional-learning.mdx +++ b/use-cases/deep-research/institutional-learning.mdx @@ -1,9 +1,9 @@ --- title: "Institutional learning" -description: "Share what every review learns so the next one starts from the team's accumulated judgment." +description: "Share reviewed insights across agents and teams through a global learning namespace." --- -A research team that does not learn re-derives the same conclusions and repeats the same mistakes. The value compounds when an insight from one review is available to every agent on the next. Agno's `LearningMachine` with a shared store and a global namespace puts every agent's learning in one place the whole team reads from. +Use a shared learning store to carry reviewed insights from one research cycle into the next. Agno's `LearningMachine` with a global namespace makes those learnings available to every agent and team that uses the store. ```python from agno.agent import Agent @@ -58,7 +58,7 @@ risk_officer.print_response( analyst.learning_machine.learned_knowledge_store.print(query="estimate lag") ``` -The learning is available to every agent and team sharing the store. In Agentic mode, retrieve it with `search_learnings`. The `Knowledge` instance is required. Without it, saves and searches log a warning and do nothing. +The learning is available to every agent and team sharing the store. In Agentic mode, retrieve it with `search_learnings`. A configured `Knowledge` instance backs the store. Missing knowledge configuration causes saves and searches to log a warning; state remains unchanged. ## Per-agent vs institutional @@ -66,17 +66,17 @@ The learning is available to every agent and team sharing the store. In Agentic |--|------------------|------------------------| | Scope | One user across agents sharing the database | Every agent and team that shares the store | | Namespace | Scoped by `user_id` | `"global"` | -| Effect | The user's preferences and facts follow them | The committee remembers | +| Effect | User preferences and facts remain available across sessions | Reviewed insights remain available across research cycles | -For deep research, institutional is the point. The team's judgment should outlive any single review. +Use institutional learning to keep reviewed team judgment available across research cycles. ## What to capture -| Worth a learning | Not worth a learning | -|------------------|----------------------| -| "Analyst estimates lag this sector by a quarter" | A one-off number from a single query | -| "This data source double-counts renewals" | A restatement of the mandate | -| A correction to a conclusion that was wrong | A summary of what was already in the library | +| Save to shared learning | Keep in context or source data | +|-------------------------|--------------------------------| +| "Analyst estimates lag this sector by a quarter" | One-off query results stay with the run | +| "This data source double-counts renewals" | The mandate stays in static context | +| A correction to a conclusion that was wrong | Source summaries stay in the research library | Capture corrections and transferable insights. Leave durable facts to the [research library](/use-cases/deep-research/grounding-research) and rules to the static context. @@ -88,7 +88,7 @@ Capture corrections and transferable insights. Leave durable facts to the [resea | `AGENTIC` | The agent decides what is worth keeping | Research, where signal-to-noise matters | | `PROPOSE` | The model proposes a learning and asks before saving; approval is prompt-based | Low-risk review where soft approval is sufficient | -This is the same machine the [data agent uses to self-correct](/use-cases/data-agents/self-correcting-agents), pointed at a shared store instead of a per-warehouse one. +The [data agent self-correction pattern](/use-cases/data-agents/self-correcting-agents) uses the same machine with a per-warehouse store. This research pattern uses the shared institutional store. ## Next steps diff --git a/use-cases/deep-research/orchestration-patterns.mdx b/use-cases/deep-research/orchestration-patterns.mdx index 367da0b6f..a7beeb3ba 100644 --- a/use-cases/deep-research/orchestration-patterns.mdx +++ b/use-cases/deep-research/orchestration-patterns.mdx @@ -1,11 +1,11 @@ --- title: "Orchestration patterns" -description: "Route, coordinate, broadcast, task, or an explicit pipeline. Pick the shape the research question needs." +description: "Choose a Team mode or Workflow based on ownership, execution order, and review requirements." --- -A research question has a shape. A factual lookup wants one specialist. A high-stakes decision wants every specialist at once. A standardized review wants the same auditable steps every time. Agno gives you a Team mode or a Workflow for each. +Choose the orchestration primitive from the research flow. Route a factual lookup to one specialist, broadcast a high-stakes decision to every specialist, and use a Workflow for a standardized review with an explicit step graph. -## Pick the shape +## Choose an orchestration pattern | Pattern | Primitive | Best for | |---------|-----------|----------| @@ -42,7 +42,7 @@ answer = response.content # response.member_responses holds each consulted member's run. ``` -The instruction asks the lead to consult the Risk Officer, but model instructions do not enforce that invariant. Put mandatory review in a `Workflow` step or an application-side gate. +The lead receives an instruction to consult the Risk Officer. Enforce mandatory review with a `Workflow` step or an application-side gate. ## Broadcast: independent evaluations, one synthesis @@ -65,7 +65,7 @@ broadcast_team = Team( Set `store_member_responses=True` to persist each member's run with the team's run record. -## Pipeline: the same steps, every time +## Pipeline: explicit execution order When a review needs an explicit execution path, a `Workflow` fixes the step graph. Each step's output feeds the next; independent steps run in [parallel](/use-cases/deep-research/parallel-investigation). diff --git a/use-cases/deep-research/overview.mdx b/use-cases/deep-research/overview.mdx index ed30f7a19..9656f5929 100644 --- a/use-cases/deep-research/overview.mdx +++ b/use-cases/deep-research/overview.mdx @@ -4,7 +4,7 @@ sidebarTitle: "Overview" description: "Combine Team modes, Workflow steps, grounding, and typed research outputs." --- -The gap between an agent using tools and a deep research system is orchestration, grounding, and inspectable deliverables. Agno Workflows define an explicit step graph. Run steps in parallel, in loops, or one after the other. +Build deep research systems with explicit orchestration, grounded specialists, and inspectable deliverables. Agno Workflows define the step graph and support sequential, parallel, and looped execution. ```python from agno.workflow import Parallel, Step, Workflow @@ -32,28 +32,28 @@ result = investment_workflow.run("Run a full investment review on NVDA") # result.step_results holds the output from each outer step. ``` -That is a five-step review with a parallel deep-dive. The same shape holds for other research mandates: swap the agents and the prompt. Attach a database to the Workflow to keep each run's input, step outputs, and final result. +This review has five stages, with fundamental and technical analysis running in parallel. Replace the investment agents and prompt to apply the pattern to another research mandate. Attach a database to the Workflow to keep each run's input, step outputs, and final result. -## Learn How To +## Deep research patterns Route, coordinate, broadcast, task, and explicit Workflow pipelines. - Fan specialists out at once, synthesize the results. + Run independent specialists concurrently, then synthesize their results. - Mandate in the prompt, a library in RAG, prior work on disk. + Give each specialist a mandate, a research library, and access to prior work. - Return a typed decision and preserve the supporting memo. + Return a typed decision and preserve its supporting memo. Share reviewed learnings through a common store and namespace. - Put the pipeline behind an API for Slack, cron, and dashboards. + Expose the pipeline through AgentOS for applications, schedules, and dashboards. diff --git a/use-cases/deep-research/parallel-investigation.mdx b/use-cases/deep-research/parallel-investigation.mdx index 0ba820306..c1def76f2 100644 --- a/use-cases/deep-research/parallel-investigation.mdx +++ b/use-cases/deep-research/parallel-investigation.mdx @@ -1,9 +1,9 @@ --- title: "Parallel investigation" -description: "Run independent specialists at the same time, then synthesize, so deep research stays fast." +description: "Run independent specialist steps concurrently, then synthesize their results." --- -Most research work is independent. The fundamental analyst does not need the technical analyst's output to do its job. Run them at the same time. A `Parallel` block in a Workflow does exactly that: every step inside it runs concurrently, and the pipeline waits for all of them before moving on. +Place independent specialist steps in a Workflow `Parallel` block. Each step in the block runs concurrently, and the Workflow waits for the block to finish before continuing. In this review, fundamental and technical analysis both start after market assessment and complete before risk assessment. ```python from agno.workflow import Parallel, Step, Workflow @@ -33,7 +33,7 @@ final = result.content # the last step's output # StepOutput("Risk Assessment") ] ``` -The market assessment runs first because risk and the deep dive depend on it. Fundamental and technical analysis have no dependency on each other, so they run together. Risk waits for both. +Market assessment runs first. Fundamental and technical analysis both use that market context, so they run together. Risk assessment starts after both analyses finish. ## Two ways to fan out @@ -44,20 +44,20 @@ The market assessment runs first because risk and the deep dive depend on it. Fu A Broadcast team is the adaptive version: every member evaluates the same question simultaneously and the lead reconciles them. See [Orchestration patterns](/use-cases/deep-research/orchestration-patterns#broadcast-independent-evaluations-one-synthesis). -## Sequence only what depends +## Model the dependencies -The skill is dependency analysis, not maximum parallelism. Put a step in `Parallel` only when it does not read another step's output. Keep the genuine dependencies sequential. +Use the step graph to express data dependencies. Group steps that share the same prerequisite in `Parallel`. Place downstream steps after the block. | Step | Depends on | Runs | |------|-----------|------| -| Market assessment | Nothing | First, alone | +| Market assessment | Research request | First, alone | | Fundamental analysis | Market context | In parallel with technical | | Technical analysis | Market context | In parallel with fundamental | | Risk assessment | Both analyses | After the parallel block | -## Why this matters for deep research +## Reduce research latency -Deep research is slow because it is thorough. Parallelism keeps thoroughness affordable in wall-clock time: the two analyses above finish in roughly the time of the slower one rather than the sum of both. +Running independent analyses concurrently reduces wall-clock latency while preserving each specialist's full analysis. ## Next steps diff --git a/use-cases/deep-research/serve-and-embed.mdx b/use-cases/deep-research/serve-and-embed.mdx index f18d79ca1..eac52a80d 100644 --- a/use-cases/deep-research/serve-and-embed.mdx +++ b/use-cases/deep-research/serve-and-embed.mdx @@ -1,9 +1,9 @@ --- title: "Serve and embed" -description: "Put the research team and pipeline behind an API so anyone, and any schedule, can ask for a review." +description: "Serve research agents, teams, and workflows through one AgentOS API." --- -A research system that only runs from a script helps the person at the keyboard. Behind an API it answers from Slack, runs as a nightly review, and feeds a dashboard. `AgentOS` serves agents, teams, and workflows on the same contract. +Serve the research workflow with AgentOS to make it available to Slack, scheduled jobs, dashboards, and backend services. Register the individual analysts, research teams, and workflow in one runtime. ```python from agno.os import AgentOS @@ -29,7 +29,7 @@ curl -X POST http://localhost:8000/workflows/investment-workflow/runs \ -F 'stream=false' ``` -## Where a research system lives +## Delivery surfaces | Surface | Shape | |---------|-------| @@ -38,9 +38,9 @@ curl -X POST http://localhost:8000/workflows/investment-workflow/runs \ | Dashboard | A widget triggers a review and renders the structured decision | | Backend gate | A pipeline calls the workflow before a position changes and blocks on a PASS | -The serving model is identical to a [product agent](/use-cases/product-agents/serve-as-an-api) and a [data agent](/use-cases/data-agents/serve-and-embed). The difference is what runs behind the endpoint, not how it is served. +[Product agents](/use-cases/product-agents/serve-as-an-api), [data agents](/use-cases/data-agents/serve-and-embed), and research systems use the same AgentOS run endpoints. Each surface selects the registered component that matches the request. -## Pick the entry point per request +## Choose an entry point | Caller wants | Hit | |--------------|-----| @@ -52,7 +52,7 @@ One AgentOS exposes all three. The surface chooses the shape per request. ## Scheduled research -A scheduled workflow runs the review without anyone asking. Every morning the watchlist is reviewed, the memos are written, and the decisions are waiting. +Use an AgentOS schedule to run a watchlist review at a fixed interval. Each run produces the workflow's memos and decisions for the team. AgentOS ships the scheduler. Start it with `AgentOS(..., scheduler=True)` and register a cron against the workflow's run endpoint with `ScheduleManager`. See [Scheduling](/features/scheduling). diff --git a/use-cases/deep-research/structured-deliverable.mdx b/use-cases/deep-research/structured-deliverable.mdx index 1881da383..9c067ac27 100644 --- a/use-cases/deep-research/structured-deliverable.mdx +++ b/use-cases/deep-research/structured-deliverable.mdx @@ -1,9 +1,9 @@ --- title: "Structured deliverable" -description: "End the pipeline in a typed decision: the call, the conviction, the rationale, and the citations." +description: "Return a typed decision with the call, conviction, allocation, rationale, and citations." --- -Research that ends in prose is hard to act on and harder to audit. The last step of a research pipeline should produce a decision with a fixed shape: the call, the conviction, the reasoning, and what it was based on. Give the final agent an `output_schema` and it returns a validated object. +Make the final pipeline step return a typed decision that downstream code can validate and use. Define the call, conviction, allocation, rationale, and citations in a Pydantic schema, then pass it as the final agent's `output_schema`. ```python from typing import List, Literal @@ -43,11 +43,11 @@ result = chair.run(briefing(market, fundamentals, technicals, risk)).content # citations=['memo:NVDA-2024Q3', 'research:semiconductors']) ``` -Because `output_schema=Decision`, the run returns a validated `Decision`. Downstream code reads `result.call` and `result.allocation_usd` without parsing text. If the model's output fails validation, Agno logs a warning and `content` stays a string, so check the type before acting on it. +Because `output_schema=Decision`, the run returns a validated `Decision`. Downstream code reads `result.call` and `result.allocation_usd` directly. If the model's output fails validation, Agno logs a warning and `content` stays a string, so check the type before acting on it. -The chair takes no tools. Its only job is to weigh the specialists' inputs and commit to a call. +The chair weighs the specialists' inputs and commits to a call. Its configuration omits tools so every conclusion comes from the supplied briefing. -## Two artifacts, two purposes +## Decision and memo A research system usually produces both a machine-actionable decision and a human-readable memo. @@ -58,19 +58,19 @@ A research system usually produces both a machine-actionable decision and a huma The memo is written by a dedicated agent with file tools and a fixed template, then archived. The next review reads it back as [prior work](/use-cases/deep-research/grounding-research). The decision is the row you store and act on. -## Make it auditable +## Required decision fields -| Field | Why it earns its place | -|-------|------------------------| +| Field | Purpose | +|-------|---------| | `conviction` | Lets you threshold: act on high, queue medium for review | -| `rationale` | The reasoning trail, required not optional | +| `rationale` | Records the reasoning trail for review and audit | | `citations` | Carries source identifiers for downstream verification | -A decision without its citations is unverifiable. Require them in the schema and the instructions. +Require citations in the schema and instructions so each decision carries source identifiers for verification. -## Gate the irreversible +## Add approval for consequential actions -When a decision triggers a real action (moving capital, publishing a number), put a human in the loop on that step. Approve the call, then let automation act. See [human approval](/hitl/overview). +When a decision triggers a real action, such as moving capital or publishing a number, add human approval before the action executes. See [human approval](/hitl/overview). ## Next steps From 312cce81e91682ed389a22d17daa175099906a3c Mon Sep 17 00:00:00 2001 From: Ashpreet Date: Sun, 19 Jul 2026 12:02:27 +0100 Subject: [PATCH 11/21] docs: tighten document processing guides --- use-cases/document-processing/contracts.mdx | 4 ++-- .../document-processing/forms-and-intake.mdx | 8 ++++---- .../human-routing-and-eval.mdx | 16 ++++++++-------- .../invoices-and-receipts.mdx | 10 +++++----- use-cases/document-processing/overview.mdx | 8 ++++---- 5 files changed, 23 insertions(+), 23 deletions(-) diff --git a/use-cases/document-processing/contracts.mdx b/use-cases/document-processing/contracts.mdx index 5276e61d8..ac2686ef6 100644 --- a/use-cases/document-processing/contracts.mdx +++ b/use-cases/document-processing/contracts.mdx @@ -3,7 +3,7 @@ title: "Contracts" description: "Parties, dates, and a clause-level breakdown for legal review queues." --- -Contracts are denser than invoices. A header (parties, effective date, term) plus a clause list with stable categories that downstream review tooling can filter on. +Extract parties, effective dates, terms, and clauses into a typed structure for downstream review. Use stable clause categories so review tools can filter the result. ```python from typing import List, Literal, Optional @@ -97,7 +97,7 @@ def route_for_review(contract: Contract) -> dict[str, list[Clause]]: return buckets ``` -The agent does the extraction. The routing is plain Python, against a typed object. The split is auditable because each clause keeps its verbatim `text` and `page`. +`route_for_review` operates on the typed result. Each clause retains its verbatim `text` and `page` for review. ## Diff against a template diff --git a/use-cases/document-processing/forms-and-intake.mdx b/use-cases/document-processing/forms-and-intake.mdx index 59bcd63dc..21ebe38fe 100644 --- a/use-cases/document-processing/forms-and-intake.mdx +++ b/use-cases/document-processing/forms-and-intake.mdx @@ -1,9 +1,9 @@ --- title: "Forms and intake" -description: "Resumes, applications, KYC. Lists inside lists, same File() plumbing." +description: "Extract nested fields from resumes, applications, and KYC documents." --- -Forms and intake documents bring a different shape: a person's identity at the top, then several parallel lists (employment, education, skills, references). The agent fills out the nested structure in one pass. +Forms and intake documents often combine identity fields with repeated sections such as employment, education, skills, and references. A nested Pydantic schema captures this structure in one run. Place the resume to extract at `resume.pdf` in the directory where you run this code. @@ -69,7 +69,7 @@ resume = agent.run( # skills=['Python', 'PostgreSQL', 'Kubernetes', 'Terraform']) ``` -The same shape covers job applications and KYC intake. Swap the schema's outer model and the instructions; the `File()` plumbing and the agent definition do not change. +Adapt the outer model and instructions for job applications and KYC intake. Reuse the `File` input and `Agent` configuration. ## KYC intake @@ -134,7 +134,7 @@ class References(BaseModel): | Resume | Identity, headline | Parallel lists: employment, education, skills | Preserve candidate wording | | KYC | Identity | Few sub-lists; conservative typing | Keep IDs as strings | -The agent code is the same across all four. The schema decides the workload. +Reuse the `Agent` setup across these workloads and change `output_schema` for the document structure. ## Next steps diff --git a/use-cases/document-processing/human-routing-and-eval.mdx b/use-cases/document-processing/human-routing-and-eval.mdx index 1b4a0d1e4..c1f250e12 100644 --- a/use-cases/document-processing/human-routing-and-eval.mdx +++ b/use-cases/document-processing/human-routing-and-eval.mdx @@ -1,9 +1,9 @@ --- title: "Human routing and eval" -description: "Confidence-gated approval and accuracy tracking against a golden set." +description: "Route low-confidence fields for approval and track extraction accuracy against a golden set." --- -Two production concerns the labeling docs leave open: routing low-confidence fields to a human, and tracking accuracy as the system runs over time. Both are short patterns on top of the same extraction agent. +Document processing pipelines need a review path for low-confidence fields and a way to measure extraction quality over time. Add both to the same extraction agent. ## Per-field confidence @@ -55,7 +55,7 @@ invoice = agent.run( ## Route on low confidence -The trigger is plain Python. Walk the fields, find anything below threshold, and decide what to do with it. +Walk the extracted fields, find values below the confidence threshold, and route the document in application code. ```python def low_confidence_fields(invoice: Invoice) -> list[str]: @@ -73,11 +73,11 @@ else: write_to_database(invoice) ``` -The model returns confidence. Your code decides the threshold and the action. +Treat confidence as an agent-provided routing signal. Application code sets the threshold and chooses the action. ## Gate the next action with `requires_confirmation` -For a tighter loop, wrap the downstream action (the database write, the ERP push) in a tool that requires approval. Every call to the tool pauses the run until a human confirms it, so nothing posts to the ERP without sign-off. +Wrap a downstream action, such as a database write or ERP push, in a tool that requires approval. Every call pauses the run until a human confirms it. This places approval at the system boundary. ```python from agno.agent import Agent @@ -124,7 +124,7 @@ The pause is persisted in `db`. A different process can reconstruct the same Age ## Accuracy against a golden set -Confidence routes individual documents. A representative golden set lets you compare extraction behavior across prompt or model changes. +A representative golden set compares extraction behavior across prompt or model changes. ```python from agno.agent import Agent @@ -187,7 +187,7 @@ for doc in golden_set: Passing `db=db` stores each evaluation result. Compare model-judge scores across repeated runs with a fixed judge configuration, and add deterministic field checks for invoice numbers, dates, totals, and line items. See the [evals cookbook](https://github.com/agno-agi/agno/tree/main/cookbook/09_evals/accuracy) for database logging and the team variant. -## Three patterns, one job +## Review controls | Pattern | What it answers | When it fires | |---------|------------------|---------------| @@ -195,7 +195,7 @@ Passing `db=db` stores each evaluation result. Compare model-judge scores across | Approval-gated tools | "Should we let the agent take the next action?" | At a specific tool boundary | | AccuracyEval over a golden set | "How does a model judge compare these outputs?" | After a prompt or model change, or on a schedule | -The first two gate a single document. The third records a model-judge signal for comparing configurations. +Confidence routing and approval-gated tools act on one document. `AccuracyEval` records a model-judge signal for comparing configurations. ## Next steps diff --git a/use-cases/document-processing/invoices-and-receipts.mdx b/use-cases/document-processing/invoices-and-receipts.mdx index 95c6845f9..d7a572024 100644 --- a/use-cases/document-processing/invoices-and-receipts.mdx +++ b/use-cases/document-processing/invoices-and-receipts.mdx @@ -3,7 +3,7 @@ title: "Invoices and receipts" description: "Header fields, line items, and the path from PDF to a database row." --- -The shape AP teams need: a header (vendor, totals, dates) and a list of line items. The schema is the contract with downstream systems. +Accounts payable systems usually need invoice header fields and a list of line items. Define that contract as a Pydantic schema before writing the result downstream. ```python from typing import List, Optional @@ -54,11 +54,11 @@ invoice = agent.run( # quantity=12, unit_price=99.0, amount=1188.0), LineItem(...)]) ``` -The hard part is the missing-field discipline. A hallucinated `total` corrupts the AP ledger. Two lines in the instructions carry that discipline: "Null for missing fields" and "Do not invent line items". Without them, a model asked for a complete object tends to fill the gaps in a noisy scan with plausible values. +Handle missing fields explicitly. The instructions tell the agent to return `null` for absent values and prohibit invented line items. Check the resulting `None` values before writing the invoice to the AP ledger. ## Persist the row -The agent's job ends at a validated `Invoice`. The next step is a normal INSERT. Pydantic `.model_dump()` gives you a dict you can hand to any driver. +A validated `Invoice` is ready for persistence. Pydantic `.model_dump()` gives you a dictionary you can pass to any database driver. ```python from sqlalchemy import create_engine, text @@ -89,11 +89,11 @@ with engine.begin() as conn: ) ``` -One insert for the header and one per line item. The schema decides the table layout; the agent decides the values. +Insert the header once, then insert each line item with the returned invoice ID. The schema maps cleanly to separate header and line tables. ## Receipts -Receipts are invoices with a thinner header: merchant, purchase date, currency, total. Keep the same line-item shape. The same agent and the same instructions work; only `output_schema` changes. +For receipts, use a smaller header with the merchant, purchase date, currency, and total. Keep the same line-item shape and change `output_schema` to `Receipt`. ```python class Receipt(BaseModel): diff --git a/use-cases/document-processing/overview.mdx b/use-cases/document-processing/overview.mdx index e7b4f3ab0..9cc8b99ea 100644 --- a/use-cases/document-processing/overview.mdx +++ b/use-cases/document-processing/overview.mdx @@ -4,9 +4,9 @@ sidebarTitle: "Overview" description: "Turn PDFs and scanned documents into typed rows for your production systems." --- -Every business runs on documents. Invoices land in AP, contracts go to legal, claims hit operations, and resumes route to recruiting. Agno turns each of those into a typed Python object you can persist, route, or hand to the next system. +Document processing agents turn invoices, contracts, forms, and scanned files into typed Python objects. Persist each result, route it for review, or pass it to another system. -Define the schema, pass the PDF, and get a validated object back. +Define a Pydantic schema and pass the document through `File`. The agent returns a validated instance of that schema. ```python from typing import List, Optional @@ -55,7 +55,7 @@ result = agent.run( # currency='USD', lines=[LineItem(...), LineItem(...)]) ``` -`result` is a validated `Invoice`. The next line in your code is an `INSERT`, an ERP call, or a queue message. The model has done its job. +`result` is a validated `Invoice` ready for an `INSERT`, an ERP call, or a queue message. ## Workloads @@ -84,7 +84,7 @@ result = agent.run( Parties, dates, and a clause-level breakdown for review queues. - Resumes, applications, KYC. Lists inside lists, same `File()` plumbing. + Extract nested employment, education, skills, and identity fields. Workflows over a folder, background runs, scheduled jobs with retries. From 276c69ff73d1d14ea68a27aae92e516b24b66752 Mon Sep 17 00:00:00 2001 From: Ashpreet Date: Sun, 19 Jul 2026 12:40:33 +0100 Subject: [PATCH 12/21] docs: remove unused knowledge redirect --- docs.json | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs.json b/docs.json index 78b141509..d39b84093 100644 --- a/docs.json +++ b/docs.json @@ -8974,10 +8974,6 @@ ] }, "redirects": [ - { - "source": "/use-cases/knowledge-assistants", - "destination": "/use-cases/knowledge-agents" - }, { "source": "/examples/agent-os/mcp-demo/enable-mcp-example", "destination": "/examples/agent-os/mcp-demo/mcp-server-example" From 54f9f275e24ddb261a6f88c8d7f386a26b9a5660 Mon Sep 17 00:00:00 2001 From: Ashpreet Date: Sun, 19 Jul 2026 13:04:07 +0100 Subject: [PATCH 13/21] docs: strengthen control plane overview --- features/control-plane.mdx | 153 ++++++++++++++++++++----------------- 1 file changed, 82 insertions(+), 71 deletions(-) diff --git a/features/control-plane.mdx b/features/control-plane.mdx index 19b816e16..ddcc97091 100644 --- a/features/control-plane.mdx +++ b/features/control-plane.mdx @@ -1,91 +1,102 @@ --- title: AgentOS Control Plane -description: "Test, inspect, and manage an AgentOS runtime from a web interface." +sidebarTitle: Agent Control Plane +description: "Test, inspect, and operate AgentOS runtimes from one web interface." --- -The AgentOS Control Plane is the web interface for working with the agents, teams, and workflows served by your AgentOS runtime. +The AgentOS Control Plane gives developers one place to run, inspect, and improve the agents, teams, and workflows served by AgentOS. Connect a local or deployed runtime, test real inputs, follow each run through its session and trace, and manage the knowledge, memory, evaluations, approvals, and schedules behind the system. - + AgentOS Control Plane showing agents, teams, workflows, and connected runtimes -Start a local runtime with a database, tracing, and the scheduler: +## From first run to production -```bash -uv pip install -U "agno[openai,os,sqlite]" -export OPENAI_API_KEY=*** -``` +Test a component, inspect the run, manage the state around it, and repeat against local or deployed runtimes. -```python control_plane.py -from agno.agent import Agent -from agno.db.sqlite import SqliteDb -from agno.models.openai import OpenAIResponses -from agno.os import AgentOS +| 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 | -db = SqliteDb(db_file="tmp/agent.db") +## Follow every run -agent = Agent( - id="assistant", - model=OpenAIResponses(id="gpt-5.5"), - db=db, -) +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. -agent_os = AgentOS( - agents=[agent], - db=db, - tracing=True, - scheduler=True, -) -app = agent_os.get_app() - -if __name__ == "__main__": - agent_os.serve(app="control_plane:app", reload=True) -``` - -Open [os.agno.com](https://os.agno.com), add a local AgentOS, and connect `http://localhost:7777`. - -## What you can do - -| Developer task | Control Plane capability | -|----------------|--------------------------| -| Test components | Chat with registered agents and teams, run workflows, and follow streamed output | -| Debug runs | Browse sessions and inspect model, tool, agent, team, and workflow spans when tracing is enabled | -| Manage context | Search knowledge content and view or update memories exposed by the runtime | -| Build in Studio | Compose and version agents, teams, and workflows from a registered component catalog | -| Review approvals | Inspect and resolve approval records created by approval-enabled tools | -| Operate schedules | Create, enable, disable, trigger, and inspect schedules backed by the AgentOS database | - -Studio uses a `Registry` and an AgentOS `db`. Approvals and schedules also require an AgentOS `db`. Set `scheduler=True` to run enabled cron schedules automatically. - -## How the connection works - -| Layer | Responsibility | -|-------|----------------| -| Browser | Loads the control plane and sends requests to the AgentOS endpoint you connect | -| AgentOS runtime | Runs components, exposes FastAPI endpoints, and applies the authentication and authorization you configure | -| Configured databases | Store the sessions, memories, traces, approvals, schedules, and Studio component versions available through the runtime | - -Runtime records shown in the control plane are read through your AgentOS API. Model providers, tools, telemetry, interfaces, and custom exporters follow their own configuration and data paths. - -For production, serve AgentOS over HTTPS and configure [Security & Auth](/agent-os/security/overview) before connecting the endpoint. - -## Development workflow + + AgentOS trace tree showing model calls, tool calls, delegation, latency, input, and output + -1. Register your agents, teams, and workflows with AgentOS. -2. Start the runtime and connect its endpoint. -3. Run representative inputs from the chat interface. -4. Inspect the session and trace when a result needs attention. -5. Update the component in Python or Studio, then run it again. -6. Connect the deployed runtime and apply its production access controls. +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 + + + + Compose components from your Registry, save drafts, publish versions, and choose the version served by the API. + + + Search knowledge content and review or update the user memories exposed by the connected runtime. + + + Review stored evaluation results and aggregate runtime usage from the configured database. + + + Inspect tool arguments, approve or reject paused executions, and follow resolution history. + + + Create recurring runs, trigger them manually, and inspect their execution history. + + + Explore each view with videos, configuration details, and links to the underlying APIs. + + + +## 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 | + + +Serve production runtimes over HTTPS and configure [Security & Auth](/agent-os/security/overview) before connecting them. + + +## 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 -- [Full Control Plane guide](/agent-os/control-plane) -- [Build and version components in Studio](/agent-os/studio/introduction) -- [Configure AgentOS tracing](/agent-os/tracing/overview) -- [Review and resolve approvals](/agent-os/approvals/overview) -- [Configure Security & Auth](/agent-os/security/overview) +- [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) From fdf777fd7f6bfb87699bf66dda2f70bd2d4fde51 Mon Sep 17 00:00:00 2001 From: Ashpreet Date: Sun, 19 Jul 2026 13:04:28 +0100 Subject: [PATCH 14/21] docs: clarify use case positioning --- agent-os/introduction.mdx | 2 +- use-cases/coding-agents.mdx | 2 +- use-cases/customer-support.mdx | 2 +- use-cases/data-agents/overview.mdx | 2 +- use-cases/data-labeling/overview.mdx | 2 +- use-cases/deep-research/overview.mdx | 2 +- use-cases/document-processing/overview.mdx | 2 +- use-cases/knowledge-agents.mdx | 2 +- use-cases/product-agents/connecting-your-data.mdx | 2 ++ use-cases/product-agents/interfaces.mdx | 2 +- use-cases/product-agents/overview.mdx | 4 ++-- use-cases/product-agents/serve-as-an-api.mdx | 6 +++++- use-cases/workflow-automation.mdx | 2 +- 13 files changed, 19 insertions(+), 13 deletions(-) diff --git a/agent-os/introduction.mdx b/agent-os/introduction.mdx index a8bc38b87..636b6c83c 100644 --- a/agent-os/introduction.mdx +++ b/agent-os/introduction.mdx @@ -34,7 +34,7 @@ app = agent_os.get_app() ## Key Features -- **Production API**: 50+ ready to use endpoints with SSE-compatible streaming. +- **Production API**: 80+ ready-to-use endpoints with SSE-compatible streaming. - **Data Ownership**: Sessions, memory, knowledge, and traces stored in your database. - **Request Isolation**: No state bleed between users, agents, or sessions. - **Security**: JWT-based RBAC with hierarchical scopes. diff --git a/use-cases/coding-agents.mdx b/use-cases/coding-agents.mdx index c325b1322..1edb4a24e 100644 --- a/use-cases/coding-agents.mdx +++ b/use-cases/coding-agents.mdx @@ -4,7 +4,7 @@ sidebarTitle: Coding Agents description: "Build coding agents that inspect repositories, edit files, run commands, and verify changes." --- -A coding agent needs a scoped project, a focused change, and a verification command. +Coding agents handle repository work that starts with reading the project and ends with verified changes. Agno gives engineering teams scoped workspaces, command boundaries, approval gates, background runs, and a production API for these agents. ```python coding_agent.py import tempfile diff --git a/use-cases/customer-support.mdx b/use-cases/customer-support.mdx index c0414ada6..a72b7e37b 100644 --- a/use-cases/customer-support.mdx +++ b/use-cases/customer-support.mdx @@ -4,7 +4,7 @@ sidebarTitle: Customer Support description: "Resolve customer requests with specialist routing, product knowledge, controlled actions, and human escalation." --- -A support system needs persistent conversation history, access to approved information, and clear boundaries for customer-impacting actions. +Support and product teams use agents when resolving a request requires conversation history, approved product knowledge, live customer data, or actions in another system. Agno combines persistent sessions, specialist teams, tools, approval gates, and human escalation in one runtime. ```python support_team.py from agno.agent import Agent diff --git a/use-cases/data-agents/overview.mdx b/use-cases/data-agents/overview.mdx index 4463c7452..fd51ca71f 100644 --- a/use-cases/data-agents/overview.mdx +++ b/use-cases/data-agents/overview.mdx @@ -4,7 +4,7 @@ sidebarTitle: "Overview" description: "Build agents that query operational data, apply business definitions, and return the SQL behind each answer." --- -Data agents answer questions from operational data, apply your business definitions, and return the SQL behind each result. For production, add curated context, captured corrections, and database-enforced access boundaries. +Data and analytics teams use agents to make operational data accessible through plain-language questions and keep business definitions consistent across teams. Agno combines SQL tools, curated context, reusable corrections, and database-enforced access boundaries so each answer can include its query and apply the same definitions. ## Where to start diff --git a/use-cases/data-labeling/overview.mdx b/use-cases/data-labeling/overview.mdx index 132e000ff..b704278e3 100644 --- a/use-cases/data-labeling/overview.mdx +++ b/use-cases/data-labeling/overview.mdx @@ -4,7 +4,7 @@ sidebarTitle: "Overview" description: "Classify data, extract records, build preference datasets, and review labels with agents." --- -Use an `output_schema` to turn text, images, audio, video, and PDFs into validated labels and records. +ML and data teams use agents to turn large collections of unstructured inputs into datasets for training, evaluation, search, and automation. Agno applies the same Pydantic schema pattern across text, images, audio, video, and PDFs, with workflows for parallel labeling, review, and conditional adjudication. ```python from typing import Literal diff --git a/use-cases/deep-research/overview.mdx b/use-cases/deep-research/overview.mdx index 9656f5929..e6f7b9694 100644 --- a/use-cases/deep-research/overview.mdx +++ b/use-cases/deep-research/overview.mdx @@ -4,7 +4,7 @@ sidebarTitle: "Overview" description: "Combine Team modes, Workflow steps, grounding, and typed research outputs." --- -Build deep research systems with explicit orchestration, grounded specialists, and inspectable deliverables. Agno Workflows define the step graph and support sequential, parallel, and looped execution. +Research, strategy, and investment teams use deep research systems when a question requires several independent investigations and a decision-ready deliverable. Agno combines specialist teams, explicit workflows, parallel execution, knowledge, and typed outputs so each stage and final result can be inspected. ```python from agno.workflow import Parallel, Step, Workflow diff --git a/use-cases/document-processing/overview.mdx b/use-cases/document-processing/overview.mdx index 9cc8b99ea..bb48e3f77 100644 --- a/use-cases/document-processing/overview.mdx +++ b/use-cases/document-processing/overview.mdx @@ -4,7 +4,7 @@ sidebarTitle: "Overview" description: "Turn PDFs and scanned documents into typed rows for your production systems." --- -Document processing agents turn invoices, contracts, forms, and scanned files into typed Python objects. Persist each result, route it for review, or pass it to another system. +Operations teams use document processing agents to move information from invoices, contracts, forms, and scans into databases, ERPs, and review queues. Agno returns validated Pydantic objects from files and images. Workflows add approvals, batch execution, retries, and schedules. Define a Pydantic schema and pass the document through `File`. The agent returns a validated instance of that schema. diff --git a/use-cases/knowledge-agents.mdx b/use-cases/knowledge-agents.mdx index dc194f001..9ba05e9c3 100644 --- a/use-cases/knowledge-agents.mdx +++ b/use-cases/knowledge-agents.mdx @@ -3,7 +3,7 @@ title: Knowledge Agents description: "Build agents that answer from indexed content with controlled ingestion, retrieval, filtering, and source updates." --- -A knowledge agent indexes a maintained corpus and retrieves relevant content when needed. +Engineering and operations teams use knowledge agents to answer questions from product documentation, policies, and internal procedures. Agno provides ingestion, retrieval, metadata filtering, corpus isolation, and source updates. AgentOS exposes the knowledge base through its API and Control Plane. ```python knowledge_agent.py from agno.agent import Agent diff --git a/use-cases/product-agents/connecting-your-data.mdx b/use-cases/product-agents/connecting-your-data.mdx index aadca5510..a32b32849 100644 --- a/use-cases/product-agents/connecting-your-data.mdx +++ b/use-cases/product-agents/connecting-your-data.mdx @@ -3,6 +3,8 @@ title: "Connecting your data" description: "Give agents access to external sources using context providers." --- +Product agents that work with live business state need current records and product actions. Context providers connect them to sources such as web search, files, databases, Slack, Google Drive, and MCP servers. + In default mode, context providers expose a source through `query_` and, where enabled, `update_`. The query surface can delegate source-specific work to a sub-agent. Set `mode=ContextMode.tools` when the calling agent should receive the provider's underlying tools directly. ```python diff --git a/use-cases/product-agents/interfaces.mdx b/use-cases/product-agents/interfaces.mdx index f32146758..8872b3131 100644 --- a/use-cases/product-agents/interfaces.mdx +++ b/use-cases/product-agents/interfaces.mdx @@ -3,7 +3,7 @@ title: "Interfaces" description: "Connect agents to Slack, Telegram, WhatsApp, and browser clients through AgentOS." --- -Register an agent with Slack, Telegram, WhatsApp, or a browser interface. +The same agent backend can serve Slack, Telegram, WhatsApp, browser clients, and agent-to-agent systems. AgentOS interface adapters map each surface onto the same run and session model. ```python from agno.agent import Agent diff --git a/use-cases/product-agents/overview.mdx b/use-cases/product-agents/overview.mdx index 5ef43452e..f23868a37 100644 --- a/use-cases/product-agents/overview.mdx +++ b/use-cases/product-agents/overview.mdx @@ -1,10 +1,10 @@ --- title: "Product Copilots & Agents" sidebarTitle: "Overview" -description: "Serve agents across product surfaces with shared database-backed sessions and memory." +description: "Embed agents in your product with REST endpoints, persistent user state, knowledge, and interfaces." --- -Serve the same product agent through chat, inline actions, background jobs, and messaging interfaces. A shared AgentOS database keeps sessions and user memory available across those surfaces. +Product engineering teams embed agents so customers can ask questions, work with their data, and take action inside the application. AgentOS gives these teams 80+ REST endpoints for running agents and managing sessions, memory, knowledge, traces, evaluations, and approvals. The same backend can power chat, inline actions, background jobs, and messaging interfaces while keeping user state in one database. ```python copilot.py from agno.agent import Agent diff --git a/use-cases/product-agents/serve-as-an-api.mdx b/use-cases/product-agents/serve-as-an-api.mdx index 1d34bd8a6..90bba3765 100644 --- a/use-cases/product-agents/serve-as-an-api.mdx +++ b/use-cases/product-agents/serve-as-an-api.mdx @@ -3,7 +3,7 @@ title: "Serve as an API" description: "Turn agents into an HTTP service with streaming, sessions, and auth." --- -`AgentOS` serves registered agents through a FastAPI application. Run routes are component-specific, while database-backed session and memory routes operate across the AgentOS. Your product surfaces call those endpoints. +Product teams can connect web, mobile, and server-side clients to the same AgentOS backend. Registered agents become FastAPI services with streaming run routes, while AgentOS manages sessions, memory, knowledge, traces, evaluations, and approvals through the same API. ```python copilot.py from agno.agent import Agent @@ -126,7 +126,11 @@ async function askCopilot(message, threadId, jwt) { | Runs | Create, stream, cancel, run in background, resume disconnected streams | | Sessions | Create, list, rename, delete, and pull every run in a session. Per-user enforcement requires user isolation. | | Memory | Create, update, delete, search user memories | +| Knowledge | Add, update, search, and delete indexed content | | Traces and metrics | Per-run spans when tracing is enabled, plus token usage and model metrics | +| Evaluations | Run and retrieve agent and team evaluation results | +| Approvals | List and resolve paused approval requests | +| Schedules | Create, update, trigger, enable, disable, and delete recurring runs | Browse the live OpenAPI spec at the `/docs` endpoint of your running AgentOS. diff --git a/use-cases/workflow-automation.mdx b/use-cases/workflow-automation.mdx index 99b923fb9..f8b278f93 100644 --- a/use-cases/workflow-automation.mdx +++ b/use-cases/workflow-automation.mdx @@ -3,7 +3,7 @@ title: Workflow Automation description: "Run repeatable processes with workflows, background execution, human review, and schedules." --- -Use a workflow when each run should follow the same steps, branches, or approval gates. +Engineering and operations teams use workflows to automate processes that need consistent execution and a traceable result. Agno combines model-driven steps with branches, loops, parallel work, approval gates, background execution, schedules, and persisted run history. ```python incident_workflow.py from agno.agent import Agent From 954b6a118bbf87db4938e332150e4c7e991abc6f Mon Sep 17 00:00:00 2001 From: Ashpreet Date: Sun, 19 Jul 2026 13:54:04 +0100 Subject: [PATCH 15/21] docs: strengthen feature positioning --- features/api.mdx | 22 ++++++------ features/evaluation.mdx | 6 ++-- features/interfaces.mdx | 33 ++++++++---------- features/observability.mdx | 6 ++-- features/runtime.mdx | 10 ++---- features/scheduling.mdx | 63 ++++++---------------------------- features/sdk.mdx | 12 +++---- features/security-and-auth.mdx | 12 +++++-- features/storage.mdx | 31 ++++++++++------- 9 files changed, 76 insertions(+), 119 deletions(-) diff --git a/features/api.mdx b/features/api.mdx index 30c8f8d3b..320609957 100644 --- a/features/api.mdx +++ b/features/api.mdx @@ -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`. @@ -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 @@ -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 @@ -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) diff --git a/features/evaluation.mdx b/features/evaluation.mdx index 5cf5f8224..dace778e5 100644 --- a/features/evaluation.mdx +++ b/features/evaluation.mdx @@ -1,9 +1,9 @@ --- title: Agent Evaluation -description: "Measure agent and team quality with accuracy, reliability, performance, and agent-as-judge evals." +description: "Catch regressions in response quality, tool use, latency, and memory." --- -Run eval cases during development and in CI: +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 @@ -44,7 +44,7 @@ uv pip install -U "agno[openai]" uv run python evals.py --json-output tmp/evals.json ``` -The case checks the response against a quality criterion and verifies the expected tool call. The CLI returns a nonzero exit code when a case fails, so the suite can gate CI. +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 diff --git a/features/interfaces.mdx b/features/interfaces.mdx index dbad95f5d..330378929 100644 --- a/features/interfaces.mdx +++ b/features/interfaces.mdx @@ -1,11 +1,11 @@ --- title: Interfaces -description: "Slack, Telegram, WhatsApp, Discord, plus protocol interfaces for agents and browsers." +description: "Connect agents to chat channels, 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 @@ -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( @@ -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 = [] @@ -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() @@ -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 | diff --git a/features/observability.mdx b/features/observability.mdx index dd1d7a961..d64f8045a 100644 --- a/features/observability.mdx +++ b/features/observability.mdx @@ -1,9 +1,9 @@ --- title: Agent Observability -description: "Store OpenTelemetry traces and spans in your configured database." +description: "Trace agent, team, and workflow runs across models, tools, and steps." --- -AgentOS comes with a built-in tracing provider that routes every run to your own database. There's no observability service to sign up for and no tracing API key to manage. +A production agent run can cross models, tools, team members, and workflow steps. Platform teams use traces to explain an unexpected answer, locate a slow call, and follow a failure to its source. AgentOS instruments those runs with OpenTelemetry, stores trace data in your configured database, and renders the same trace tree in the Control Plane. ```python from agno.os import AgentOS @@ -15,7 +15,7 @@ agent_os = AgentOS( ) ``` -`tracing=True` turns on OpenTelemetry instrumentation for agent, team, and workflow runs. Every run produces a trace tree: spans for the LLM call, each tool, team delegation, and workflow step. The database exporter writes the aggregate trace to `agno_traces` and individual spans to `agno_spans`. +`tracing=True` instruments supported agent, team, and workflow operations. Each instrumented run produces spans for model calls, tool executions, team coordination, and workflow steps. AgentOS writes the aggregate trace to `agno_traces` and individual spans to `agno_spans`. ## Where trace data goes diff --git a/features/runtime.mdx b/features/runtime.mdx index 2e28c3699..12f9662c4 100644 --- a/features/runtime.mdx +++ b/features/runtime.mdx @@ -1,15 +1,9 @@ --- title: "Agent Runtime" -description: "Serve agents through a stateless FastAPI runtime with database persistence and optional auth." +description: "Run agents, teams, and workflows through FastAPI with persistence, streaming, authorization, and observability." --- -AgentOS runs agents, teams, and workflows as an API service. A production runtime needs to: - -1. Run components on demand through API requests or interfaces such as Slack and Telegram. -2. Maintain sessions across minutes, days, or weeks. -3. Preserve state across restarts, replicas, and infrastructure failures. -4. Protect application routes from unauthenticated access. -5. Record runs and actions for monitoring. +Platform teams use AgentOS to turn agents into services that handle concurrent requests, preserve state across replicas, and expose production controls from one runtime. AgentOS runs agents, teams, and workflows through FastAPI with streaming, background execution, persistence, auth, tracing, scheduling, and chat or protocol interfaces. AgentOS serves native Agno components and adapters for the Claude Agent SDK, LangGraph, DSPy, and Antigravity. diff --git a/features/scheduling.mdx b/features/scheduling.mdx index 034103f9a..414afaaa1 100644 --- a/features/scheduling.mdx +++ b/features/scheduling.mdx @@ -1,11 +1,9 @@ --- title: Scheduling -description: "Built-in cron for triggering recurring tasks." +description: "Run agents, teams, and workflows on recurring schedules with persisted history and retry controls." --- -AgentOS comes with a built-in cron-style scheduler. Use it to run morning briefings, daily triage, weekly digests, hourly health checks. Agents can also manage their own schedules through tool calls. - -Registered schedules live in the AgentOS database (`agno_schedules` table). The scheduler runs in the same FastAPI process as your agents. No separate worker. +Recurring work such as daily briefs, queue triage, repository syncs, health checks, and reports should use the same runtime as on-demand runs. AgentOS stores schedules and run history in the platform database, invokes existing agent, team, or workflow endpoints, and lets agents manage schedules through `SchedulerTools`. ```python from agno.os import AgentOS @@ -18,7 +16,7 @@ agent_os = AgentOS( ) ``` -The scheduler polls `agno_schedules` every `scheduler_poll_interval` seconds, fires due jobs, retries failures up to each schedule's `max_retries`, and persists state. +The scheduler runs inside the AgentOS process and polls `agno_schedules` every `scheduler_poll_interval` seconds. Keep at least one scheduler-enabled runtime running continuously. Due jobs retry failures up to each schedule's `max_retries`, and every attempt is persisted. The scheduler fires a due job by calling its endpoint over HTTP, against `http://127.0.0.1:7777` by default. That matches the default `serve()` port. Set `scheduler_base_url` to match when you serve on a different host or port; otherwise schedules fire against the wrong URL. @@ -79,59 +77,18 @@ async def lifespan(app): agent_os = AgentOS(agents=[agent], db=db, scheduler=True, lifespan=lifespan) ``` -`if_exists="update"` makes the call idempotent. Re-running on restart updates the existing schedule rather than raising or duplicating. Pass `"skip"` if you want to leave manually-edited schedules alone, or `"raise"` (the default) to surface accidental name collisions. This is the pattern Coda uses for [daily digest and repo sync](/deploy/templates/coda/overview). - -## Workflows for multi-step jobs - -Schedules fire single endpoints. When the work is multi-step (research, then outline, then draft, then review), you reach for a workflow. Workflows are a separate primitive, but they're the most common thing a schedule fires. - -A workflow is a typed pipeline whose steps run in order. Use `Parallel` for concurrent steps, `Loop` for repetition, and `Router` to select one branch. - -```python -from agno.workflow import Loop, Step, Workflow - -workflow = Workflow( - name="content_pipeline", - steps=[ - Step(name="research", agent=researcher), - Step(name="outline", agent=outliner), - Loop( - name="draft_review", - steps=[ - Step(name="draft", agent=writer), - Step(name="review", agent=editor), - ], - end_condition='last_step_content.contains("APPROVED")', - max_iterations=3, - ), - ], -) -``` - -`Loop.end_condition` accepts a CEL expression string (as above) or a callable that takes the iteration's step outputs and returns a bool. `Condition` is a separate primitive for if/else branching inside a workflow. - - -CEL string conditions need the optional `cel-python` dependency: `pip install cel-python` or `pip install 'agno[cel]'`. Without it, the expression logs an error, evaluates to `False`, and the loop runs to `max_iterations`. The callable form has no extra dependency. - - -Registered workflows get a `POST /workflows//runs` endpoint and can be scheduled. Session history is persisted when the workflow has a database. Traces are stored when AgentOS tracing is enabled. +`if_exists="update"` makes restarts idempotent by updating the existing schedule. Pass `"skip"` to preserve manually edited schedules or `"raise"` (the default) to surface accidental name collisions. This is the pattern Coda uses for [daily digest and repo sync](/deploy/templates/coda/overview). -| Pattern | Use when | -|---------|----------| -| **Sequential** | Steps depend on each other | -| **Parallel** | Steps are independent and you want fanout | -| **Loop with condition** | Quality threshold or max iterations | -| **Router + Condition** | Dynamic branching on input | -| **Cross-modal chaining** | Output of one agent is input to a different modality (text → speech, code → narration) | +## Schedule a workflow -For worked examples, see [Demo OS](https://github.com/agno-agi/demo-os). +Schedules invoke endpoints. Point a schedule at `/workflows//runs` when recurring work has multiple steps, branches, or review loops. See [Workflow Automation](/use-cases/workflow-automation) and [Workflows](/workflows/overview). ## Schedule runs and observability When a schedule fires, AgentOS: -1. Looks up the schedule in `agno_schedules` and claims it via a row-level lease. -2. Calls the configured endpoint (`POST /agents//runs` or `POST /workflows//runs`) over HTTP via `httpx.AsyncClient`. This is the same path an external caller would take, including auth headers. +1. Looks up the schedule in `agno_schedules` and claims it through a database-backed lease. +2. Calls the configured endpoint (`POST /agents//runs`, `POST /teams//runs`, or `POST /workflows//runs`) over HTTP via `httpx.AsyncClient`. This is the same path an external caller would take, including auth headers. 3. Records the schedule attempt in `agno_schedule_runs` with status, timings, the underlying `run_id` and `session_id` when returned, and any error. The target component persists its run according to its database configuration. Traces require tracing to be enabled. Schedule runs are queryable from `agno_schedule_runs`. When the target component persists sessions and AgentOS tracing is enabled, the linked run also appears in session and trace views. This Postgres query lists runs fired in the last 24 hours: @@ -152,6 +109,6 @@ The `ai.` prefix is the schema `PostgresDb` creates its tables in by default (ov ## Scheduler in HA -Every replica can run the scheduler loop safely on the backends that implement the scheduler's claim methods (Postgres, SQLite, and MongoDB). Due schedules are claimed via a row-level lease (`locked_by`, `locked_at` on `agno_schedules`). The first replica to claim a due job runs it; the others skip. No leader election needed. +Every replica can run the scheduler loop safely on the backends that implement the scheduler's claim methods: Postgres, SQLite, and MongoDB. Due schedules are claimed through an atomic database-backed lease. The first replica to claim a due job runs it; the others skip. -If you'd rather keep scheduler polling off your hot request path, pin it to a dedicated replica via deployment config. See [Scheduler](/agent-os/scheduler/overview) for tuning details. +Deployment configuration can pin scheduler polling to a dedicated replica. See [Scheduler](/agent-os/scheduler/overview) for tuning details. diff --git a/features/sdk.mdx b/features/sdk.mdx index 946e59a5c..fe47fc8d6 100644 --- a/features/sdk.mdx +++ b/features/sdk.mdx @@ -1,9 +1,9 @@ --- title: Agent SDK -description: "Build your agent platform in pure Python." +description: "Build agents, teams, and workflows in Python with composable models, tools, memory, knowledge, and guardrails." --- -Agno is a Python SDK for building agents and multi-agent systems. It provides three primitives (agents, teams, and workflows) plus capabilities such as storage, memory, knowledge, learning, and compression. A primitive and its capabilities form a component in your agent platform. Everything is pure Python. No new DSL to learn, no YAML to manage. +The Agno SDK gives engineering teams Python primitives for agents, multi-agent teams, and explicit workflows, plus composable models, tools, memory, knowledge, learning, and guardrails. Each configured primitive remains a regular Python object that can run directly or be served through AgentOS. ```bash uv pip install -U "agno[openai,sqlite]" @@ -26,7 +26,7 @@ workbench = Agent( workbench.print_response("Inventory this folder.") ``` -An agent (the primitive) with a model, tools, storage, and session history (the capabilities) is a component you can serve on the AgentOS runtime. +`workbench` is a component: an agent primitive configured with a model, tools, storage, and session history. AgentOS serves the same object as a runtime component. ## Primitives @@ -73,16 +73,14 @@ An agent (the primitive) with a model, tools, storage, and session history (the | Capability | What it adds | |------------|--------------| -| [Background execution](/background-execution/overview) | Long-running runs that don't block your API | +| [Background execution](/background-execution/overview) | Continue long-running work after the initial API request returns | | [Evals](/evals/overview) | Measure accuracy, performance, and reliability; agent-as-judge | | [Observability](/observability/overview) | Tracing with Langfuse, Logfire, Arize, The Context Company, and 12+ providers | | [Scheduler](/scheduler/overview) | Run agents, teams, and workflows on recurring schedules | ## Components -A primitive + capabilities + configuration becomes a live **component** of your agent platform. - -You can create components in code, through a no-code UI, or via the AgentOS API. Change code-defined components in Python. Components created via the API or no-code UI have draft and published configuration versions that you can promote or roll back. The `/components` API lets you build, version, and operate components over HTTP. +Agents, teams, and workflows become runnable **components** once you add their models, tools, state, and configuration. Code-defined components stay in Python. Components created in Studio or through the `/components` API use draft and published versions, with a `current` version that you can promote or roll back. ### Versioned components diff --git a/features/security-and-auth.mdx b/features/security-and-auth.mdx index 61819a605..d3dfed91a 100644 --- a/features/security-and-auth.mdx +++ b/features/security-and-auth.mdx @@ -1,9 +1,17 @@ --- title: Security & Auth -description: "Configure JWT authentication, RBAC scopes, request isolation, and per-user data isolation." +description: "Protect AgentOS APIs with JWT verification, scoped permissions, request isolation, and per-user data boundaries." --- -AgentOS security works in layers: JWT authentication at the edge, scope-based authorization per endpoint, per-request component copies, and opt-in per-user data isolation. Network controls and database permissions cover the rest. +Teams serving agents to employees or customers need identity, permissions, and user data boundaries at the runtime. AgentOS verifies JWTs, enforces scopes per endpoint, creates a fresh component copy for each run, and can scope persistent user data to the JWT subject. Tokens can come from the Control Plane, your backend, or an external identity provider. + +| Boundary | Control | +|----------|---------| +| Caller identity | JWT signature verification; set `verify_audience=True` to enforce the `aud` claim | +| API access | Scopes enforced per endpoint | +| Run state | Fresh component copy for each request | +| Persistent user data | Opt-in reads, writes, and ownership checks scoped to the JWT subject | +| Network and database | Reverse proxy controls and database permissions configured by the deployment | diff --git a/features/storage.mdx b/features/storage.mdx index 0eedb0cfd..01a7c938c 100644 --- a/features/storage.mdx +++ b/features/storage.mdx @@ -1,11 +1,11 @@ --- title: "Agent Storage" -description: "Store sessions, memory, knowledge, and traces in a supported database backend." +description: "Persist agent sessions, memory, knowledge, traces, approvals, schedules, evaluations, and metrics." --- -Agents persist the data they generate and use in a database, set by the `db` param: sessions, memory, knowledge metadata, traces, schedules, approvals, learnings, and usage metrics. +Agent state has to remain available across conversations, restarts, and replicas. Agents, teams, workflows, and AgentOS share a `db` interface for sessions, memory, learnings, knowledge metadata, traces, schedules, approvals, evaluations, and metrics. -The primitives (agents, teams, workflows) and the AgentOS accept a `db` param. Pick from JSON files (local or cloud), embedded (SQLite), relational (Postgres, MySQL), document (MongoDB, Firestore), key-value (Redis, Valkey, DynamoDB), or distributed (SingleStore). +The `db` parameter accepts JSON file, embedded, relational, document, key-value, and distributed backends. ```python from agno.db.postgres import PostgresDb @@ -31,8 +31,7 @@ AgentOS creates the tables and indexes on first boot. Set `auto_provision_dbs=Fa | `agno_schedules`, `agno_schedule_runs` | Cron jobs | | `agno_metrics`, `agno_eval_runs` | Metrics and eval results | -- Backend-specific names may vary. -- Schema changes are generally additive. +Backend-specific table and collection names may vary. ## Pick a backend @@ -40,16 +39,16 @@ Most tutorials use `PostgresDb`. Pair it with `PgVector` when you want relationa | Backend | When to use | |---------|-------------| -| [`PostgresDb`](/database/providers/postgres/overview) | Production. Vector + relational on one box. | +| [`PostgresDb`](/database/providers/postgres/overview) | Production runtime state; pair with `PgVector` for embeddings | | [`SqliteDb`](/database/providers/sqlite/overview) | Local dev, single-user demos, edge deployments | | [`MongoDb`](/database/providers/mongo/overview) | Already on Mongo | | [`MySQLDb`](/database/providers/mysql/overview) | Already on MySQL | -| [`SingleStoreDb`](/database/providers/singlestore/overview) | Vector + analytics on one engine, high-throughput | -| [`RedisDb`](/database/providers/redis/overview) | Cache-friendly, ephemeral sessions | -| [`ValkeyDb`](/database/providers/valkey/overview) | Cache-friendly, ephemeral sessions | +| [`SingleStoreDb`](/database/providers/singlestore/overview) | Existing SingleStore infrastructure and high-throughput runtime state | +| [`RedisDb`](/database/providers/redis/overview) | Existing Redis infrastructure and high-throughput key-value access | +| [`ValkeyDb`](/database/providers/valkey/overview) | Existing Valkey infrastructure and high-throughput key-value access | | [`DynamoDb`](/database/providers/dynamodb/overview) | AWS-native, serverless | | [`FirestoreDb`](/database/providers/firestore/overview) | GCP-native, serverless | -| [`JsonDb`](/database/providers/json/overview) | Local JSON files, no server to run | +| [`JsonDb`](/database/providers/json/overview) | Local JSON file storage | | [`GcsJsonDb`](/database/providers/gcs/overview) | JSON-backed records in Google Cloud Storage | | [`InMemoryDb`](/database/providers/in-memory/overview) | Tests, ephemeral demos | @@ -57,7 +56,7 @@ Postgres-compatible managed services like [Neon](/database/providers/neon/overvi ## Vector storage -Knowledge needs a vector store, and Agno supports 15+ vector databases out of the box. +Knowledge uses a vector store for embedding search. ```python from agno.knowledge import Knowledge @@ -78,7 +77,7 @@ agent = Agent( Other options: LanceDB, Qdrant, Weaviate, Pinecone, Chroma, MongoDB Atlas, Cosmos, Cassandra, ClickHouse, SurrealDB, Milvus. See [Vector Stores](/knowledge/vector-stores/index). -For most production AgentOS deployments, **PgVector + PostgresDb on the same Postgres** is the right default: one database with hybrid search and transactional reads, and no extra service to operate. +For production deployments already using Postgres, pair `PostgresDb` with `PgVector` to keep runtime state and hybrid search in one Postgres service. ## Splitting concerns across databases @@ -103,4 +102,10 @@ Common splits include separate tenant databases, a high-traffic agent on its own ## File and blob storage -For media that doesn't belong in the relational store (generated images, audio, large PDFs), store them in object storage and reference paths in `agno_knowledge` or `agno_sessions`. +Store generated images, audio, and large PDFs in object storage, then reference their paths in `agno_knowledge` or `agno_sessions`. + +## Developer Resources + +- [Database overview](/database/overview) +- [Vector stores](/knowledge/vector-stores/index) +- [Database migrations](/agent-os/usage/database-migrations) From 5fc580e7fb1ac1e3303bc3b6e4097cae38415a5c Mon Sep 17 00:00:00 2001 From: Ashpreet Date: Sun, 19 Jul 2026 13:54:20 +0100 Subject: [PATCH 16/21] docs: improve agent platform journey --- agent-platform/create-agent.mdx | 21 ++++++++++------- agent-platform/evals.mdx | 33 ++++++++++++++++---------- agent-platform/improve-agent.mdx | 26 +++++++++++---------- agent-platform/next-steps.mdx | 21 ++++++++++------- agent-platform/overview.mdx | 30 ++++++++++-------------- agent-platform/run-local.mdx | 35 ++++++++++++++++------------ agent-platform/run-railway.mdx | 40 ++++++++++++++++++++++++-------- docs.json | 2 +- 8 files changed, 123 insertions(+), 85 deletions(-) diff --git a/agent-platform/create-agent.mdx b/agent-platform/create-agent.mdx index 28a050832..37cb8d4d1 100644 --- a/agent-platform/create-agent.mdx +++ b/agent-platform/create-agent.mdx @@ -1,25 +1,28 @@ --- title: Create an Agent -description: "Use Claude Code to create a new agent." +description: "Use a coding-agent skill to add, register, and verify an agent." --- -Next we're going to create a new agent using Claude Code. +The template keeps agent code and eval cases in one repository, while the local runtime exposes logs, traces, and live behavior. A coding agent can use that context to take a short brief through registration and a smoke test. -Because you're running a unified platform (i.e. code, data and logs live in one place), coding agents can manage it end-to-end. The codebase ships five skills that cover the full agent development lifecycle. +Choose how the new component should be managed: -Let's try `/create-new-agent`. +| You want | Use | +|----------|-----| +| Agent source committed to the repository and deployed with AgentOS | `create-new-agent` skill | +| Agent, team, or workflow assembled from registered components at runtime | Agent Builder in the AgentOS UI | ## Run the skill -Open Claude Code (or your favorite coding agent) in your `agent-platform` directory and run: +Open your coding agent in the `agent-platform` directory and ask it to run: ```text -/create-new-agent +Run the create-new-agent skill in .agents/skills. ``` -Claude will ask a few questions and build your agent out. +The coding agent works from a concrete brief directly. For an open-ended goal, it asks for the context needed to choose the pattern and toolkits. -Once the spec is locked in, Claude generates `agents/.py`, registers it in `app/main.py`, adds quick prompts to `app/config.yaml`, restarts the container, and smoke-tests it live. +Once the specification is clear, it generates `agents/.py`, registers the agent in `app/main.py`, adds quick prompts to `app/config.yaml`, restarts the container, and smoke-tests the live endpoint. ## Test your agents on the AgentOS UI @@ -31,7 +34,7 @@ Open [os.agno.com](https://os.agno.com), select your new agent in the sidebar, a ## Do it manually -The `/create-new-agent` skill automated the agent creation process. To do it manually: +The `create-new-agent` skill automates the agent creation process. To do it manually: - Create a file in `agents/.py`. - Register the agent in `app/main.py`. diff --git a/agent-platform/evals.mdx b/agent-platform/evals.mdx index 5ccb23318..832bc3d29 100644 --- a/agent-platform/evals.mdx +++ b/agent-platform/evals.mdx @@ -1,11 +1,9 @@ --- title: Evals -description: "Lock in agent behavior with regression tests." +description: "Turn expected agent behavior into repeatable checks for development, CI, and scheduled runs." --- -Evals are regression tests for your agents. Rerun the same prompts against the same agents and behavior drift becomes visible. - -`/improve-agent` generates probes from an agent's instructions to find new weaknesses. Evals preserve known behavior as repeatable cases. +Probes help you discover weaknesses. Evals turn the behavior you care about into repeatable checks that can run before release, in CI, and on a schedule. ## Cases @@ -46,9 +44,17 @@ Add tags to group your cases into suites. The template uses three tags: `smoke`, ## Run the suite -The suite runs on the host, calls the model, and logs results to your local Postgres through `eval_db`. Start the platform first (`docker compose up -d`) and make sure `.env` has your `OPENAI_API_KEY`. +The suite imports agents on the host and writes results to Postgres through `eval_db`. Start the database, activate the local virtual environment, and set `OPENAI_API_KEY` in `.env`. + + + ```bash + docker compose up -d agentos-db + ``` + + + The eval suite runs on the host and needs a local virtual environment: @@ -68,15 +74,18 @@ The suite runs on the host, calls the model, and logs results to your local Post ```bash - python -m evals --tag smoke # fast suite - python -m evals # full suite + python -m evals --tag smoke # fast checks + python -m evals --tag release # pre-release suite + python -m evals --tag live # checks that depend on live sources + python -m evals # all cases ``` Other options: ```bash - python -m evals -v # stream the agent run with full panels - python -m evals --name # single case while iterating + python -m evals --name # one case while iterating + python -m evals --tag release --json-output out.json + python -m evals -v # stream full run panels ``` @@ -89,10 +98,10 @@ Results write to Postgres via `eval_db`. The eval history shows up on [os.agno.c ## Diagnose failures with your coding agent -Open your coding agent and run: +Open your coding agent and ask it to run: ```text -/eval-and-improve +Run the eval-and-improve skill in .agents/skills. ``` The coding agent runs the suite, triages every failure (bad criteria, real regression, flaky LLM judge), and proposes in-scope fixes. It edits the agent or the case and re-runs until the suite is green. @@ -117,4 +126,4 @@ The template ships a `run_evals` workflow for scheduled checks. Set `ENABLE_SCHE ## Next -[Next steps →](/agent-platform/next-steps) +[Run your platform on Railway →](/agent-platform/run-railway) diff --git a/agent-platform/improve-agent.mdx b/agent-platform/improve-agent.mdx index a08da4129..272dbcdb6 100644 --- a/agent-platform/improve-agent.mdx +++ b/agent-platform/improve-agent.mdx @@ -3,19 +3,21 @@ title: Improve an Agent description: "Run autonomous probe, judge, and edit loops against a live agent." --- +Once an agent works on its main path, test the edges it promises to handle. The template gives coding agents the instructions, runtime logs, and live endpoint they need to probe behavior and make small verified changes. + The template includes two coding-agent skills for changing and testing a live agent: -- `/improve-agent`. Your coding agent derives probes from the agent's instructions, judges responses, and edits until they pass. **Autonomous.** -- `/extend-agent`. You drive this one: add a tool, refine a prompt, or fix a bug. +- `improve-agent`. Your coding agent derives probes from the agent's instructions, judges responses, and edits until they pass. **Autonomous.** +- `extend-agent`. You drive this one: add a tool, refine a prompt, or fix a bug. -`/improve-agent` edits `agents/.py`. `/extend-agent` can also update registration, quick prompts, and dependencies when the requested change requires them. The local container reloads code edits before the next probe. +`improve-agent` edits `agents/.py`. `extend-agent` can also update registration, quick prompts, and dependencies when the requested change requires them. The local container reloads code edits before the next probe. ## Improve: autonomous probe-and-judge -Open your coding agent in the `agent-platform` directory and run: +Open your coding agent in the `agent-platform` directory and ask it to run: ```text -/improve-agent +Run the improve-agent skill in .agents/skills. ``` The coding agent reads the target agent's `INSTRUCTIONS` and typically derives 8-12 probes across four categories: golden path, edge cases, tool selection, and adversarial. For each probe, it calls the live container, reads tool calls from the logs, and judges PASS or FAIL against what the instructions promise. For every failure, it changes one lever: instructions, tools, context provider, model, or `num_history_runs`. It re-runs failed probes and spot-checks previously passing probes for regressions. @@ -25,7 +27,7 @@ The coding agent reads the target agent's `INSTRUCTIONS` and typically derives 8 When you have a specific change in mind, run: ```text -/extend-agent +Run the extend-agent skill in .agents/skills. ``` The coding agent asks what to change. You describe a tool to add, a prompt to refine, or a bug to fix. The agno-docs MCP grounds toolkit and API changes. Each iteration makes and verifies one small change. @@ -34,12 +36,12 @@ The coding agent asks what to change. You describe a tool to add, a prompt to re | Situation | Skill | |-----------|-------| -| Just created an agent and want to harden it before deploying | `/improve-agent` | -| Users report the agent is missing the point | `/improve-agent` | -| You want to add a new tool or knowledge base | `/extend-agent` | -| You hit a specific bug | `/extend-agent` | -| You just extended an agent and want to confirm nothing regressed | `/improve-agent` | +| Just created an agent and want to harden it before deploying | `improve-agent` | +| Users report the agent is missing the point | `improve-agent` | +| You want to add a new tool or knowledge base | `extend-agent` | +| You hit a specific bug | `extend-agent` | +| You just extended an agent and want to confirm nothing regressed | `improve-agent` | ## Next -[Run your platform on Railway →](/agent-platform/run-railway) +[Lock in behavior with evals →](/agent-platform/evals) diff --git a/agent-platform/next-steps.mdx b/agent-platform/next-steps.mdx index 77f033e2e..f72116d4a 100644 --- a/agent-platform/next-steps.mdx +++ b/agent-platform/next-steps.mdx @@ -3,9 +3,7 @@ title: Next Steps description: "Add teams, workflows, scheduled tasks, and interfaces to your agent platform." --- -You now have a deployed agent platform with evals, JWT auth, and a set of coding-agent skills that cover the full lifecycle: create → improve → evaluate → maintain. - -The sections below cover the next level: teams and workflows for multi-step logic, scheduled tasks for proactive runs, and interfaces that put your agents where your users are. +Your platform now runs locally and on Railway with persisted state, authentication, traces, evals, and a coding-agent development loop. Extend it with teams, workflows, schedules, and the interfaces your users already use. ## Going beyond agents @@ -31,7 +29,7 @@ The scheduler is on by default in `app/main.py`, and the template prepares two w | Workflow | What it does when enabled | Toggle | | -------------------- | ------------------------------------------------------- | -------------------------------------------- | | **Deployment check** | Checks daily that the AgentOS is wired correctly. | `ENABLE_DEPLOY_CHECK` (on by default) | -| **Run evals** | Runs the `smoke` profile eval cases daily. | `ENABLE_SCHEDULED_EVALS` (off by default) | +| **Run evals** | Runs the `smoke`-tagged eval cases daily. | `ENABLE_SCHEDULED_EVALS` (off by default) | Schedule your own agents and workflows the same way: @@ -75,18 +73,25 @@ agent_os = AgentOS( | Telegram | [Telegram interface](/agent-os/interfaces/telegram/introduction) | | WhatsApp | [WhatsApp interface](/agent-os/interfaces/whatsapp/introduction) | | Custom UI / AG-UI | [AG-UI interface](/agent-os/interfaces/ag-ui/introduction) | +| MCP clients | [AgentOS MCP interface](/agent-os/mcp/mcp) | | All interfaces | [Interfaces overview](/agent-os/interfaces/overview) | ## Keep the repo coherent -As you ship more agents, configuration drifts, env vars rot, and new agents miss imports. The template ships a fifth skill for the recurring sweep: +As the platform grows, component registration, configuration, environment variables, and documentation can drift. The `review-and-improve` skill checks those contracts and fixes mechanical inconsistencies: ```text -/review-and-improve +Run the review-and-improve skill in .agents/skills. ``` It auto-fixes mechanical drift (stale paths, missing `example.env` entries, agents on disk not registered in `app/main.py`) and surfaces the rest as a punch list. Run it before public releases and periodically during active development. -## You're done +## What you have built -You now have a platform that runs locally and on Railway with JWT auth, persists sessions, memory, and traces in Postgres, supports Postgres-backed knowledge, and includes five coding-agent skills for ongoing development and maintenance. +| Capability | What is in place | +|------------|------------------| +| Runtime | AgentOS running locally and on Railway | +| State | Postgres for sessions, memory, knowledge, traces, and eval history | +| Access | REST, MCP, the AgentOS UI, and optional chat interfaces | +| Security | JWT authorization configured for Railway, with per-user isolation available as an opt-in | +| Development loop | Six coding-agent skills for setup, creation, extension, improvement, evaluation, and maintenance | diff --git a/agent-platform/overview.mdx b/agent-platform/overview.mdx index d52af4717..e236799c3 100644 --- a/agent-platform/overview.mdx +++ b/agent-platform/overview.mdx @@ -1,22 +1,16 @@ --- title: Overview sidebarTitle: Overview -description: "Build your own Agent Platform using Agno's AgentOS runtime." +description: "Build and operate an agent platform with AgentOS, Postgres, and coding-agent skills." --- -Every company building agents builds the same system from scratch: +Engineering teams embedding agents in a product need a shared runtime for runs, sessions, memory, knowledge, authentication, traces, and evals. Building that foundation once gives every agent the same API, state, security, and operating model. -- A server to run the agents (batch, streaming, or background mode). -- A database for storing sessions, runs, traces, and memory. -- Auth and RBAC, validated via JWT or service-account tokens. +AgentOS provides that foundation as a FastAPI application in your cloud. Registered agents, teams, and workflows are available through REST, MCP, and the AgentOS UI. Chat interfaces expose the components you wire to each channel. Postgres stores runtime state, and the Railway starter used in this guide adds six coding-agent skills for setup, creation, extension, improvement, evaluation, and maintenance. -This system is called an agent platform and today I'll show you how to build the foundation once so every new agent slots into the same runtime, storage, and connectors. +## Build with a coding agent -## Built by coding agents - -The best part about building an agent platform is that coding agents can build this entire system for you. Agent code, logs, traces, evals, and the live service live in one place, so a coding agent can set up the platform, then create, improve, and evaluate the agents running on it. It would be surprising if your agent platform wasn't agentic in itself! - -I've curated a set of prompts that you can give your coding agent to do exactly that. Pick your cloud, copy the prompt into Claude Code, Cursor or Codex, and it'll take you from zero to a running platform: +Pick a cloud, then give the setup prompt to Claude Code, Codex, Cursor, or another coding agent. The prompt starts the platform and uses the skills in `.agents/skills` to build the first agent. @@ -59,13 +53,13 @@ I've curated a set of prompts that you can give your coding agent to do exactly ## Build it step by step -It's true that we only learn when we build things ourselves, the old-fashioned way. So the rest of this guide builds the same platform by hand. We'll use the `AgentOS on Railway` template as our starting point, but you can swap it for your cloud provider just as easily. +The rest of this guide uses the Railway starter to show each part separately. The AgentOS development flow stays the same across templates; deployment commands vary by cloud. | Step | What happens | | ---- | ------------ | -| [Run Locally](/agent-platform/run-local) | Run your agent platform (AgentOS + Postgres) locally using Docker. | -| [Create an Agent](/agent-platform/create-agent) | Create a new agent with Claude Code. | -| [Improve an Agent](/agent-platform/improve-agent) | Use Claude Code to read container logs and improve an agent. | -| [Run on Railway](/agent-platform/run-railway) | Deploy the platform to Railway with JWT auth on. | -| [Evals](/agent-platform/evals) | Lock in behavior with regression tests. | -| [Next Steps](/agent-platform/next-steps) | Teams, workflows, scheduling, and Slack interfaces. | +| [Run Locally](/agent-platform/run-local) | Start AgentOS and Postgres with Docker. | +| [Create an Agent](/agent-platform/create-agent) | Use a coding-agent skill to add and verify an agent. | +| [Improve an Agent](/agent-platform/improve-agent) | Probe live behavior and make focused changes. | +| [Evals](/agent-platform/evals) | Turn expected behavior into regression cases. | +| [Run on Railway](/agent-platform/run-railway) | Deploy with JWT authorization enabled. | +| [Next Steps](/agent-platform/next-steps) | Add teams, workflows, schedules, and interfaces. | diff --git a/agent-platform/run-local.mdx b/agent-platform/run-local.mdx index f34560a1d..0af5faab5 100644 --- a/agent-platform/run-local.mdx +++ b/agent-platform/run-local.mdx @@ -1,12 +1,9 @@ --- title: Run Locally -description: "Run AgentOS and Postgres locally with Docker." +description: "Start AgentOS, Postgres, and pgvector locally with Docker." --- -Today we're going to run an agent platform made of: - -- AgentOS on FastAPI -- Postgres + pgvector +Start with the Railway starter, which runs AgentOS and Postgres locally in Docker. This gives you the same API, database, traces, scheduler, MCP interface, and coding-agent workflow you will deploy later. ## Prerequisites @@ -23,13 +20,13 @@ Today we're going to run an agent platform made of: ``` - To make this codebase yours, run `rm -rf .git` and push to your own git repo. + To make the codebase yours, create a new repository, rename this clone's `origin` remote to `upstream`, and add your repository as `origin`. ```bash - cp example.env .env + test -f .env || cp example.env .env ``` Open `.env` and set `OPENAI_API_KEY`. Everything else has sensible defaults. @@ -52,11 +49,19 @@ Today we're going to run an agent platform made of: AgentOS API + + + ```bash + ./scripts/mcp_check.sh + ``` + + This checks the MCP handshake, tool discovery, and one agent run against the local platform. + You now have an agent platform made of AgentOS on FastAPI and Postgres. The AgentOS server exposes 80+ endpoints for runs, sessions, memory, knowledge, and evals. -AgentOS also comes with a UI at [os.agno.com](https://os.agno.com). +Use the AgentOS UI at [os.agno.com](https://os.agno.com) to test and inspect the running platform. ## Connect the AgentOS UI @@ -74,21 +79,21 @@ You should see three agents: Try a prompt against each: -> _"Build an agent that tracks AI news and writes a daily brief"_ → **Agent Builder** walks you through the agent development process. +> _"Plan an agent that tracks AI news daily. Explain the components and steps in plan-only mode."_ → **Agent Builder** returns a component plan without creating one. > _"How healthy is the platform?"_ → **Platform Manager** answers from eval history, deployment checks, and schedules. > _"What did Anthropic publish about agents recently?"_ → **WebSearch** returns a summary with citations. -Open **Sessions** and **Traces** in the sidebar. Every run is captured with full message history, tool calls, and timing. This is what powers the iteration loop on the next page. +Open **Sessions** and **Traces** in the sidebar. The template records these runs with message history, tool calls, and timing. This data powers the iteration loop on the next page. ## Summary -We now have a locally running agent platform with: - -- Our agent runtime (AgentOS) running on port 8000 with request isolation, session management, scheduling, and 80+ endpoints. -- A Postgres database for storing sessions, memory, knowledge, and traces. -- Five coding-agent skills in `.agents/skills/` covering the agent development lifecycle: create, improve, extend, eval, and review. +| Capability | What is running | +|------------|-----------------| +| Runtime | AgentOS on port 8000 with request isolation, session management, scheduling, MCP, and 80+ REST endpoints | +| State | Postgres for sessions, memory, knowledge, traces, schedules, and eval history | +| Development loop | Six skills in `.agents/skills/` for setup, creation, extension, improvement, evaluation, and maintenance | Hot-reload is on. Edits to Python files in the source (`agents/`, `app/`, `db/`, `evals/`, `workflows/`) are live in ~2s. diff --git a/agent-platform/run-railway.mdx b/agent-platform/run-railway.mdx index 7874c0360..a030c4ff2 100644 --- a/agent-platform/run-railway.mdx +++ b/agent-platform/run-railway.mdx @@ -1,13 +1,16 @@ --- title: Run on Railway -description: "Deploy your agent platform to Railway with JWT auth on." +description: "Deploy AgentOS and Postgres to Railway with JWT authorization and MCP access." --- -Your company probably has a set way of running software. Follow that. If you're looking for a place to test this out without going through the full DevOps process, Railway is a good option, and the template includes scripts to: +Deploy after local probes and release evals pass. The Railway starter provisions AgentOS and Postgres, sets the public URL used by schedules and MCP, and requires JWT verification before serving production traffic. + +The template includes scripts to: - Deploy to Railway: `./scripts/railway/up.sh` - Sync environment variables: `./scripts/railway/env-sync.sh` - Redeploy the app: `./scripts/railway/redeploy.sh` +- Tear down the Railway project: `./scripts/railway/down.sh` ## Prerequisites @@ -16,7 +19,7 @@ Your company probably has a set way of running software. Follow that. If you're ## Why JWT is on by default -Token-Based Authorization is **ON** by default. Without a `JWT_VERIFICATION_KEY` (or `JWT_JWKS_FILE`), the app refuses to serve traffic in production. This is why the deploy script stops and asks you for a key. +Token-Based Authorization is **ON** by default. Production startup requires a `JWT_VERIFICATION_KEY` or `JWT_JWKS_FILE`. The deploy script pauses for the verification key before it serves traffic. Token-Based Auth gives you three things: @@ -26,6 +29,8 @@ Token-Based Auth gives you three things: AgentOS leaves its operational and API-documentation routes public: `/`, `/health`, `/info`, `/docs`, `/redoc`, `/openapi.json`, and `/docs/oauth2-redirect`. +Per-user data isolation is opt-in. Set `authorization_config=AuthorizationConfig(user_isolation=True)` to limit non-admin users to their own sessions, memories, traces, and runs. See [User Isolation](/agent-os/security/authorization/user-isolation). + ## Deploy your agent platform to Railway @@ -34,7 +39,7 @@ AgentOS leaves its operational and API-documentation routes public: `/`, `/healt The deploy and sync scripts read `.env.production`. This keeps local and production values separate: different OpenAI keys with different budgets, production-only credentials, a different Slack workspace. ```bash - cp .env .env.production + test -f .env.production || cp .env .env.production ``` Edit `.env.production` with a production OpenAI key. @@ -53,8 +58,9 @@ AgentOS leaves its operational and API-documentation routes public: `/`, `/healt 2. Provisions a Postgres service (with pgvector) and a persistent volume. 3. Creates the `agent-os` service and forwards the database connection vars. 4. Issues your public Railway domain and sets `AGENTOS_URL` to it, on Railway and in `.env.production`. - 5. Pauses and asks for a JWT verification key. - 6. Builds and deploys from the current directory. + 5. Generates `MCP_CONNECT_SECRET` for hosted MCP clients and saves it to `.env.production` and Railway. + 6. Pauses and asks for a JWT verification key. + 7. Builds and deploys from the current directory. The domain takes a few minutes to start resolving after the first deploy. @@ -83,6 +89,18 @@ AgentOS leaves its operational and API-documentation routes public: `/`, `/healt Once you see successful requests, open `https://.up.railway.app/docs` and you're live. + + + + Register the deployed AgentOS with supported local clients: + + ```bash + uvx agno connect --url https://.up.railway.app + ``` + + For ChatGPT or Claude on the web, add `https://.up.railway.app/mcp` as a custom connector. Enter the `MCP_CONNECT_SECRET` stored in `.env.production` on the consent page. + + ## Auto-deploys from GitHub @@ -95,9 +113,9 @@ By default every code update needs `./scripts/railway/redeploy.sh`. To auto-depl Push to `main` now triggers a build and deploy. `./scripts/railway/env-sync.sh` is still how you push env changes. -## Opting out of JWT (not recommended) +## External authentication boundary -If you must run production without auth (inside a private VPC behind another auth layer), set `authorization=False` in `app/main.py` and redeploy. Keep authorization on for any deploy holding real data. Without it, anyone who guesses your Railway domain can read your sessions and run your agents. +Deployments inside a private VPC can set `authorization=False` in `app/main.py` when another trusted layer blocks unauthenticated traffic. Keep AgentOS authorization enabled for internet-accessible deployments and services that hold user data. ## Scaling @@ -112,12 +130,14 @@ The default deploy is one replica with 4 GiB of memory and 2 vCPU. Change `numRe | Run a command with production env vars | `railway run --service agent-os ` | | Push env changes | `./scripts/railway/env-sync.sh` | | Redeploy without git push | `./scripts/railway/redeploy.sh` | -| Tear everything down | Delete the project in the Railway dashboard | +| Tear everything down | `./scripts/railway/down.sh` | Deleting the Railway project removes the app, the database, and all data. +See [Railway Reference](/deploy/templates/railway/reference) for environment variables, scaling, and troubleshooting. + ## Next -[Lock in behavior with evals →](/agent-platform/evals) +[Next steps →](/agent-platform/next-steps) diff --git a/docs.json b/docs.json index d39b84093..c6914715e 100644 --- a/docs.json +++ b/docs.json @@ -95,8 +95,8 @@ "agent-platform/run-local", "agent-platform/create-agent", "agent-platform/improve-agent", - "agent-platform/run-railway", "agent-platform/evals", + "agent-platform/run-railway", "agent-platform/next-steps" ] } From d3fe71fc0a84fb56bb85883a99e72438b89cbcd2 Mon Sep 17 00:00:00 2001 From: Ashpreet Date: Sun, 19 Jul 2026 18:51:22 +0100 Subject: [PATCH 17/21] docs: improve AgentOS onboarding --- agent-os/connect-your-os.mdx | 86 ++++++--- agent-os/control-plane.mdx | 320 ++++++++------------------------- agent-os/introduction.mdx | 99 +++++----- agent-os/overview.mdx | 147 +++++---------- agent-os/run-your-os.mdx | 68 ++++--- agent-os/security/overview.mdx | 120 +++++++------ features/control-plane.mdx | 4 +- 7 files changed, 354 insertions(+), 490 deletions(-) diff --git a/agent-os/connect-your-os.mdx b/agent-os/connect-your-os.mdx index 0a999763a..6afa3391c 100644 --- a/agent-os/connect-your-os.mdx +++ b/agent-os/connect-your-os.mdx @@ -1,12 +1,65 @@ --- title: "Connect Your AgentOS" -description: "Connect your AgentOS to the control plane for monitoring and management." +description: "Connect a local or deployed AgentOS runtime to the Control Plane." --- -## Connect Your AgentOS +Connect a local runtime for development or a deployed runtime to test and operate its agents, teams, and workflows from the [AgentOS Control Plane](https://os.agno.com). -1. Open [os.agno.com](https://os.agno.com) and sign in -2. Click **"Add new OS"** +## Before You Connect + +| Runtime | Requirements | +|---------|--------------| +| Local | AgentOS running on your machine and reachable from your browser, usually at `http://localhost:7777` | +| Live | AgentOS available at a browser-reachable HTTPS URL with [Security & Auth](/agent-os/security/overview) configured for production traffic | + + +Live AgentOS connections require a paid plan. + + +## Connect the Runtime + + + + Open [os.agno.com](https://os.agno.com), sign in, and click **CONNECT OS**. + + + + Choose **Local** or **Live**, then complete the form: + + | Field | Value | + |-------|-------| + | **Environment** | **Local** for a runtime on your machine. **Live** for a browser-reachable HTTPS endpoint. | + | **Endpoint URL** | The AgentOS base URL, such as `http://localhost:7777`. Do not include `/docs` or another route. | + | **Name** | The label shown in the runtime selector, such as `Development`. | + | **Tags** | Optional labels such as `dev`, `stg`, or `prd`. | + + + + Click **CONNECT**. For Control Plane-managed JWT authorization, enable **Token-Based Authorization (JWT)** before connecting. The Control Plane creates a signing key pair and shows the public verification key. + + + + If you enabled **Token-Based Authorization (JWT)**, copy the generated public key into `JWT_VERIFICATION_KEY`, run AgentOS with `authorization=True`, then restart or redeploy the runtime. + + ```bash + export JWT_VERIFICATION_KEY="your-public-key" + ``` + + The Control Plane keeps the matching private signing key and uses it to issue scoped tokens. See the [Authorization quickstart](/agent-os/security/authorization/quickstart) for the complete runtime configuration. + + Keep your existing credential setup when the runtime already uses `OS_SECURITY_KEY` or self-managed JWTs. See [Security & Auth](/agent-os/security/overview) for the available authentication paths. + + + + Select the runtime again after it restarts. + + | Check | Expected | + |-------|----------| + | Connection | A green indicator appears beside the runtime name. | + | Components | Registered agents, teams, and workflows appear on Home. | + | Test run | Select a component in Chat and start a new session. | + + -`modal_app.py` pins `min_containers=1` and `max_containers=1`. The always-warm container keeps the in-process scheduler and MCP streams alive, and the cap stops two schedulers from double-firing every cron. Keep both settings. +`modal_app.py` pins `min_containers=1` and `max_containers=1`. The always-warm container keeps scheduled work and MCP streams available. The template has been validated with this single-container topology. Validate schedule registration and MCP streams before changing the maximum. ## Production auth -Token-Based Authorization is on by default. Production startup requires `JWT_VERIFICATION_KEY` or a readable JWKS file at the container path in `JWT_JWKS_FILE`; otherwise the process exits. +Token-Based Authorization protects AgentOS routes by default in production. Startup requires `JWT_VERIFICATION_KEY` or a readable JWKS file at the container path in `JWT_JWKS_FILE`; otherwise the process exits. Token-Based Auth gives you three things: -1. **No public access.** The server rejects requests without a valid token. +1. **Protected API access.** Requests to protected AgentOS routes require a valid token. `/`, `/health`, `/info`, `/docs`, `/redoc`, `/openapi.json`, and `/docs/oauth2-redirect` remain public. 2. **Per-request identity.** Middleware validates the token and exposes its `user_id`, optional `session_id`, scopes, and claims to the request. 3. **Scope-based permissions.** Token scopes control access to AgentOS routes and resources. The templates do not enable per-user data isolation. To scope non-admin session, memory, trace, and run access to the JWT subject, pass `authorization_config=AuthorizationConfig(user_isolation=True)` to `AgentOS`. See [User Isolation](/agent-os/security/authorization/user-isolation). -To opt out (not recommended), set `authorization=False` in `app/main.py` and redeploy. Use this only inside a private VPC behind another auth layer. Without it, anyone who guesses your modal.run URL can access your AgentOS backend. +To disable JWT authentication, set `authorization=False` in `app/main.py`, remove `JWT_VERIFICATION_KEY` and `JWT_JWKS_FILE` from the production env file, and run `./scripts/modal/env-sync.sh`. `authorization=False` disables AgentOS scope enforcement. Configured JWT environment variables continue to enable JWT validation. MCP OAuth remains active when `MCP_CONNECT_SECRET` is set. Only do this when another layer protects the service. ## Customize @@ -88,10 +88,10 @@ Local containers hot-reload on save. For production, run `./scripts/modal/redepl from agno.models.anthropic import Claude def default_model(): - return Claude(id="claude-sonnet-5") + return Claude(id="claude-sonnet-5-0") ``` -Add `anthropic` to `pyproject.toml`, set the provider key in your env, and regenerate pins: +Add `anthropic` to `pyproject.toml`. Set `ANTHROPIC_API_KEY` in `.env` for local runs and `.env.production` for production, then regenerate pins: ```bash ./scripts/generate_requirements.sh @@ -163,7 +163,7 @@ source .venv/bin/activate | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `OPENAI_API_KEY` | Yes | - | Models and embeddings. | -| `RUNTIME_ENV` | No | `prd` | `dev` disables JWT. Compose sets it for local. Never put it in an env file that syncs to Modal, or production deploys unauthenticated. | +| `RUNTIME_ENV` | No | `prd` | `dev` sets `authorization=False`, which disables AgentOS scope enforcement. Configured JWT environment variables continue to enable JWT validation. Compose sets `dev` locally; keep `prd` on Modal. | | `JWT_VERIFICATION_KEY` | Production | - | Public key from os.agno.com. Quote the value so the multi-line PEM parses as one variable. | | `JWT_JWKS_FILE` | Production | - | Path inside the Modal container to a JWKS file. The scripts put only this path into `agentos-secrets`. Put the file in the Docker build context or add an explicit Modal mount before deploying. | | `MCP_CONNECT_SECRET` | No | generated by `up.sh` | OAuth consent secret (16+ chars) for connecting claude.ai and ChatGPT to `/mcp`. `up.sh` generates one on deploy and writes it to `.env.production`. | @@ -201,7 +201,7 @@ Neon projects are org-scoped, so `neonctl projects create` asks which organizati Expected. Mint the key at [os.agno.com](https://os.agno.com): connect your OS (**Connect OS** → **Live**, enter your modal.run URL), then turn on **Token-Based Authorization (JWT)** under **Settings** → **OS & Security** and paste the full PEM. To add a PEM later, set `JWT_VERIFICATION_KEY` and run `./scripts/modal/env-sync.sh`. To use JWKS, add the file to the Docker build context or configure a Modal mount, set `JWT_JWKS_FILE` to its container path, then deploy. -JWT auth is on whenever `RUNTIME_ENV` is not `dev`. Set `JWT_VERIFICATION_KEY` and sync. For `JWT_JWKS_FILE`, first make the file available inside the Modal image or through a mount, then set its container path and sync. To opt out inside a private VPC behind another auth layer, set `authorization=False` in `app/main.py`. +AgentOS scope enforcement is on whenever `RUNTIME_ENV` is not `dev`. Set `JWT_VERIFICATION_KEY` and sync. For `JWT_JWKS_FILE`, first make the file available inside the Modal image or through a mount, then set its container path and sync. To disable JWT, set `authorization=False` in `app/main.py`, remove both JWT variables from the production env file, and sync. MCP OAuth remains active when `MCP_CONNECT_SECRET` is set. Secrets are read at container start, so rewriting the secret alone changes nothing. `./scripts/modal/env-sync.sh` does both steps: it rewrites `agentos-secrets` and redeploys to roll the container. @@ -210,7 +210,7 @@ Secrets are read at container start, so rewriting the secret alone changes nothi `AGENTOS_URL` is still the localhost default. `up.sh` sets it to your modal.run URL automatically; for a custom domain or tunnel, set it by hand and run `./scripts/modal/env-sync.sh`. -`down.sh` deletes the Neon project but leaves `NEON_PROJECT_ID` and the `DB_*` values in your env file, so `up.sh` thinks a database still exists. Delete those lines and re-run `./scripts/modal/up.sh` to provision a fresh one. +`down.sh` deletes the Neon project and leaves `NEON_PROJECT_ID` and the `DB_*` values in your env file. Delete those lines and re-run `./scripts/modal/up.sh` to provision a fresh one. The script only declares success once the app no longer shows as running in `modal app list` and the project is gone from `neonctl projects list`. Check both, then re-run it or finish by hand: `modal app stop agentos` and `neonctl projects delete `. diff --git a/deploy/templates/railway/deploy.mdx b/deploy/templates/railway/deploy.mdx index 326f26a64..e691e8f18 100644 --- a/deploy/templates/railway/deploy.mdx +++ b/deploy/templates/railway/deploy.mdx @@ -4,16 +4,17 @@ sidebarTitle: "Deploy" description: "Run AgentOS locally using Docker and deploy to production on Railway." --- -The [agentos-railway](https://github.com/agno-agi/agentos-railway) template runs AgentOS locally with Docker and deploys it to Railway. It includes: +Choose Railway when you want Railway to run AgentOS and PostgreSQL without managing a host. The [agentos-railway](https://github.com/agno-agi/agentos-railway) template uses Docker locally and provisions both services on Railway for production. -- **2 platform agents** that build and run the platform for you. **Agent Builder** creates agents, teams, and workflows. **Platform Manager** understands, monitors, and explains the platform. -- **5 [skills](/deploy/templates/improve-agents)** that let coding agents build, test, and improve the platform for you. +- **Agent Builder**, which creates agents, teams, and workflows when prompted. +- **Platform Manager**, which inspects registered agents, eval history, deployment checks, and schedules. +- **Six [skills](/deploy/templates/improve-agents)**. `setup-platform` configures the local platform. Five lifecycle skills create, extend, improve, evaluate, and review it. Coding agents can use the repository skills, live AgentOS API, evals, and container logs to inspect and improve the platform. ## Get started -Copy the prompt below into Claude Code, Cursor, or Codex to clone, configure, and start the platform. +Copy the prompt below into Claude Code, Cursor, or Codex to clone the template, start AgentOS locally, and build your first agent. @@ -120,10 +121,13 @@ For claude.ai and ChatGPT on the web: add `https:///mcp` as a cu ```bash +curl -o /dev/null -w '%{http_code}\n' "https:///health" # 200 +curl -o /dev/null -w '%{http_code}\n' "https:///agents" # 401 + railway logs --service agent-os ``` -Open `https:///docs` to confirm the API is serving. +`/health` and `/docs` remain public. Protected AgentOS routes such as `/agents` require a valid token. diff --git a/deploy/templates/railway/reference.mdx b/deploy/templates/railway/reference.mdx index c8d1335c2..d421791e5 100644 --- a/deploy/templates/railway/reference.mdx +++ b/deploy/templates/railway/reference.mdx @@ -4,6 +4,8 @@ sidebarTitle: "Reference" description: "Commands, customization, environment variables, and troubleshooting for the Railway template." --- +Start with [Deploy AgentOS on Railway](/deploy/templates/railway/deploy) for local setup and the first production deployment. + ## Manage | Task | Command | @@ -26,17 +28,17 @@ Push to `main` triggers a build and rolling deploy. `./scripts/railway/env-sync. ## Production auth -Token-Based Authorization is on by default. Production startup requires `JWT_VERIFICATION_KEY` or a readable JWKS file at the container path in `JWT_JWKS_FILE`; otherwise the process exits. +Token-Based Authorization protects AgentOS routes by default in production. Startup requires `JWT_VERIFICATION_KEY` or a readable JWKS file at the container path in `JWT_JWKS_FILE`; otherwise the process exits. Token-Based Auth gives you three things: -1. **No public access.** The server rejects requests without a valid token. +1. **Protected API access.** Requests to protected AgentOS routes require a valid token. `/`, `/health`, `/info`, `/docs`, `/redoc`, `/openapi.json`, and `/docs/oauth2-redirect` remain public. 2. **Per-request identity.** Middleware validates the token and exposes its `user_id`, optional `session_id`, scopes, and claims to the request. 3. **Scope-based permissions.** Token scopes control access to AgentOS routes and resources. The templates do not enable per-user data isolation. To scope non-admin session, memory, trace, and run access to the JWT subject, pass `authorization_config=AuthorizationConfig(user_isolation=True)` to `AgentOS`. See [User Isolation](/agent-os/security/authorization/user-isolation). -To opt out (not recommended), set `authorization=False` in `app/main.py` and redeploy. Use this only inside a private VPC behind another auth layer. Without it, anyone who guesses your Railway domain can access your platform. +To disable JWT authentication, set `authorization=False` in `app/main.py`, remove `JWT_VERIFICATION_KEY` and `JWT_JWKS_FILE` from the Railway service, and redeploy. `authorization=False` disables AgentOS scope enforcement. Configured JWT environment variables continue to enable JWT validation. MCP OAuth remains active when `MCP_CONNECT_SECRET` is set. Only do this when another layer protects the service. ## Customize @@ -88,10 +90,10 @@ Local containers hot-reload on save. For production, run `./scripts/railway/rede from agno.models.anthropic import Claude def default_model(): - return Claude(id="claude-sonnet-5") + return Claude(id="claude-sonnet-5-0") ``` -Add `anthropic` to `pyproject.toml`, set the provider key in your env, and regenerate pins: +Add `anthropic` to `pyproject.toml`. Set `ANTHROPIC_API_KEY` in `.env` for local runs and `.env.production` for production, then regenerate pins: ```bash ./scripts/generate_requirements.sh @@ -162,7 +164,7 @@ source .venv/bin/activate | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `OPENAI_API_KEY` | Yes | - | Models and embeddings. | -| `RUNTIME_ENV` | No | `prd` | `dev` disables JWT. Compose sets it for local. Never put it in an env file that syncs to Railway, or production deploys unauthenticated. | +| `RUNTIME_ENV` | No | `prd` | `dev` sets `authorization=False`, which disables AgentOS scope enforcement. Configured JWT environment variables continue to enable JWT validation. Compose sets `dev` locally; keep `prd` on Railway. | | `JWT_VERIFICATION_KEY` | Production | - | Public key from os.agno.com. Quote the value so the multi-line PEM parses as one variable. | | `JWT_JWKS_FILE` | Production | - | Path inside the running container to a JWKS JSON file. The scripts set only this path. Add the file to the image build context, rebuild, and redeploy the image, or configure a platform mount and roll the service. | | `MCP_CONNECT_SECRET` | No | generated by `up.sh` | OAuth consent secret (16+ chars) for connecting claude.ai and ChatGPT to `/mcp`. `up.sh` generates one on deploy and writes it to `.env.production`. | @@ -191,7 +193,7 @@ Install the CLI with `brew install railway` or `npm install -g @railway/cli`, th Expected. Mint the key at [os.agno.com](https://os.agno.com): connect your OS (**Connect OS** → **Live**, enter your Railway domain), then turn on **Token-Based Authorization (JWT)** under **Settings** → **OS & Security** and paste the full PEM. To add a PEM later, set `JWT_VERIFICATION_KEY` and run `./scripts/railway/env-sync.sh`. To use JWKS, add the file to the image build context and rebuild, or configure a mount. Set `JWT_JWKS_FILE` to its container path, then redeploy or roll the service. Env sync alone only updates the path. -JWT auth is on whenever `RUNTIME_ENV` is not `dev`. Set `JWT_VERIFICATION_KEY` and sync. For JWKS, verify the file exists inside the container at `JWT_JWKS_FILE`; changing the variable alone does not deliver it. To opt out inside a private VPC behind another auth layer, set `authorization=False` in `app/main.py`. +AgentOS scope enforcement is on whenever `RUNTIME_ENV` is not `dev`. Set `JWT_VERIFICATION_KEY` and sync. For JWKS, verify the file exists inside the container at `JWT_JWKS_FILE`; changing the variable alone does not deliver it. To disable JWT, set `authorization=False` in `app/main.py`, remove both JWT variables from the Railway service, and redeploy. MCP OAuth remains active when `MCP_CONNECT_SECRET` is set. The container is still starting. Wait 1-2 minutes and check `railway logs --service agent-os`. diff --git a/deploy/templates/render/deploy.mdx b/deploy/templates/render/deploy.mdx index a4af94f39..13c150f5b 100644 --- a/deploy/templates/render/deploy.mdx +++ b/deploy/templates/render/deploy.mdx @@ -4,18 +4,19 @@ sidebarTitle: "Deploy" description: "Run AgentOS locally using Docker and deploy to production on Render." --- -AgentOS is a secure, scalable platform for running agents. The [agentos-render](https://github.com/agno-agi/agentos-render) codebase runs AgentOS locally using Docker and deploys to production on Render. It comes with: +Choose Render when your team wants a Blueprint-driven AgentOS deployment with managed PostgreSQL. The [agentos-render](https://github.com/agno-agi/agentos-render) template uses Docker locally and deploys one paid, always-on web service for production. -- **2 platform agents** that build and run the platform for you. **Agent Builder** creates agents, teams, and workflows. **Platform Manager** understands, monitors, and explains the platform. -- **5 [skills](/deploy/templates/improve-agents)** that let coding agents build, test, and improve the platform for you. +- **Agent Builder**, which creates agents, teams, and workflows when prompted. +- **Platform Manager**, which inspects registered agents, eval history, deployment checks, and schedules. +- **Six [skills](/deploy/templates/improve-agents)**. `setup-platform` configures the local platform. Five lifecycle skills create, extend, improve, evaluate, and review it. -Because the trace data, agent code, evals, and system logs all live in one place, the platform can inspect and improve itself automatically. +Coding agents can use the repository skills, live AgentOS API, evals, and container logs to inspect and improve the platform. Deployment is Blueprint-driven: Render provisions everything from `render.yaml` when you connect your repo, and one wiring script finishes the setup. ## Get started -The fastest way to get started is using a coding agent. Copy the prompt below into Claude Code, Cursor or Codex and it'll take you from zero to a running platform. +Copy the prompt below into Claude Code, Cursor, or Codex to clone the template, start AgentOS locally, and build your first agent. @@ -79,7 +80,7 @@ Prints `MCP OK` with the tool count and a real agent answer through the MCP endp ## Deploy to production -**Prerequisites:** A [Render](https://render.com) account with your copy of the repo reachable from Render. A `RENDER_API_KEY` (dashboard → **Account Settings** → **API Keys**) for the scripts. +**Prerequisites:** Python 3 and OpenSSL. A [Render](https://render.com) account with your copy of the repo reachable from Render. A `RENDER_API_KEY` (dashboard → **Account Settings** → **API Keys**) for the scripts. @@ -93,7 +94,7 @@ Edit `.env.production` with production values: a different OpenAI key, productio Open [dashboard.render.com](https://dashboard.render.com) → **New +** → **Blueprint**, connect your copy of the repo, and apply. Render reads `render.yaml`, prompts for `OPENAI_API_KEY`, builds the Dockerfile, and creates the `basic-256mb` Postgres. The first build takes about 10 minutes. -The web service runs on the `starter` plan, the cheapest that never sleeps, which the in-process scheduler and MCP streams require. It runs as a single instance by design; two instances double-fire every cron. +The web service runs on the `starter` plan, the cheapest that never sleeps. This keeps scheduled work and MCP streams available. The template uses one instance and has been validated with that topology. Validate schedule registration and MCP streams before scaling it. @@ -127,7 +128,12 @@ For claude.ai and ChatGPT on the web: add `https:///mcp` as a c -The script prints your service URL. Open `https:///docs` to confirm the API is serving. Logs live in the dashboard: `agent-os` → **Logs**. +```bash +curl -o /dev/null -w '%{http_code}\n' "https:///health" # 200 +curl -o /dev/null -w '%{http_code}\n' "https:///agents" # 401 +``` + +The script prints your service URL. `/health` and `/docs` remain public. Protected AgentOS routes such as `/agents` require a valid token. Logs live in the dashboard: `agent-os` → **Logs**. diff --git a/deploy/templates/render/reference.mdx b/deploy/templates/render/reference.mdx index 15818ac41..700d9892c 100644 --- a/deploy/templates/render/reference.mdx +++ b/deploy/templates/render/reference.mdx @@ -4,7 +4,7 @@ sidebarTitle: "Reference" description: "Commands, customization, environment variables, and troubleshooting for the Render template." --- -The web service is `agent-os` and the database is `agentos-db`. Every command in `scripts/render/` drives the Render API and needs `RENDER_API_KEY` in your environment or env file. +The web service is `agent-os` and the database is `agentos-db`. Every command in `scripts/render/` drives the Render API and needs `RENDER_API_KEY` in your environment or env file. Start with [Deploy AgentOS on Render](/deploy/templates/render/deploy) for prerequisites and the first deployment. ## Manage @@ -36,7 +36,7 @@ Token-Based Auth gives you three things: The templates do not enable per-user data isolation. To scope non-admin session, memory, trace, and run access to the JWT subject, pass `authorization_config=AuthorizationConfig(user_isolation=True)` to `AgentOS`. See [User Isolation](/agent-os/security/authorization/user-isolation). -To disable JWT authentication, set `authorization=False` in `app/main.py`, remove `JWT_VERIFICATION_KEY` and `JWT_JWKS_FILE` from the Render service, and push. Use this only inside a private VPC behind another auth layer. `authorization=False` disables AgentOS scope enforcement, while configured JWT environment variables still enable JWT validation. MCP OAuth remains active when `MCP_CONNECT_SECRET` is set. +To disable JWT authentication, set `authorization=False` in `app/main.py`, remove `JWT_VERIFICATION_KEY` and `JWT_JWKS_FILE` from the Render service, and push. `authorization=False` disables AgentOS scope enforcement. Configured JWT environment variables continue to enable JWT validation. MCP OAuth remains active when `MCP_CONNECT_SECRET` is set. Only do this after placing the public service behind another authentication or network boundary. ## Customize @@ -88,10 +88,10 @@ Local containers hot-reload on save. For production, commit and push; Render reb from agno.models.anthropic import Claude def default_model(): - return Claude(id="claude-sonnet-5") + return Claude(id="claude-sonnet-5-0") ``` -Add `anthropic` to `pyproject.toml`, set the provider key in your env, and regenerate pins: +Add `anthropic` to `pyproject.toml`. Set `ANTHROPIC_API_KEY` in `.env` for local runs and `.env.production` for production, then regenerate pins: ```bash ./scripts/generate_requirements.sh @@ -101,6 +101,8 @@ Rebuild locally with `docker compose up -d --build`. For production, sync the en ```bash ./scripts/render/env-sync.sh +git add app/settings.py pyproject.toml requirements.txt +git commit -m "Use Anthropic model" git push ``` @@ -195,7 +197,7 @@ Create one in the dashboard under **Account Settings** → **API Keys**, then ex Expected. Mint the key at [os.agno.com](https://os.agno.com): connect your OS (**Connect OS** → **Live**, enter your onrender.com URL), then turn on **Token-Based Authorization (JWT)** under **Settings** → **OS & Security** and paste the full PEM. To add a PEM later, set `JWT_VERIFICATION_KEY` and run `./scripts/render/env-sync.sh`. To use JWKS, commit and push the file into the image build context, or configure a mount. Set `JWT_JWKS_FILE` to its container path, then let auto-deploy rebuild or roll the service. Env sync alone only updates the path. -JWT scope enforcement is on whenever `RUNTIME_ENV` is not `dev`. Set `JWT_VERIFICATION_KEY` and sync. For JWKS, verify the file exists inside the container at `JWT_JWKS_FILE`; changing the variable alone does not deliver it. To disable JWT inside a private VPC behind another auth layer, set `authorization=False` in `app/main.py` and remove both JWT environment variables from the Render service. MCP OAuth remains active when `MCP_CONNECT_SECRET` is set. +JWT scope enforcement is on whenever `RUNTIME_ENV` is not `dev`. Set `JWT_VERIFICATION_KEY` and sync. For JWKS, verify the file exists inside the container at `JWT_JWKS_FILE`; changing the variable alone does not deliver it. To disable JWT, set `authorization=False` in `app/main.py`, remove both JWT environment variables from the Render service, and place the public service behind another authentication or network boundary. MCP OAuth remains active when `MCP_CONNECT_SECRET` is set. Render builds the pushed branch, so local uncommitted changes stay on your machine. Commit, push to your deploy branch, and let `autoDeploy` rebuild. `redeploy.sh` warns when it finds uncommitted changes. diff --git a/deploy/templates/scout/overview.mdx b/deploy/templates/scout/overview.mdx index d2e1d9cdb..5928342c7 100644 --- a/deploy/templates/scout/overview.mdx +++ b/deploy/templates/scout/overview.mdx @@ -1,12 +1,35 @@ --- title: "Scout" -sidebarTitle: "Scout" +sidebarTitle: "Scout: Knowledge Agent" description: "Open-source company intelligence agent that navigates web, Slack, Drive, and MCP sources and builds its own wiki and CRM as it learns about your company." --- -**Scout is an open-source company intelligence agent.** It navigates live information sources (web, Slack, Drive, wiki, CRM, MCP servers) to assemble context on demand, and it builds its own wiki and CRM as it learns about your company. The code is public at [agno-agi/scout](https://github.com/agno-agi/scout). +**Scout gives teams an open-source company intelligence agent for finding answers across web, Slack, Drive, wiki, CRM, and MCP sources.** -The default move when working with knowledge sources is to ingest everything into a vector database, chunk, embed, and pray. Coding agents figured out the right approach. They navigate: `ls`, `grep`, open the file, follow the import. Scout does the same thing across Slack, Drive, and the rest. It searches the channel, opens the doc, expands the thread, and assembles context at question time from the live source. +Company knowledge changes across systems with different search APIs and access rules. Scout navigates those live sources at request time: it searches a channel, opens a document, expands a thread, and assembles the relevant context for the answer. + +Agno context providers give each source its own sub-agent and expose a small query or update interface to Scout. Run it locally, then ask a question that requires information from two configured sources. The code is public at [agno-agi/scout](https://github.com/agno-agi/scout). + +## Run locally + +You need [Docker Desktop](https://docs.docker.com/desktop/) installed and running. + +```bash +git clone https://github.com/agno-agi/scout && cd scout + +cp example.env .env +# set OPENAI_API_KEY in .env + +docker compose up -d --build +``` + +Scout is now running at `http://localhost:8000`. The [Scout README](https://github.com/agno-agi/scout#quick-start) has the full walkthrough. + +### Chat with Scout + +1. Open [os.agno.com](https://os.agno.com) and log in. +2. Click **Add OS**, choose **Local**, enter `http://localhost:8000`, then **Connect**. +3. Try the pre-configured prompts. ## How it works @@ -26,7 +49,7 @@ A sub-agent behind each provider owns the source's quirks. Scout sees `query_sla | **MCP** | Registered in `scout/contexts.py` | One `query_mcp_` per server. | - Scout intends Slack access to be read-only, but the pinned template does not pass `write=False` when it creates `SlackContextProvider`. Configuring Slack currently exposes `update_slack`. Leave write scopes ungranted until the template enforces its intended boundary. + Configuring Slack currently exposes both `query_slack` and `update_slack`. The Slack interface needs `chat:write` to reply, so removing write scopes does not provide a practical boundary. Set `write=False` on `SlackContextProvider` in `scout/contexts.py` before connecting a workspace that should remain read-only. Setup for each provider is covered in the Scout README's [Context Providers](https://github.com/agno-agi/scout#context-providers) section. @@ -42,27 +65,6 @@ Most information Scout learns from working with you is perfect for a wiki and a Both start empty and grow with use. Mention that Josh from Anthropic shared a new RLM paper, and Scout adds Josh to the CRM, parses the paper into the wiki, and links them. See [How Scout works](https://github.com/agno-agi/scout#how-scout-works) in the README for how both systems work. -## Run locally - -You need [Docker Desktop](https://docs.docker.com/desktop/) installed and running. - -```bash -git clone https://github.com/agno-agi/scout && cd scout - -cp example.env .env -# set OPENAI_API_KEY in .env - -docker compose up -d --build -``` - -Scout is now running at `http://localhost:8000`. The [Scout README](https://github.com/agno-agi/scout#quick-start) has the full walkthrough. - -### Chat with Scout - -1. Open [os.agno.com](https://os.agno.com) and log in. -2. Click **Add OS**, choose **Local**, enter `http://localhost:8000`, then **Connect**. -3. Try the pre-configured prompts. - ## Deploy to Railway Scout runs on any cloud provider. We provide scripts for Railway. From 495ae0809466b3f01076d36268605925554d2e3c Mon Sep 17 00:00:00 2001 From: Ashpreet Date: Sun, 19 Jul 2026 21:25:16 +0100 Subject: [PATCH 19/21] docs: refine agent platform and starter guidance --- agent-platform/create-agent.mdx | 18 +++++++------- agent-platform/evals.mdx | 29 ++++++++++++---------- agent-platform/improve-agent.mdx | 19 ++++++++++----- agent-platform/next-steps.mdx | 8 +++---- agent-platform/overview.mdx | 10 ++++---- agent-platform/run-local.mdx | 33 +++++++++++++++++++------- agent-platform/run-railway.mdx | 33 ++++++++++++++------------ deploy/templates/aws/reference.mdx | 2 +- deploy/templates/azure/reference.mdx | 2 +- deploy/templates/context/overview.mdx | 2 +- deploy/templates/docker/reference.mdx | 2 +- deploy/templates/fly/reference.mdx | 2 +- deploy/templates/gcp/reference.mdx | 2 +- deploy/templates/helm/reference.mdx | 2 +- deploy/templates/improve-agents.mdx | 6 ++--- deploy/templates/modal/reference.mdx | 2 +- deploy/templates/railway/reference.mdx | 2 +- deploy/templates/render/reference.mdx | 2 +- deploy/templates/scout/overview.mdx | 4 ++-- features/control-plane.mdx | 2 +- features/security-and-auth.mdx | 12 +++++----- 21 files changed, 111 insertions(+), 83 deletions(-) diff --git a/agent-platform/create-agent.mdx b/agent-platform/create-agent.mdx index 37cb8d4d1..17bc9d7f8 100644 --- a/agent-platform/create-agent.mdx +++ b/agent-platform/create-agent.mdx @@ -1,16 +1,16 @@ --- title: Create an Agent -description: "Use a coding-agent skill to add, register, and verify an agent." +description: "Use a coding-agent skill to create and verify an agent." --- -The template keeps agent code and eval cases in one repository, while the local runtime exposes logs, traces, and live behavior. A coding agent can use that context to take a short brief through registration and a smoke test. +The codebase keeps agent code and eval cases in one repository, and the local runtime exposes logs, traces, and live behavior. A coding agent can use this context to create and verify new agents for you. -Choose how the new component should be managed: +There are two ways to create an agent: | You want | Use | |----------|-----| -| Agent source committed to the repository and deployed with AgentOS | `create-new-agent` skill | -| Agent, team, or workflow assembled from registered components at runtime | Agent Builder in the AgentOS UI | +| Agent source stored in the repository | `create-new-agent` skill | +| Agent configuration stored in Postgres | Agent Builder in the AgentOS UI | ## Run the skill @@ -20,13 +20,13 @@ Open your coding agent in the `agent-platform` directory and ask it to run: Run the create-new-agent skill in .agents/skills. ``` -The coding agent works from a concrete brief directly. For an open-ended goal, it asks for the context needed to choose the pattern and toolkits. +Give the coding agent a clear brief and it starts building. For an open-ended goal, it asks for the context it needs to choose the pattern and tools. Once the specification is clear, it generates `agents/.py`, registers the agent in `app/main.py`, adds quick prompts to `app/config.yaml`, restarts the container, and smoke-tests the live endpoint. -## Test your agents on the AgentOS UI +## Test your agent on the AgentOS UI -Open [os.agno.com](https://os.agno.com), select your new agent in the sidebar, and try a few prompts: +Open [os.agno.com](https://os.agno.com), click **Refresh**, choose your new agent from the **Agents** dropdown, and try a few prompts: - **The golden path.** What you built the agent for. - **Edge cases.** Unusual inputs, ambiguous questions, partial information. @@ -38,7 +38,7 @@ The `create-new-agent` skill automates the agent creation process. To do it manu - Create a file in `agents/.py`. - Register the agent in `app/main.py`. -- Add quick-start prompts in `app/config.yaml`. +- Add quick prompts in `app/config.yaml`. The agent file skeleton and the `app/main.py` registration are in [Railway Reference](/deploy/templates/railway/reference), under "Add an agent". diff --git a/agent-platform/evals.mdx b/agent-platform/evals.mdx index 832bc3d29..32ea4e911 100644 --- a/agent-platform/evals.mdx +++ b/agent-platform/evals.mdx @@ -7,7 +7,7 @@ Probes help you discover weaknesses. Evals turn the behavior you care about into ## Cases -Cases live in `evals/cases.py`. Each case sends one input to an agent (`agent=`) and optionally checks two things: +Cases live in `evals/cases.py`. Each case sends one input to an agent (`agent=`) and can run up to two checks: - **judge**: `AgentAsJudgeEval` scores the response against `criteria` (binary pass/fail) using an LLM. - **reliability**: `ReliabilityEval` checks which tools fired against `expected_tool_calls`. @@ -94,7 +94,7 @@ The suite imports agents on the host and writes results to Postgres through `eva Each case prints its response and the verdicts for the checks it defines. The run ends with an `Eval Summary` table. -Results write to Postgres via `eval_db`. The eval history shows up on [os.agno.com](https://os.agno.com) alongside your sessions and traces, so you can see when a case started failing and what changed. +Results are written to Postgres via `eval_db`. The eval history appears on [os.agno.com](https://os.agno.com) alongside your sessions and traces, so you can compare inputs, responses, and verdicts across runs. ## Diagnose failures with your coding agent @@ -104,25 +104,28 @@ Open your coding agent and ask it to run: Run the eval-and-improve skill in .agents/skills. ``` -The coding agent runs the suite, triages every failure (bad criteria, real regression, flaky LLM judge), and proposes in-scope fixes. It edits the agent or the case and re-runs until the suite is green. +The coding agent runs the suite and classifies failures as bad criteria, real regressions, or unreliable LLM judgments. It proposes scoped fixes, updates the agent or case, and re-runs the affected checks. -## When to run evals +## Choose when to run evals -| Trigger | Frequency | -| ------------------------------------- | --------------------- | -| Before deploying a change to an agent | Every time | -| As part of CI | Every PR | -| Against production | On a daily cron | -| After bumping a model version | Every time | +These behavioral checks call models, so choose a cadence that fits the cost and confidence you need. -The template ships a `run_evals` workflow for scheduled checks. Set `ENABLE_SCHEDULED_EVALS=True` to run the `smoke`-tagged cases daily. See [scheduling](/features/scheduling) for the cron API. +| Situation | Suggested run | +| --------- | ------------- | +| While changing one behavior | Run the affected case with `--name `. | +| Before a release | Run the `release` tag when you want broader confidence. | +| In CI | Use stable `smoke` or `release` cases. Leave `live` cases out. | +| After changing a model | Run the cases for affected agents. | +| On a schedule | Run `smoke` cases when recurring model calls are useful. | + +The template ships a `run_evals` workflow for scheduled checks. Scheduled evals are off by default because they make model calls. Set `ENABLE_SCHEDULED_EVALS=True` to run the `smoke`-tagged cases daily. See [scheduling](/features/scheduling) for the cron API. ## What good cases look like - **Specific.** "Returns a JSON object with `ticker` and `price`" beats "Returns the right answer". -- **Stable.** Avoid prompts whose correct answer changes daily. Use phrasing like "describes a real, recent..." instead of locking in a specific result. +- **Stable.** Avoid prompts whose correct answer changes daily. Use phrasing like "describes a real, recent..." so the case remains useful as the answer changes. - **Scoped to one behavior.** One case per behavior makes failures easy to read. -- **Anchored to tools.** `expected_tool_calls` catches the failure mode where the agent confidently makes things up instead of calling a tool. +- **Anchored to tools.** `expected_tool_calls` catches responses that skip a required tool call. ## Next diff --git a/agent-platform/improve-agent.mdx b/agent-platform/improve-agent.mdx index 272dbcdb6..8d8d20bf2 100644 --- a/agent-platform/improve-agent.mdx +++ b/agent-platform/improve-agent.mdx @@ -1,18 +1,18 @@ --- title: Improve an Agent -description: "Run autonomous probe, judge, and edit loops against a live agent." +description: "Probe a live agent, inspect failures, and verify focused changes." --- Once an agent works on its main path, test the edges it promises to handle. The template gives coding agents the instructions, runtime logs, and live endpoint they need to probe behavior and make small verified changes. The template includes two coding-agent skills for changing and testing a live agent: -- `improve-agent`. Your coding agent derives probes from the agent's instructions, judges responses, and edits until they pass. **Autonomous.** -- `extend-agent`. You drive this one: add a tool, refine a prompt, or fix a bug. +- `improve-agent` derives probes from the agent's instructions, judges responses, and makes focused edits. +- `extend-agent` takes a change you specify, such as adding a tool, refining a prompt, or fixing a bug. `improve-agent` edits `agents/.py`. `extend-agent` can also update registration, quick prompts, and dependencies when the requested change requires them. The local container reloads code edits before the next probe. -## Improve: autonomous probe-and-judge +## Improve: probe, judge, and edit Open your coding agent in the `agent-platform` directory and ask it to run: @@ -20,7 +20,14 @@ Open your coding agent in the `agent-platform` directory and ask it to run: Run the improve-agent skill in .agents/skills. ``` -The coding agent reads the target agent's `INSTRUCTIONS` and typically derives 8-12 probes across four categories: golden path, edge cases, tool selection, and adversarial. For each probe, it calls the live container, reads tool calls from the logs, and judges PASS or FAIL against what the instructions promise. For every failure, it changes one lever: instructions, tools, context provider, model, or `num_history_runs`. It re-runs failed probes and spot-checks previously passing probes for regressions. +The skill: + +1. Reads the target agent's `INSTRUCTIONS` and typically derives 8-12 probes across golden path, edge cases, tool selection, and adversarial behavior. +2. Runs each probe against the live container, reads tool calls from the logs, and judges the response against what the instructions promise. +3. Changes one part of the agent for each failure: instructions, tools, context provider, model, or `num_history_runs`. +4. Re-runs failed probes and spot-checks passing probes for regressions. + +If the same probe fails three times or the skill reaches five edit cycles, it stops and reports the blocker. ## Extend: user-driven changes @@ -30,7 +37,7 @@ When you have a specific change in mind, run: Run the extend-agent skill in .agents/skills. ``` -The coding agent asks what to change. You describe a tool to add, a prompt to refine, or a bug to fix. The agno-docs MCP grounds toolkit and API changes. Each iteration makes and verifies one small change. +The coding agent asks what to change. You describe a tool to add, a prompt to refine, or a bug to fix. It checks the current Agno documentation before changing toolkit or API usage. Each iteration makes and verifies one small change. ## When to run each diff --git a/agent-platform/next-steps.mdx b/agent-platform/next-steps.mdx index f72116d4a..a6a4389e3 100644 --- a/agent-platform/next-steps.mdx +++ b/agent-platform/next-steps.mdx @@ -5,7 +5,7 @@ description: "Add teams, workflows, scheduled tasks, and interfaces to your agen Your platform now runs locally and on Railway with persisted state, authentication, traces, evals, and a coding-agent development loop. Extend it with teams, workflows, schedules, and the interfaces your users already use. -## Going beyond agents +## Add teams and workflows | Pattern | Use it when | Reference | | -------------- | ------------------------------------------------------------------------ | ------------------------------------------ | @@ -28,7 +28,7 @@ The scheduler is on by default in `app/main.py`, and the template prepares two w | Workflow | What it does when enabled | Toggle | | -------------------- | ------------------------------------------------------- | -------------------------------------------- | -| **Deployment check** | Checks daily that the AgentOS is wired correctly. | `ENABLE_DEPLOY_CHECK` (on by default) | +| **Deployment check** | Checks daily that AgentOS is wired correctly. | `ENABLE_DEPLOY_CHECK` (on by default) | | **Run evals** | Runs the `smoke`-tagged eval cases daily. | `ENABLE_SCHEDULED_EVALS` (off by default) | Schedule your own agents and workflows the same way: @@ -78,13 +78,13 @@ agent_os = AgentOS( ## Keep the repo coherent -As the platform grows, component registration, configuration, environment variables, and documentation can drift. The `review-and-improve` skill checks those contracts and fixes mechanical inconsistencies: +As the platform grows, the same agent needs to stay aligned across its source file, `app/main.py`, `app/config.yaml`, environment variables, and documentation. The `review-and-improve` skill checks those files together: ```text Run the review-and-improve skill in .agents/skills. ``` -It auto-fixes mechanical drift (stale paths, missing `example.env` entries, agents on disk not registered in `app/main.py`) and surfaces the rest as a punch list. Run it before public releases and periodically during active development. +It fixes straightforward issues such as stale paths, missing `example.env` entries, and agents that exist on disk but are not registered in `app/main.py`. It returns a list of changes that need your judgment. Run it before a public release or after a refactor. ## What you have built diff --git a/agent-platform/overview.mdx b/agent-platform/overview.mdx index e236799c3..7573ca9be 100644 --- a/agent-platform/overview.mdx +++ b/agent-platform/overview.mdx @@ -1,16 +1,16 @@ --- title: Overview sidebarTitle: Overview -description: "Build and operate an agent platform with AgentOS, Postgres, and coding-agent skills." +description: "Build your own Agent Platform using Agno's AgentOS runtime." --- -Engineering teams embedding agents in a product need a shared runtime for runs, sessions, memory, knowledge, authentication, traces, and evals. Building that foundation once gives every agent the same API, state, security, and operating model. +Engineering teams building agents need a shared runtime for runs, sessions, memory, knowledge, authentication, traces, and evals. Building that foundation once gives every agent the same API, state, security, and operating model. -AgentOS provides that foundation as a FastAPI application in your cloud. Registered agents, teams, and workflows are available through REST, MCP, and the AgentOS UI. Chat interfaces expose the components you wire to each channel. Postgres stores runtime state, and the Railway starter used in this guide adds six coding-agent skills for setup, creation, extension, improvement, evaluation, and maintenance. +AgentOS runs that foundation as a FastAPI application in your cloud. Every registered agent, team, and workflow gets a REST API, an MCP interface, and a place in the AgentOS UI. Postgres stores runtime state. The Railway starter used in this guide also includes six coding-agent skills for setup, creation, extension, improvement, evaluation, and maintenance. ## Build with a coding agent -Pick a cloud, then give the setup prompt to Claude Code, Codex, Cursor, or another coding agent. The prompt starts the platform and uses the skills in `.agents/skills` to build the first agent. +Pick a cloud, then give the setup prompt to your favorite coding agent. The prompt starts the platform and uses the skills in `.agents/skills` to build the first agent. @@ -53,7 +53,7 @@ Pick a cloud, then give the setup prompt to Claude Code, Codex, Cursor, or anoth ## Build it step by step -The rest of this guide uses the Railway starter to show each part separately. The AgentOS development flow stays the same across templates; deployment commands vary by cloud. +We learn by building, so the rest of this guide walks through each part of the platform using the [AgentOS on Railway template](/deploy/templates/railway/deploy). The development loop is shared across Agno's deployment templates. When it is time to deploy, follow the guide for your cloud provider. | Step | What happens | | ---- | ------------ | diff --git a/agent-platform/run-local.mdx b/agent-platform/run-local.mdx index 0af5faab5..a55215f38 100644 --- a/agent-platform/run-local.mdx +++ b/agent-platform/run-local.mdx @@ -1,9 +1,12 @@ --- title: Run Locally -description: "Start AgentOS, Postgres, and pgvector locally with Docker." +description: "Run AgentOS and Postgres locally with Docker." --- -Start with the Railway starter, which runs AgentOS and Postgres locally in Docker. This gives you the same API, database, traces, scheduler, MCP interface, and coding-agent workflow you will deploy later. +Today we're going to run an agent platform made of: + +- AgentOS on FastAPI +- Postgres + pgvector ## Prerequisites @@ -20,13 +23,25 @@ Start with the Railway starter, which runs AgentOS and Postgres locally in Docke ``` - To make the codebase yours, create a new repository, rename this clone's `origin` remote to `upstream`, and add your repository as `origin`. + Make the codebase yours by pushing it to a repository you own. To start with a clean Git history, run these commands inside the cloned `agent-platform` directory: + + ```bash + rm -rf .git + git init + git add . + git commit -m "Initial commit" + git branch -M main + git remote add origin https://github.com/your-org/your-repo.git + git push -u origin main + ``` + + `rm -rf .git` removes the template's Git history. Replace the repository URL before running the final two commands. ```bash - test -f .env || cp example.env .env + cp example.env .env ``` Open `.env` and set `OPENAI_API_KEY`. Everything else has sensible defaults. @@ -59,9 +74,7 @@ Start with the Railway starter, which runs AgentOS and Postgres locally in Docke -You now have an agent platform made of AgentOS on FastAPI and Postgres. The AgentOS server exposes 80+ endpoints for runs, sessions, memory, knowledge, and evals. - -Use the AgentOS UI at [os.agno.com](https://os.agno.com) to test and inspect the running platform. +You now have AgentOS on FastAPI with Postgres and pgvector. The API exposes 80+ endpoints for runs, sessions, memory, knowledge, and evals. ## Connect the AgentOS UI @@ -79,13 +92,15 @@ You should see three agents: Try a prompt against each: -> _"Plan an agent that tracks AI news daily. Explain the components and steps in plan-only mode."_ → **Agent Builder** returns a component plan without creating one. +> _"Build an agent that tracks AI news and writes a daily brief"_ → **Agent Builder** creates the agent through AgentOS Studio. > _"How healthy is the platform?"_ → **Platform Manager** answers from eval history, deployment checks, and schedules. > _"What did Anthropic publish about agents recently?"_ → **WebSearch** returns a summary with citations. -Open **Sessions** and **Traces** in the sidebar. The template records these runs with message history, tool calls, and timing. This data powers the iteration loop on the next page. +After Agent Builder finishes, click **Refresh**, choose the new agent from the **Agents** dropdown, and try it. + +Open **Sessions** and **Traces** in the sidebar. They capture message history, tool calls, and timing so you can inspect behavior and improve your agents. ## Summary diff --git a/agent-platform/run-railway.mdx b/agent-platform/run-railway.mdx index a030c4ff2..53d07a4bc 100644 --- a/agent-platform/run-railway.mdx +++ b/agent-platform/run-railway.mdx @@ -3,9 +3,7 @@ title: Run on Railway description: "Deploy AgentOS and Postgres to Railway with JWT authorization and MCP access." --- -Deploy after local probes and release evals pass. The Railway starter provisions AgentOS and Postgres, sets the public URL used by schedules and MCP, and requires JWT verification before serving production traffic. - -The template includes scripts to: +Your company probably has a standard way to run software. Use it. If you want to deploy this platform without building the cloud infrastructure first, Railway is the quickest path through this guide. The template includes scripts to: - Deploy to Railway: `./scripts/railway/up.sh` - Sync environment variables: `./scripts/railway/env-sync.sh` @@ -19,9 +17,9 @@ The template includes scripts to: ## Why JWT is on by default -Token-Based Authorization is **ON** by default. Production startup requires a `JWT_VERIFICATION_KEY` or `JWT_JWKS_FILE`. The deploy script pauses for the verification key before it serves traffic. +JWT authorization is enabled by default. Production startup requires a `JWT_VERIFICATION_KEY` or `JWT_JWKS_FILE`. During an interactive deploy, the script pauses for a verification key when neither value is configured. -Token-Based Auth gives you three things: +JWT authorization provides: - **Protected application routes.** Requests to agent, team, workflow, and data routes require a valid token. - **Per-request identity.** Middleware parses the token and exposes `user_id`, `session_id`, and custom claims to protected routes. @@ -36,13 +34,15 @@ Per-user data isolation is opt-in. Set `authorization_config=AuthorizationConfig - The deploy and sync scripts read `.env.production`. This keeps local and production values separate: different OpenAI keys with different budgets, production-only credentials, a different Slack workspace. + The deploy and sync scripts read `.env.production`. This keeps local and production values separate: different OpenAI keys with different budgets, production-only credentials, or a different Slack workspace. + + Create the file the first time you deploy: ```bash - test -f .env.production || cp .env .env.production + cp .env .env.production ``` - Edit `.env.production` with a production OpenAI key. + Skip this command if `.env.production` already exists. Edit the file with a production OpenAI key. @@ -59,7 +59,7 @@ Per-user data isolation is opt-in. Set `authorization_config=AuthorizationConfig 3. Creates the `agent-os` service and forwards the database connection vars. 4. Issues your public Railway domain and sets `AGENTOS_URL` to it, on Railway and in `.env.production`. 5. Generates `MCP_CONNECT_SECRET` for hosted MCP clients and saves it to `.env.production` and Railway. - 6. Pauses and asks for a JWT verification key. + 6. Asks for a JWT verification key when neither JWT setting is configured. 7. Builds and deploys from the current directory. The domain takes a few minutes to start resolving after the first deploy. @@ -83,10 +83,11 @@ Per-user data isolation is opt-in. Set `authorization_config=AuthorizationConfig ```bash - railway logs --service agent-os + curl --fail https://.up.railway.app/health + curl --silent --output /dev/null --write-out "%{http_code}\n" https://.up.railway.app/agents ``` - Once you see successful requests, open `https://.up.railway.app/docs` and you're live. + The health check should succeed, and the protected `/agents` route should return `401` without a token. Open `https://.up.railway.app/docs` to inspect the deployed API. Use `railway logs --service agent-os` if either check fails. @@ -105,7 +106,7 @@ Per-user data isolation is opt-in. Set `authorization_config=AuthorizationConfig ## Auto-deploys from GitHub -By default every code update needs `./scripts/railway/redeploy.sh`. To auto-deploy on every push to `main`: +Until GitHub auto-deploy is connected, redeploy code changes with `./scripts/railway/redeploy.sh`. To deploy on every push to `main`: 1. Open the Railway dashboard → your project → the `agent-os` service → **Settings**. 2. Under **Source**, click **Connect Repo** and pick your repo. @@ -115,11 +116,13 @@ Push to `main` now triggers a build and deploy. `./scripts/railway/env-sync.sh` ## External authentication boundary -Deployments inside a private VPC can set `authorization=False` in `app/main.py` when another trusted layer blocks unauthenticated traffic. Keep AgentOS authorization enabled for internet-accessible deployments and services that hold user data. +If a private network or trusted gateway already blocks unauthenticated traffic, set `authorization=False` in `app/main.py`. JWT middleware still validates tokens while `JWT_VERIFICATION_KEY` or `JWT_JWKS_FILE` remains configured. Remove those values from `.env.production` and the Railway `agent-os` service, then redeploy. `MCP_CONNECT_SECRET` controls the separate OAuth flow for MCP clients. Remove it from both places too if the gateway should protect `/mcp`. Keep AgentOS authorization enabled for internet-accessible deployments and services that hold user data. + +`./scripts/railway/env-sync.sh` updates variables present in `.env.production`; it does not remove variables you deleted from the file. ## Scaling -The default deploy is one replica with 4 GiB of memory and 2 vCPU. Change `numReplicas` and `limits` in `railway.json` as your load and availability requirements grow. +The starter is configured for one replica with 4 GiB of memory and 2 vCPU. Adjust the resource limits in `railway.json` as load grows. Validate schedules and long-lived MCP connections with your workload before increasing `numReplicas`. ## Operations @@ -136,7 +139,7 @@ The default deploy is one replica with 4 GiB of memory and 2 vCPU. Change `numRe Deleting the Railway project removes the app, the database, and all data. -See [Railway Reference](/deploy/templates/railway/reference) for environment variables, scaling, and troubleshooting. +See [Railway Reference](/deploy/templates/railway/reference) for environment variables, customization, and troubleshooting. ## Next diff --git a/deploy/templates/aws/reference.mdx b/deploy/templates/aws/reference.mdx index f4fa6ba15..871fb8949 100644 --- a/deploy/templates/aws/reference.mdx +++ b/deploy/templates/aws/reference.mdx @@ -82,7 +82,7 @@ Complete the first AWS deployment with the default OpenAI model. The current `up from agno.models.anthropic import Claude def default_model(): - return Claude(id="claude-sonnet-5-0") + return Claude(id="claude-sonnet-5") ``` Add `anthropic` to `pyproject.toml`. Set `ANTHROPIC_API_KEY` in `.env` for local runs and `.env.production` for production, then regenerate pins: diff --git a/deploy/templates/azure/reference.mdx b/deploy/templates/azure/reference.mdx index 5d22a505b..9abda4741 100644 --- a/deploy/templates/azure/reference.mdx +++ b/deploy/templates/azure/reference.mdx @@ -85,7 +85,7 @@ Local containers hot-reload on save. For production, run `./scripts/azure/redepl from agno.models.anthropic import Claude def default_model(): - return Claude(id="claude-sonnet-5-0") + return Claude(id="claude-sonnet-5") ``` Add `anthropic` to `pyproject.toml`. Set `ANTHROPIC_API_KEY` in `.env` for local runs and `.env.production` for production, then regenerate pins: diff --git a/deploy/templates/context/overview.mdx b/deploy/templates/context/overview.mdx index d99937aea..a39d38606 100644 --- a/deploy/templates/context/overview.mdx +++ b/deploy/templates/context/overview.mdx @@ -115,7 +115,7 @@ The script creates your public domain, then pauses and waits while you mint the Token-Based Authorization is on by default. Without a `JWT_VERIFICATION_KEY` in `.env.production`, the AgentOS will not serve traffic. That is the safe default for an agent that holds your work context. You can also [issue and verify your own JWT](/agent-os/security/authorization/self-hosted). -1. Open [os.agno.com](https://os.agno.com), click **Connect AgentOS** → **Live**, and paste the domain the script printed. +1. Open [os.agno.com](https://os.agno.com), click **Connect OS** → **Live**, and paste the domain the script printed. 2. Turn on **Token-Based Authorization** and click **Connect**. 3. Copy the public key into `.env.production` as `JWT_VERIFICATION_KEY`. 4. Back in the terminal, press Enter. The script reads the key and deploys the service. diff --git a/deploy/templates/docker/reference.mdx b/deploy/templates/docker/reference.mdx index c7f4b3d65..2cd2bcfaa 100644 --- a/deploy/templates/docker/reference.mdx +++ b/deploy/templates/docker/reference.mdx @@ -80,7 +80,7 @@ Local containers hot-reload on save. For production, rebuild with `docker compos from agno.models.anthropic import Claude def default_model(): - return Claude(id="claude-sonnet-5-0") + return Claude(id="claude-sonnet-5") ``` Add `anthropic` to `pyproject.toml`, set `ANTHROPIC_API_KEY` in `.env`, and regenerate pins: diff --git a/deploy/templates/fly/reference.mdx b/deploy/templates/fly/reference.mdx index eb61a3bfa..15c58e3fd 100644 --- a/deploy/templates/fly/reference.mdx +++ b/deploy/templates/fly/reference.mdx @@ -82,7 +82,7 @@ Local containers hot-reload on save. For production, run `./scripts/fly/redeploy from agno.models.anthropic import Claude def default_model(): - return Claude(id="claude-sonnet-5-0") + return Claude(id="claude-sonnet-5") ``` Add `anthropic` to `pyproject.toml`. Set `ANTHROPIC_API_KEY` in `.env` for local runs and `.env.production` for production, then regenerate pins: diff --git a/deploy/templates/gcp/reference.mdx b/deploy/templates/gcp/reference.mdx index b40d2f419..7672b33f2 100644 --- a/deploy/templates/gcp/reference.mdx +++ b/deploy/templates/gcp/reference.mdx @@ -82,7 +82,7 @@ Local containers hot-reload on save. For production, run `./scripts/gcp/redeploy from agno.models.anthropic import Claude def default_model(): - return Claude(id="claude-sonnet-5-0") + return Claude(id="claude-sonnet-5") ``` Add `anthropic` to `pyproject.toml`. Set `ANTHROPIC_API_KEY` in `.env` for local runs and `.env.production` for production, then regenerate pins: diff --git a/deploy/templates/helm/reference.mdx b/deploy/templates/helm/reference.mdx index 5babe07ca..a2e7003fb 100644 --- a/deploy/templates/helm/reference.mdx +++ b/deploy/templates/helm/reference.mdx @@ -82,7 +82,7 @@ Local containers hot-reload on save. For production, build and push a new image from agno.models.anthropic import Claude def default_model(): - return Claude(id="claude-sonnet-5-0") + return Claude(id="claude-sonnet-5") ``` Add `anthropic` to `pyproject.toml`, set `ANTHROPIC_API_KEY` in `.env` for local runs, and regenerate pins: diff --git a/deploy/templates/improve-agents.mdx b/deploy/templates/improve-agents.mdx index 5d8ccd071..e14611aec 100644 --- a/deploy/templates/improve-agents.mdx +++ b/deploy/templates/improve-agents.mdx @@ -23,9 +23,9 @@ The skills live in `.agents/skills/`. Claude Code discovers them through the com | `/setup-platform` | Configures a fresh clone, starts AgentOS locally, verifies MCP, and builds the first agent. | Starting with a new Starter | | `/create-new-agent` | Scaffolds an agent, registers it in `app/main.py`, and smoke-tests it live. | Adding a new agent | | `/extend-agent` | Adds a tool or capability, refines instructions, or fixes a known bug. | The required change is already clear | -| `/improve-agent` | Derives probes from the agent's `INSTRUCTIONS`, judges responses, and edits until they pass. | Improving behavior through simulations and probes | -| `/eval-and-improve` | Runs the eval suite, diagnoses failures, and fixes in scope until green. | Resolving an eval regression | -| `/review-and-improve` | Checks for drift between documentation, code, and configuration and fixes mechanical drift. | Maintaining the project after changes | +| `/improve-agent` | Derives probes from the agent's `INSTRUCTIONS`, judges responses, makes focused edits, and reruns affected probes. | Improving behavior through simulations and probes | +| `/eval-and-improve` | Runs the eval suite, classifies failures, proposes scoped fixes, and reruns affected cases. | Resolving an eval regression | +| `/review-and-improve` | Checks documentation, code, and configuration together and fixes straightforward inconsistencies. | Maintaining the project after changes | ## Connect the live platform diff --git a/deploy/templates/modal/reference.mdx b/deploy/templates/modal/reference.mdx index 02613cca4..8a0326a58 100644 --- a/deploy/templates/modal/reference.mdx +++ b/deploy/templates/modal/reference.mdx @@ -88,7 +88,7 @@ Local containers hot-reload on save. For production, run `./scripts/modal/redepl from agno.models.anthropic import Claude def default_model(): - return Claude(id="claude-sonnet-5-0") + return Claude(id="claude-sonnet-5") ``` Add `anthropic` to `pyproject.toml`. Set `ANTHROPIC_API_KEY` in `.env` for local runs and `.env.production` for production, then regenerate pins: diff --git a/deploy/templates/railway/reference.mdx b/deploy/templates/railway/reference.mdx index d421791e5..0ca26361f 100644 --- a/deploy/templates/railway/reference.mdx +++ b/deploy/templates/railway/reference.mdx @@ -90,7 +90,7 @@ Local containers hot-reload on save. For production, run `./scripts/railway/rede from agno.models.anthropic import Claude def default_model(): - return Claude(id="claude-sonnet-5-0") + return Claude(id="claude-sonnet-5") ``` Add `anthropic` to `pyproject.toml`. Set `ANTHROPIC_API_KEY` in `.env` for local runs and `.env.production` for production, then regenerate pins: diff --git a/deploy/templates/render/reference.mdx b/deploy/templates/render/reference.mdx index 700d9892c..cea3c411a 100644 --- a/deploy/templates/render/reference.mdx +++ b/deploy/templates/render/reference.mdx @@ -88,7 +88,7 @@ Local containers hot-reload on save. For production, commit and push; Render reb from agno.models.anthropic import Claude def default_model(): - return Claude(id="claude-sonnet-5-0") + return Claude(id="claude-sonnet-5") ``` Add `anthropic` to `pyproject.toml`. Set `ANTHROPIC_API_KEY` in `.env` for local runs and `.env.production` for production, then regenerate pins: diff --git a/deploy/templates/scout/overview.mdx b/deploy/templates/scout/overview.mdx index 5928342c7..0473faacf 100644 --- a/deploy/templates/scout/overview.mdx +++ b/deploy/templates/scout/overview.mdx @@ -28,7 +28,7 @@ Scout is now running at `http://localhost:8000`. The [Scout README](https://gith ### Chat with Scout 1. Open [os.agno.com](https://os.agno.com) and log in. -2. Click **Add OS**, choose **Local**, enter `http://localhost:8000`, then **Connect**. +2. Click **Connect OS**, choose **Local**, enter `http://localhost:8000`, then **Connect**. 3. Try the pre-configured prompts. ## How it works @@ -85,7 +85,7 @@ The `up.sh` script provisions PostgreSQL and the `scout` service, then creates y Your first deploy will fail. That's expected. Production endpoints require RBAC authorization by default, and without a `JWT_VERIFICATION_KEY` the app refuses to serve traffic. Scout's job is to keep your company data off the public web. To get your key: -1. Open [os.agno.com](https://os.agno.com), click **Add OS** → **Live**, and enter your Railway domain. +1. Open [os.agno.com](https://os.agno.com), click **Connect OS** → **Live**, and enter your Railway domain. 2. Enable **Token Based Authorization**. 3. Paste the public key into `.env.production` as `JWT_VERIFICATION_KEY` (the full PEM block, no surrounding quotes). 4. Sync the env. Railway auto-deploys when values change. diff --git a/features/control-plane.mdx b/features/control-plane.mdx index 1a062b9fd..ecc6e5fb8 100644 --- a/features/control-plane.mdx +++ b/features/control-plane.mdx @@ -1,6 +1,6 @@ --- title: AgentOS Control Plane -sidebarTitle: Agent Control Plane +sidebarTitle: AgentOS Control Plane description: "Test, inspect, and operate AgentOS runtimes from one web interface." --- diff --git a/features/security-and-auth.mdx b/features/security-and-auth.mdx index d3dfed91a..7b84c2a99 100644 --- a/features/security-and-auth.mdx +++ b/features/security-and-auth.mdx @@ -3,13 +3,13 @@ title: Security & Auth description: "Protect AgentOS APIs with JWT verification, scoped permissions, request isolation, and per-user data boundaries." --- -Teams serving agents to employees or customers need identity, permissions, and user data boundaries at the runtime. AgentOS verifies JWTs, enforces scopes per endpoint, creates a fresh component copy for each run, and can scope persistent user data to the JWT subject. Tokens can come from the Control Plane, your backend, or an external identity provider. +Teams serving agents to employees or customers need identity, permissions, and user data boundaries at the runtime. AgentOS verifies JWTs, enforces scopes per endpoint, creates a fresh component copy for core run endpoints, and can scope persistent user data to the JWT subject. Tokens can come from the Control Plane, your backend, or an external identity provider. | Boundary | Control | |----------|---------| | Caller identity | JWT signature verification; set `verify_audience=True` to enforce the `aud` claim | | API access | Scopes enforced per endpoint | -| Run state | Fresh component copy for each request | +| Run state | Fresh component copy for core run endpoints, with some resources shared by reference | | Persistent user data | Opt-in reads, writes, and ownership checks scoped to the JWT subject | | Network and database | Reverse proxy controls and database permissions configured by the deployment | @@ -44,7 +44,7 @@ A small set of public routes are exempt from the JWT requirement: `/`, `/health` - Open [os.agno.com](https://os.agno.com) → **Add OS** → **Live** → paste your URL. Enable JWT authorization when connecting a new AgentOS, or later from the OS Settings page. + Open [os.agno.com](https://os.agno.com) → **Connect OS** → **Live** → paste your URL. Enable JWT authorization when connecting a new AgentOS, or later from the OS Settings page. @@ -111,11 +111,11 @@ The AgentOS control plane mints each token with the appropriate scopes. Scopes a ## Request isolation -Each run request gets a fresh copy of the agent, team, or workflow it's hitting. AgentOS calls `deep_copy()` on the registered component before the run, so mutable per-run state (session-scoped variables, tool execution context, run metadata) never bleeds between concurrent calls. +Core run endpoints start each run from a fresh copy of the registered agent, team, or workflow. AgentOS calls `deep_copy()` and copies mutable fields when possible. -Heavy resources (the database connection, the model client, MCP tool handles) are shared by reference; only the mutable per-run state is isolated. You get cheap concurrency without two requests racing on the same in-memory agent instance. +Models, databases, knowledge resources, MCP tool handles, and some tools are shared by reference so their connections and pools remain available. A field that cannot be copied also falls back to the original value. Custom tools and objects shared this way must be safe for concurrent use. -This is on by default for run endpoints. There's nothing to configure. +The copy happens automatically on core run endpoints. Review mutable state in custom tools and objects before serving concurrent traffic. ## User isolation From 723a2e99db6b4f936b6cab8d4a628b8e07dfd052 Mon Sep 17 00:00:00 2001 From: Ashpreet Date: Mon, 20 Jul 2026 01:02:32 +0100 Subject: [PATCH 20/21] docs: restore AgentOS security overview --- agent-os/security/overview.mdx | 120 +++++++++++++++------------------ 1 file changed, 54 insertions(+), 66 deletions(-) diff --git a/agent-os/security/overview.mdx b/agent-os/security/overview.mdx index 2d330772f..04aadb49d 100644 --- a/agent-os/security/overview.mdx +++ b/agent-os/security/overview.mdx @@ -1,104 +1,92 @@ --- title: "Security & Auth" sidebarTitle: "Security & Auth" -description: "Choose authentication, endpoint permissions, and data isolation for each AgentOS surface." +description: "Authentication modes, service account tokens, and the single auth layer covering every AgentOS surface." --- -AgentOS supports bearer authentication across the REST API, WebSockets, A2A, AG-UI, and the default MCP surface. Choose a credential based on who calls the runtime and the permissions they need. +AgentOS installs one auth layer that covers the REST API, the MCP server at `/mcp`, interfaces (A2A, AG-UI), and WebSockets. The layer runs in one of three authentication modes: -## Choose an Authentication Path +| Mode | Active when | Behavior | +|------|-------------|----------| +| `jwt` | `authorization=True`, JWT env vars (`JWT_VERIFICATION_KEY` / `JWT_JWKS_FILE`), or a manually installed `JWTMiddleware` | JWTs prove identity and scopes control permissions per endpoint. Recommended for production. | +| `security_key` | `OS_SECURITY_KEY` is set and no JWT source is configured | A shared key proves identity. No per-endpoint permissions. | +| `none` | Neither is configured | All requests pass. Development only. | -| Requirement | Configuration | Enforcement | -|-------------|---------------|-------------| -| Product clients and human users | `authorization=True` plus a JWT verification source | JWT validation and per-endpoint scopes | -| Internal tools and prototypes | `OS_SECURITY_KEY` | One shared bearer key with full access | -| Machine callers on a protected runtime | AgentOS `db`, JWT or `OS_SECURITY_KEY`, and a service account | Scoped `agno_pat_...` token | -| Hosted MCP connectors | `mcp_server=True` plus `mcp_auth=...` | OAuth on the MCP surface | -| Local development | No authentication configuration | Open access within a trusted development environment | +JWT configuration takes precedence over the security key. Service account tokens authenticate in all three modes. -JWT configuration takes precedence over `OS_SECURITY_KEY`. `AgentOS(db=...)` enables service account verification. Configure JWT authentication or `OS_SECURITY_KEY` when the runtime must reject anonymous requests. +## Authorization (JWT) -## JWT Authorization - -JWT verification proves the caller's identity. `authorization=True` also checks the token's scopes against the permissions required by each AgentOS endpoint. - -Set `JWT_VERIFICATION_KEY` to a verification key or set `JWT_JWKS_FILE` to a static JWKS file, then enable authorization: - -```python -from agno.os import AgentOS - -agent_os = AgentOS( - id="product-platform", - agents=[agent], - authorization=True, -) - -app = agent_os.get_app() -``` - -Tokens can come from the AgentOS Control Plane, your backend, or an identity provider such as WorkOS, Auth0, or Okta. Requests to protected endpoints return `401 Unauthorized` for an invalid JWT and `403 Forbidden` when the token lacks a required scope. - -See [Authorization Quickstart](/agent-os/security/authorization/quickstart) for key setup, token creation, and the first authenticated request. - -## Per-User Data Isolation - -JWT scope checks and database isolation are configured separately. Enable user isolation when non-admin callers should only access their own sessions, memories, and traces: +AgentOS validates JWT tokens and checks scopes against required permissions for each endpoint. Enable it with `authorization=True`: ```python from agno.os import AgentOS -from agno.os.config import AuthorizationConfig agent_os = AgentOS( - agents=[agent], + id="my-agent-os", + agents=[my_agent], authorization=True, - authorization_config=AuthorizationConfig(user_isolation=True), ) ``` -The authenticated JWT subject becomes the user ID for scoped reads and writes. Callers with the admin scope retain access across users. +Tokens can be issued by the AgentOS control plane, your own backend, or a third-party identity provider like WorkOS, Auth0, or Okta. Requests without a valid JWT return `401 Unauthorized`; requests with insufficient scopes return `403 Forbidden`. -See [Per-User Data Isolation](/agent-os/security/authorization/user-isolation) for ownership rules and supported resources. +See [Authorization](/agent-os/security/authorization/overview) for the full setup. -## Service Accounts +## Service Accounts (Machine Tokens) -Machine callers use opaque `agno_pat_...` tokens with scopes stored in your database. Service accounts require `AgentOS(db=...)`. Minting requires the OS security key, an admin JWT, or a JWT that holds `service_accounts:write` and every scope granted to the new token. +Machine callers such as coding agents, chat apps, and CI pipelines authenticate with opaque `agno_pat_...` tokens instead of JWTs. Tokens are minted through the API or `agno tokens create`, carry their own scopes, and attribute every run to an `sa:` principal: ```bash -agno tokens create ci-runner \ - --scopes agents:run \ - --scopes sessions:read +curl -X POST http://localhost:7777/agents/my-agent/runs \ + -H "Authorization: Bearer agno_pat_..." \ + -d "message=hello" -d "stream=false" ``` -Each request runs as the `sa:` principal. AgentOS checks the token's stored scopes against protected endpoints in every authentication mode. +Service account scopes are ACL data stored in your database, so they are enforced in every authentication mode, including `security_key` and `none`. -See [Service Accounts](/agent-os/security/authorization/service-accounts) for minting, rotation, expiry, and revocation. +See [Service Accounts](/agent-os/security/authorization/service-accounts) for minting, scoping, and revocation. ## Security Key -Set a shared secret for a local or single-team deployment: +Set a shared secret in the `OS_SECURITY_KEY` environment variable: ```bash export OS_SECURITY_KEY="your-secret-key" ``` -Protected endpoints require `Authorization: Bearer `. A valid security key has full access and can mint service account tokens. JWT authorization is the production path for systems with multiple users and endpoint permissions. - -## Authentication by Surface +Requests without a valid `Authorization: Bearer ` header return `401 Unauthorized`. This is the simplest path to a protected AgentOS, suitable for local development or single-team prototypes. A valid key is a trusted root: it passes every endpoint and can mint service account tokens. -| Surface | Authentication | -|---------|----------------| -| REST API and WebSockets | JWT, `OS_SECURITY_KEY`, or service account token | -| A2A and AG-UI | Shared AgentOS bearer authentication; endpoint scopes with JWT authorization or service accounts | -| Slack, Telegram, and WhatsApp | Interface-specific webhook signatures or secrets | -| MCP at `/mcp` | Shared bearer authentication by default; OAuth when `mcp_auth` is configured | -| Health and API documentation | Public routes for health checks, OpenAPI, and interactive docs | +For production deployments, use [Authorization](#authorization-jwt) instead. ## Next Steps -| Task | Guide | -|------|-------| -| Configure JWT verification and scopes | [Authorization](/agent-os/security/authorization/overview) | -| Mint credentials for machine callers | [Service Accounts](/agent-os/security/authorization/service-accounts) | -| Review endpoint permissions | [Scopes](/agent-os/security/authorization/scopes) | -| Isolate sessions, memories, and traces | [Per-User Data Isolation](/agent-os/security/authorization/user-isolation) | -| Configure MCP clients and tools | [MCP](/agent-os/mcp/mcp) | + + + JWT validation, scopes, roles, and per-user data isolation. + + + Mint, scope, and revoke opaque machine tokens. + + + Token sources, claim extraction, and parameter injection. + + + The full permission reference for every AgentOS endpoint. + + From c17a63213c2897b1ab7e7e0d558596f70d6f1578 Mon Sep 17 00:00:00 2001 From: Ashpreet Date: Mon, 20 Jul 2026 01:12:28 +0100 Subject: [PATCH 21/21] docs: refine AgentOS introduction copy --- agent-os/connect-your-os.mdx | 6 +++--- agent-os/control-plane.mdx | 2 +- agent-os/introduction.mdx | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/agent-os/connect-your-os.mdx b/agent-os/connect-your-os.mdx index 6afa3391c..fc94fee5b 100644 --- a/agent-os/connect-your-os.mdx +++ b/agent-os/connect-your-os.mdx @@ -1,15 +1,15 @@ --- title: "Connect Your AgentOS" -description: "Connect a local or deployed AgentOS runtime to the Control Plane." +description: "Connect your AgentOS to the control plane for monitoring and management." --- -Connect a local runtime for development or a deployed runtime to test and operate its agents, teams, and workflows from the [AgentOS Control Plane](https://os.agno.com). +Connect a local or deployed AgentOS runtime to monitor and manage its agents, teams, and workflows from the [AgentOS Control Plane](https://os.agno.com). ## Before You Connect | Runtime | Requirements | |---------|--------------| -| Local | AgentOS running on your machine and reachable from your browser, usually at `http://localhost:7777` | +| Local | AgentOS running on your machine and reachable from your browser, usually at `http://localhost:7777` or `http://localhost:8000` | | Live | AgentOS available at a browser-reachable HTTPS URL with [Security & Auth](/agent-os/security/overview) configured for production traffic | diff --git a/agent-os/control-plane.mdx b/agent-os/control-plane.mdx index 4e932110c..cdbe9c4b5 100644 --- a/agent-os/control-plane.mdx +++ b/agent-os/control-plane.mdx @@ -1,6 +1,6 @@ --- title: "AgentOS Control Plane" -description: "Run components, inspect execution, and operate connected AgentOS runtimes." +description: "Run components, inspect runs, and manage AgentOS runtimes." --- Use the [AgentOS Control Plane](https://os.agno.com) to test agents, teams, and workflows, follow runs from sessions into traces, and manage the state and automation exposed by a connected AgentOS runtime. diff --git a/agent-os/introduction.mdx b/agent-os/introduction.mdx index b4726655d..143facd32 100644 --- a/agent-os/introduction.mdx +++ b/agent-os/introduction.mdx @@ -1,10 +1,10 @@ --- title: "What is AgentOS?" sidebarTitle: "Introduction" -description: "The FastAPI runtime for serving and operating agents, teams, and workflows." +description: "The FastAPI runtime for serving agents, teams, and workflows." --- -**AgentOS is the FastAPI runtime for serving and operating agent systems.** +**AgentOS is a FastAPI-powered runtime for serving multi-agent systems.** The smallest AgentOS looks like this: @@ -24,7 +24,7 @@ agent_os = AgentOS(agents=[agent]) app = agent_os.get_app() ``` -This registers one agent, stores its sessions in a local SQLite database, and returns a FastAPI application. +This registers one agent, stores its sessions in a local SQLite database, and returns a FastAPI app that you can run locally or deploy to your cloud provider. Engineering teams use AgentOS to serve agents, teams, and workflows through one backend. It provides REST endpoints for runs, sessions, memory, knowledge, evaluations, approvals, and schedules. Add MCP, messaging interfaces, tracing, and JWT authorization as your deployment needs them.