Agno Admin Guide

This guide is for the engineers, architects, and operators who run Agno in production: people standing up an AgentOS service, wiring it to a database, securing it with JWT and RBAC, instrumenting it with tracing, and deploying it to a cloud. It documents the system's architecture, the monorepo layout, the full configuration surface, the storage and security models, operational procedures, and the internals you need to extend or debug the framework.

For end-user, task-oriented material — building agents, adding tools, writing workflows — see the companion User Guide. This guide assumes you have read it and focuses on running Agno as a platform.

Source of truth. Everything here is derived from the Agno source at commit 5b9cfec (package version 2.6.12). Where behavior depends on a constructor flag or environment variable, the exact name from the source is given.

1. Executive Summary

Agno is a Python SDK — distributed as the agno package — for building agent platforms. It is not a hosted service: you embed it in your own code and run it on your own infrastructure, against your own database. There is no required Agno-operated backend; the optional os.agno.com control plane is a UI that talks to your AgentOS instance.

The system has three layers, each opt-in:

Architecturally significant properties:

• Stateless compute, stateful database. Agents themselves hold no durable state. Sessions, user memories, knowledge, traces, and component definitions all live in a database you supply (db=). This makes AgentOS horizontally scalable — run many replicas behind a load balancer, all pointed at the same DB.
• Provider-agnostic. 50+ model providers sit behind a single Model interface; switching providers is a one-line change.
• Dependency-light core, heavy optional surface. The core depends only on pydantic, httpx, typer, rich, pyyaml, and a few others. Every model, tool, vector DB, and storage backend is an optional extra, so a production image installs only what it uses.

2. Architecture

2.1 Request lifecycle

When a client calls an AgentOS run endpoint (e.g. POST /agents/{id}/runs), the flow is:

HTTP request
   │
   ▼
FastAPI route (os/routers/agents)
   │  ── JWT/auth middleware: validate token, resolve scopes ──┐
   │                                                            │ (RBAC)
   ▼                                                            │
Resolve Agent by id (from registered agents or DB)             │
   │                                                            │
   ▼                                                            │
Agent.arun(input, session_id, user_id)                         │
   │   1. Load session + history from db                        │
   │   2. Build context (system msg, history, knowledge, memory)│
   │   3. Resolve tools (incl. MCP, callable factories)         │
   │   4. Call Model  ◄──► tool-call loop ──► provider API      │
   │   5. Optional: reasoning, guardrails (pre/post hooks)      │
   │   6. Persist run, update memory/summaries (async)          │
   │   7. Emit OpenTelemetry trace span (if tracing=True)       │
   ▼                                                            │
RunOutput  ── serialized to JSON or streamed via SSE ──────────┘

The agent's logic is intentionally split across private submodules under agno/agent/ — _run.py (the run loop), _messages.py (context building), _tools.py (tool resolution), _session.py (persistence), _managers.py (memory/culture). The public agent.py is a thin dataclass plus a facade that delegates to these. When debugging the run loop, read agno/agent/_run.py, not agent.py.

2.2 The core primitives

2.3 The database as the system of record

Every durable concern routes through a BaseDb implementation (agno/db/base.py). One database can hold all component types: sessions, runs, user memories, session summaries, knowledge metadata, traces, eval runs, and saved component definitions (versioned agents/teams/workflows). The ComponentType and SessionType enums in agno/db/base.py classify what is stored.

This single-DB design is why AgentOS(db=...) can auto-provision tables (auto_provision_dbs=True by default) and why agents declared without their own db inherit the OS-level one.

3. Repository Layout (Monorepo)

Agno is a monorepo. Operators should understand which package provides what.

agno/                          (repository root)
├── libs/
│   ├── agno/                  → the `agno` PyPI package (the SDK)
│   │   ├── agno/
│   │   │   ├── agent/         Agent class + private run/message/tool/session modules
│   │   │   ├── team/          Team class + coordination modes
│   │   │   ├── workflow/      Workflow + Step/Parallel/Loop/Condition/Router
│   │   │   ├── models/        50+ provider adapters (openai, anthropic, google, …)
│   │   │   ├── tools/         ~130 toolkits + @tool decorator + Toolkit base
│   │   │   ├── knowledge/     readers, chunking, embedders, rerankers
│   │   │   ├── vectordb/      pgvector, lancedb, chroma, qdrant, milvus, …
│   │   │   ├── db/            postgres, sqlite, mysql, mongo, redis, dynamo, …
│   │   │   ├── memory/        user-memory managers + strategies
│   │   │   ├── session/       session + summary objects
│   │   │   ├── os/            AgentOS: app.py, routers/, middleware/, auth, scopes
│   │   │   ├── reasoning/     step-by-step reasoning
│   │   │   ├── guardrails/    input/output guardrails
│   │   │   ├── scheduler/     cron scheduling
│   │   │   ├── tracing/       OpenTelemetry spans + schemas
│   │   │   └── registry/      component registry
│   │   ├── migrations/        v1→v2 migration helpers
│   │   └── pyproject.toml     package metadata + ALL optional extras
│   └── agno_infra/            → the `agno-infra` package (the `ag` CLI)
│       └── agno/
│           ├── cli/           entrypoint + `infra` subcommands
│           ├── docker/        Docker resource definitions
│           └── aws/           AWS resource definitions (ECS, RDS, S3, …)
├── cookbook/                  hundreds of runnable examples (not shipped)
└── scripts/                   dev/release scripts

Note

cookbook/ is the single best onboarding resource — every feature has a runnable example there, organized by topic (02_agents, 03_teams, 04_workflows, 05_agent_os, 07_knowledge, 91_tools, 90_models). It is not part of the installed package.

4. Requirements

Production images should pin Agno and install exactly the extras needed:

pip install "agno[os,postgres,pgvector,openai,anthropic]==2.6.12"

Warning

Some extras are intentionally disabled at the source level due to upstream supply-chain incidents (the pyproject.toml notes litellm compromised on PyPI 2026-03-24 and mistralai quarantined 2026-05-12, both excluded from the aggregate agno[models] extra). If you need those providers, install them deliberately and review their advisories first.

5. AgentOS: Configuration Mastery

AgentOS (agno/os/app.py) is the deployment unit. Its constructor is the primary configuration surface.

5.1 Constructor reference

from agno.os import AgentOS

agent_os = AgentOS(
    agents=[...], teams=[...], workflows=[...], knowledge=[...],
    db=...,
    ...
)

5.2 Getting and serving the app

app = agent_os.get_app()      # returns the FastAPI instance (for uvicorn/gunicorn)

agent_os.serve("module:app", host="0.0.0.0", port=7777, workers=4)

serve() wraps uvicorn. Host and port can be overridden by environment variables (see below) — env wins over the arguments.

5.3 Environment variables

5.4 AgnoAPISettings

The settings= argument takes an AgnoAPISettings (agno/os/settings.py), a pydantic-settings model populated from the environment:

Important

In production, either enable full JWT authorization (authorization=True) or set os_security_key to a strong secret. With neither, the API is unauthenticated. Also set docs_enabled=False to avoid exposing your endpoint schema.

6. Storage Backends

All persistence goes through a BaseDb / AsyncBaseDb implementation. Pick the backend that matches your operational stack; the agent/OS code is identical regardless.

from agno.db.postgres import PostgresDb
db = PostgresDb(db_url="postgresql+psycopg://ai:ai@db:5432/agno")

6.1 Provisioning and migrations

• Auto-provisioning. With auto_provision_dbs=True (default), AgentOS creates required tables on startup.
• Migrations. Schema-evolution helpers live in agno/db/migrations/ (Alembic-style versions/). A migrations/v1_to_v2/ package exists for upgrading data written by Agno v1 to the v2 schema. Run migrations as a deliberate, backed-up step in production; do not rely on auto-provisioning to alter existing tables.

6.2 Vector databases (for Knowledge)

Knowledge persistence is separate from the relational db. Supported vector stores include PgVector, LanceDb, Chroma, Qdrant, Milvus, Pinecone, Weaviate, MongoDb, Redis, Couchbase, Cassandra, SingleStore, Clickhouse, SurrealDb, and UpstashDb (each under agno/vectordb/<name> with a matching extra).

Tip

A common production topology is one Postgres instance serving both roles: PostgresDb for sessions/memory/traces and PgVector (same database, pgvector extension) for knowledge. This minimizes operational surface.

7. Security

7.1 Authentication options

AgentOS offers two authentication models:

1. Static bearer token — set settings.os_security_key. Every request must send Authorization: Bearer <key>. Simple, coarse-grained (all-or-nothing). Suitable for internal/single-tenant deployments.
2. JWT + RBAC — set authorization=True (or configure JWT env vars). The JWT middleware validates tokens and enforces per-resource scopes. Required for multi-user / multi-tenant deployments.

JWT validation is configured via environment:

The middleware extracts the bearer token from the Authorization header, validates the signature, and attaches the caller's scopes to the request for downstream authorization.

7.2 RBAC scopes

Authorization is scope-based (agno/os/scopes.py). Scopes come in three shapes:

Resource types include agents, teams, workflows, sessions, memories, knowledge, metrics, traces, schedules, approvals, and config. Legacy system:* scopes are accepted as aliases for config:*.

The middleware filters list endpoints to only the resources a token may see (get_accessible_resources, filter_resources_by_access) and gates run/mutation endpoints with check_resource_access / require_resource_access. Multi-tenant isolation is achieved by issuing each tenant a token scoped to their resource ids.

# A token granting run access to one agent and read access to its sessions:
scopes: ["agents:support-bot:run", "sessions:read"]

7.3 CORS and surface hardening

• CORS origins are controlled by cors_allowed_origins / settings.cors_origin_list. Agno's own domains (agno.com, app.agno.com, os.agno.com, localhost:3000) are always appended so the hosted control-plane UI can connect; remove these in set_cors_origin_list if you do not use the Agno UI.
• Disable the OpenAPI docs in production (docs_enabled=False).
• Run agents with least-privilege tools. Gate dangerous tools behind @tool(requires_confirmation=True) and the approvals workflow (/approvals endpoints) so a human resolves them before execution.

7.4 Secrets and credentials

Model and tool credentials are read from environment variables (python-dotenv loads a .env automatically). Never bake keys into images. Per the source's error surface, a missing key fails loudly at first use with ValueError: <PROVIDER>_API_KEY not set.

8. Observability & Tracing

Set tracing=True on AgentOS (or per agent) to emit OpenTelemetry spans for every run. Spans capture the model calls, tool calls, reasoning steps, and timings. Schemas live in agno/tracing/schemas.py, which imports opentelemetry-sdk at module load — so opentelemetry-sdk must be installed wherever tracing-capable routers are imported (it is part of agno[os]).

Traces are also queryable through the API:

Run-level metrics (token counts, latencies) are on every RunOutput.metrics and exposed at GET /metrics (with POST /metrics/refresh to recompute). For third-party observability, cookbook/observability/ shows integrations with Langfuse, Langsmith, Arize Phoenix, Logfire, MLflow, and others via OpenInference — configured purely through their own env vars (e.g. LANGFUSE_PUBLIC_KEY, PHOENIX_API_KEY), not Agno-specific config.

9. Scheduling & Background Jobs

Enable the cron scheduler with scheduler=True. It polls every scheduler_poll_interval seconds (default 15) and triggers scheduled runs via HTTP back into the OS (scheduler_base_url, default http://127.0.0.1:7777), authenticated with internal_service_token. The scheduler needs croniter and pytz (agno[scheduler], also pulled by agno[os]).

Manage schedules through the API:

Note

The scheduler runs in-process with no external broker (no Celery/Redis queue required). For high-availability scheduling across replicas, ensure only one instance owns scheduling or coordinate via the shared DB; running the scheduler on every replica will multiply triggers.

10. Deployment

10.1 Running the server

AgentOS is a standard ASGI app. For production, run it under uvicorn/gunicorn with multiple workers behind a reverse proxy:

# directly
python my_os.py            # calls agent_os.serve(..., workers=4)

# or via uvicorn
uvicorn my_os:app --host 0.0.0.0 --port 7777 --workers 4

Because compute is stateless, scale horizontally by running more replicas against the same database. Put TLS termination, rate limiting, and (optionally) auth at the proxy.

10.2 The ag CLI (agno-infra)

The agno-infra package provides the ag entrypoint (agno.cli.entrypoint:agno_cli) for scaffolding and deploying AgentOS to Docker or AWS:

The AWS resource library (libs/agno_infra/agno/aws/resource/) covers ECS, EC2, RDS, ElastiCache, S3, IAM, ELB, ACM, Secrets Manager, Glue, EMR, and CloudFormation — i.e. it can stand up a full container-based deployment. The Docker resource library targets local/compose-style deployment.

10.3 Containerization

A typical Dockerfile installs only the needed extras and runs serve:

FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install "agno[os,postgres,pgvector,openai]==2.6.12"
ENV AGENT_OS_HOST=0.0.0.0 AGENT_OS_PORT=7777 AGNO_TELEMETRY=false
EXPOSE 7777
CMD ["python", "my_os.py"]

Tip

Bake your provider API keys in at runtime (env/secret manager), not build time. Point db_url at a managed Postgres. Set auto_provision_dbs=False once schema is stable and run migrations explicitly.

11. Operations Runbook

11.1 Backups

Your db is the platform's state. Back it up on your normal cadence; a restore brings back every session, memory, trace, and saved component. Knowledge embeddings live in the vector DB — back that up too, or be prepared to re-ingest source documents.

11.2 Scaling guidance

• Throughput scales with replicas (stateless compute).
• Latency is dominated by the model provider; use fallback_models to ride out provider slowdowns.
• Context cost grows with history — cap num_history_runs, enable compress_tool_results=True, and use session summaries for long sessions to avoid ModelProviderError: maximum context length failures.
• Run hooks in the background (run_hooks_in_background=True) so guardrails/eval hooks don't block responses.

12. Internals & Module Reference

For engineers extending or debugging Agno. The codebase is large (~7.7M chars across libs/agno); the table below is the navigational map for the highest-traffic modules.

12.1 The Model interface (extending providers)

A provider adapter subclasses Model (agno/models/base.py) and implements the request/response/stream methods plus tool-call parsing. Provider classes live under agno/models/<provider>/ and are re-exported from that package's __init__.py (e.g. OpenAIChat, Claude, Gemini, Groq, MistralChat, AwsBedrock, AzureOpenAI). Error handling is centralized: providers raise ModelProviderError, which the run loop classifies as retryable (server errors, context-length) or fatal (invalid API key) to drive retries and fallbacks.

12.2 Component versioning & the registry

Agents, teams, and workflows can be persisted and versioned: agent.save(db=..., stage="published", label=...) writes a definition; Agent.load(id, db=...) reconstructs it. The Registry resolves nested references (a team's members, a workflow's steps) during load. This is what powers the /components and /registry endpoints and the "edit in the UI, reload without redeploy" workflow.

13. Code Quality & Conventions

• Typed throughout. py.typed is shipped; mypy runs with pydantic.mypy plugin, check_untyped_defs, no_implicit_optional. Hundreds of third-party libs are listed under [[tool.mypy.overrides]] with ignore_missing_imports because they are optional extras.
• Ruff for linting/formatting, line length 120, target py39. F401 (unused import) is ignored in __init__.py files because those re-export the public API.
• Facade pattern. Large classes (Agent, Team) are dataclasses whose methods delegate to private _* modules, keeping the public file readable while isolating heavy logic. Sync and async paths are maintained in parallel (x/ax).
• Optional-by-default dependencies. Anything beyond the slim core is gated behind an import guard that raises a pip install-instructional ImportError. This is a deliberate UX choice — keep it when adding integrations.
• Backward compatibility. Deprecated constructor params are kept and mapped to their replacements with a log_warning (e.g. enable_user_memories → update_memory_on_run, search_session_history → search_past_sessions). Honor this pattern when renaming.

14. Testing Strategy

Tests live under libs/agno/tests/ split into unit/, integration/, and system/. The agno[dev] and agno[tests] extras install the toolchain (pytest, pytest-asyncio, pytest-cov, pytest-mock, mypy, ruff, plus provider SDKs for model tests).

• tests/unit/models/ includes retry/error-classification suites that assert how ModelProviderErrors (context-length, server errors, invalid key) drive retry vs. fail decisions — read these to understand resilience behavior.
• asyncio_mode = "auto" means async tests need no explicit marker.
• Integration tests hit real provider/DB backends and are gated by the integration-tests extra and credentials; run unit tests in CI by default.

cd libs/agno
pip install -e ".[dev]"
pytest tests/unit -q

15. Known Issues, Risks & Improvements

Derived from the community issue tracker and source structure:

16. Quick Reference

Minimal production AgentOS

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.db.postgres import PostgresDb
from agno.os import AgentOS

db = PostgresDb(db_url="postgresql+psycopg://ai:ai@db:5432/agno")
assistant = Agent(name="Assistant", model=OpenAIChat(id="gpt-4o"), db=db)

agent_os = AgentOS(
    agents=[assistant],
    db=db,
    authorization=True,     # JWT + RBAC
    tracing=True,           # OpenTelemetry
    scheduler=True,         # cron jobs
    telemetry=False,        # no usage reporting
)
app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve("my_os:app", host="0.0.0.0", port=7777, workers=4)

Production checklist

• [ ] Pin Agno and install only needed extras (agno[os,postgres,pgvector,openai]==2.6.12).
• [ ] Point db (and vector DB) at managed, backed-up instances.
• [ ] authorization=True with JWT_VERIFICATION_KEY/JWT_JWKS_FILE, or a strong os_security_key.
• [ ] docs_enabled=False; lock down cors_allowed_origins.
• [ ] Provider keys via secret manager; AGNO_TELEMETRY=false.
• [ ] tracing=True wired to your OTel collector; /health wired to the load balancer.
• [ ] auto_provision_dbs=False after first deploy; run migrations explicitly.
• [ ] Single scheduler owner (or DB coordination) if scheduler=True across replicas.
• [ ] Cap history (num_history_runs) and enable summaries/compression for long sessions.

Key environment variables

Endpoint families

/agents · /teams · /workflows · /sessions · /memories · /knowledge · /metrics · /traces · /schedules · /approvals · /components · /eval-runs · /registry · /health — each with the run sub-resources (/runs, /runs/{id}, .../cancel, .../continue, .../resume) where applicable.