Agno User Guide

Agno is a Python SDK for building, running, and managing agent platforms. You use it to create AI agents in a handful of lines, compose them into multi-agent teams and deterministic workflows, give them tools, memory, and knowledge, and then run the whole thing as a production HTTP service with tracing, scheduling, human approvals, and role-based access control — all in your own infrastructure.

This guide is task-oriented: it shows you how to install Agno, build your first agent, and progressively add every capability the framework offers. Architecture, deployment internals, security hardening, and the full configuration reference live in the companion Admin Guide.

Note

Agno is an SDK and library, not a command-line application. You build agents in Python and run them as scripts or services. The only shipped CLI (ag / agno) belongs to the separate agno-infra package and is used for scaffolding and deploying AgentOS projects — see Deploying with the ag CLI.

Table of Contents

1. What Is Agno
2. Quick Start
3. Installation
4. Core Concepts
5. Building Agents
6. Models and Providers
7. Tools and Toolkits
8. Knowledge and RAG
9. Memory
10. Sessions, State, and History
11. Structured Input and Output
12. Reasoning
13. Guardrails, Hooks, and Human-in-the-Loop
14. Multi-Agent Teams
15. Workflows
16. Running as a Service: AgentOS
17. Deploying with the ag CLI
18. Common Recipes
19. Troubleshooting
20. Frequently Asked Questions
21. Reference

1. What Is Agno

Agno lets you own your entire agent stack. You keep control of your data, context, tools, permissions, memory, and human-review loops; you run the platform in your own cloud; and you manage it through a single control plane.

At its heart, Agno gives you three composable primitives:

Around those primitives, Agno provides everything a production agent platform needs:

• 50+ model providers behind one Model interface — OpenAI, Anthropic, Google, Groq, Mistral, Ollama, AWS Bedrock, Azure, and dozens more.
• ~130 pre-built toolkits — web search, finance data, code execution, databases, Slack, GitHub, Gmail, and many others.
• Knowledge / RAG with readers, chunkers, embedders, rerankers, and 18+ vector databases.
• Memory that persists user facts across sessions.
• Storage for sessions, runs, memory, knowledge, and traces in your own database (PostgreSQL, MySQL, SQLite, MongoDB, Redis, DynamoDB, and more).
• AgentOS — a FastAPI runtime that exposes your agents as a production API with SSE/WebSocket streaming, JWT-based RBAC, OpenTelemetry tracing, cron scheduling, human-approval gates, and chat interfaces for Slack, Telegram, WhatsApp, AG-UI, and A2A.

Tip

If you only want a chatbot in a script, you need just the agno package and one model provider. If you want to serve agents over HTTP for a product, add agno[os]. If you want to deploy that to a cloud, add agno-infra. Each layer is opt-in.

2. Quick Start

Install Agno with a model provider

OpenAI

pip install -U agno openai
export OPENAI_API_KEY=sk-...

Anthropic

pip install -U "agno[anthropic]"
export ANTHROPIC_API_KEY=sk-ant-...

Google Gemini

pip install -U "agno[google]"
export GOOGLE_API_KEY=...

Your first agent

Create finance_agent.py:

from agno.agent import Agent
from agno.models.openai import OpenAIChat

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    instructions="You are a concise financial analyst. Facts only, no speculation.",
    markdown=True,
)

agent.print_response("Explain what a P/E ratio is in two sentences.", stream=True)

Run it:

python finance_agent.py

The price-to-earnings (P/E) ratio measures a company's current share price
relative to its earnings per share. A higher P/E suggests investors expect
higher future growth, while a lower P/E may indicate a more conservatively
valued or slower-growing company.

Note

print_response() renders the answer to your terminal (with live streaming when stream=True). For programmatic use, call agent.run(...), which returns a RunOutput object you can inspect — see Building Agents.

Add a tool

Tools let the model fetch live data or take actions. Here the agent uses real Yahoo Finance data:

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.tools.yfinance import YFinanceTools

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    tools=[YFinanceTools(all=True)],
    instructions="You are a finance analyst. Always note the data timestamp.",
    add_datetime_to_context=True,
    markdown=True,
)

agent.print_response("Give me a quick investment brief on NVIDIA", stream=True)

pip install yfinance   # or: pip install "agno[yfinance]"
python finance_agent.py

That is the whole loop: a model, instructions, and tools. Everything else in this guide builds on this pattern.

3. Installation

Requirements

The base agno package is intentionally lightweight. Model providers, tools, databases, vector stores, and the server runtime are all optional extras you add as needed.

Install the base package

pip install -U agno

Extras matrix

Install extras with pip install "agno[<extra>]". You can combine them: pip install "agno[openai,os,pgvector]".

Model providers

Warning

As of this writing, the agno[models] meta-extra temporarily excludes litellm and mistralai because of upstream PyPI supply-chain incidents (see the Admin Guide's security section). Install them individually only if you have verified the upstream package.

Server runtime, storage, and infrastructure

Vector databases (agno[vectordbs] for all)

agno[pgvector], agno[chromadb], agno[lancedb], agno[qdrant], agno[milvusdb], agno[weaviate], agno[mongodb], agno[pinecone], agno[couchbase], agno[cassandra], agno[clickhouse], agno[singlestore], agno[surrealdb], agno[upstash], agno[redis].

Knowledge / document readers (agno[knowledge] for all)

agno[pdf], agno[docx], agno[pptx], agno[csv], agno[excel], agno[text], agno[markdown], agno[docling], agno[chonkie] (chunking).

Interfaces and integrations

Observability

agno[opentelemetry], agno[langfuse], agno[arize], agno[weave], agno[openlit].

Tip

Tool extras follow the same pattern — agno[exa], agno[github], agno[gmail], agno[duckdb], agno[firecrawl], and many more. Install agno[tools] to pull a curated bundle, or add individual tool extras as you adopt them.

Set provider credentials

Most providers read an API key from an environment variable. Agno loads a .env file automatically (via python-dotenv):

# .env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...

4. Core Concepts

These objects compose. An Agent can have knowledge, memory, tools, and a db. A Team contains Agents. A Workflow orchestrates Agents, Teams, and plain functions. An AgentOS exposes any of them over HTTP.

5. Building Agents

The Agent constructor is where almost all configuration happens. It accepts roughly 150 keyword arguments, grouped by capability below. Every argument is keyword-only and optional except where noted.

from agno.agent import Agent
from agno.models.openai import OpenAIChat

agent = Agent(
    name="Support Agent",
    model=OpenAIChat(id="gpt-4o"),
    description="A helpful customer-support assistant.",
    instructions=[
        "Answer in plain language.",
        "If you don't know, say so.",
    ],
    markdown=True,
)

Running an agent

result = agent.run("What is the capital of France?")
print(result.content)   # "Paris"

Important

If your instructions, tools, or system message are defined as async callables, you must use arun() / aprint_response(). Calling run() will raise Instructions function is async, use agent.arun() instead.

Identity and model

Instructions and system message

Tools

See Tools and Toolkits.

Knowledge (RAG)

See Knowledge and RAG.

Memory

See Memory.

Sessions, state, and history

See Sessions, State, and History.

Structured output

See Structured Input and Output.

Reasoning

See Reasoning.

Hooks and guardrails

See Guardrails, Hooks, and Human-in-the-Loop.

Streaming and retries

Telemetry and debug

Caution

Telemetry is currently synchronous and can add latency to agent.run(). If you need the lowest possible per-call latency, set telemetry=False (or AGNO_TELEMETRY=false). See Troubleshooting.

6. Models and Providers

Agno wraps every provider behind a common Model interface. Import the class for your provider and pass it as model=:

from agno.models.openai import OpenAIChat
from agno.models.anthropic import Claude
from agno.models.google import Gemini

agent = Agent(model=Claude(id="claude-sonnet-4-5"))

Provider class reference

Agno additionally ships providers for Cerebras, Cloudflare, Fireworks, Hugging Face, IBM watsonx, LiteLLM, LM Studio, llama.cpp, Meta, NVIDIA, Nebius, OpenRouter, Perplexity, Portkey, Requesty, SambaNova, Together, vLLM, and more — over 45 in total. Each lives under agno.models.<provider>.

The provider:id shorthand

Instead of importing a class, you can pass a model string. Agno resolves the provider and instantiates the right class:

agent = Agent(model="openai:gpt-4o")
agent = Agent(model="anthropic:claude-sonnet-4-5")

Warning

The string must be "<provider>:<model_id>". A bare model name raises: ValueError: Invalid model string format: 'gpt-4o'. Model strings should be in format '<provider>:<model_id>' e.g. 'openai:gpt-4o'.

Fallback models

Provide alternates that are tried automatically when the primary model errors:

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    fallback_models=["anthropic:claude-sonnet-4-5", "google:gemini-2.5-flash"],
)

7. Tools and Toolkits

Tools are functions the model can call. Agno ships ~130 pre-built toolkits and lets you write your own.

Using a built-in toolkit

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.tools.duckduckgo import DuckDuckGoTools

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    tools=[DuckDuckGoTools()],
    instructions="Search the web and cite your sources.",
)
agent.print_response("What happened in tech news today?", stream=True)

Toolkit catalog (selected)

Tip

Many toolkits expose an all=True flag (e.g. YFinanceTools(all=True)) to enable every function, or accept granular flags to expose only what you need. Most require their extra: e.g. pip install "agno[github]" for GithubTools.

Writing a custom tool

Any plain Python function with type hints and a docstring becomes a tool:

from agno.agent import Agent
from agno.models.openai import OpenAIChat

def get_weather(city: str) -> str:
    """Return the current weather for a city.

    Args:
        city: The city name, e.g. "London".
    """
    return f"It is 18°C and sunny in {city}."

agent = Agent(model=OpenAIChat(id="gpt-4o"), tools=[get_weather])
agent.print_response("What's the weather in Tokyo?")

The docstring becomes the tool description and the type hints define the JSON schema the model fills in.

Limiting and controlling tool use

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    tools=[get_weather],
    tool_call_limit=3,          # at most 3 tool calls per run
    tool_choice="auto",          # let the model decide (default when tools present)
)

Model Context Protocol (MCP)

Connect to MCP servers to expose their tools to your agent:

pip install "agno[mcp]"

from agno.tools.mcp import MCPTools

agent = Agent(model=OpenAIChat(id="gpt-4o"), tools=[MCPTools(command="npx -y @modelcontextprotocol/server-filesystem /data")])

Caution

If MCP toolkit initialization fails, older versions could spin the CPU. Always wrap MCP setup in error handling and pin a recent Agno release (see Troubleshooting).

8. Knowledge and RAG

Knowledge gives an agent a searchable corpus. At run time the agent retrieves relevant chunks and grounds its answer in them (Retrieval-Augmented Generation).

The pipeline

Documents → Reader → Chunker → Embedder → Vector DB → (search at run time)

Vector database support

PgVector, ChromaDb, LanceDb, Qdrant, Milvus, Weaviate, MongoDb, Pinecone, Couchbase, Cassandra, Clickhouse, SingleStore, SurrealDb, UpstashDb, Redis, plus LangChain and LlamaIndex adapters.

Example: PDF knowledge with pgvector

pip install "agno[pdf,pgvector,openai]"

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.pgvector import PgVector

knowledge = Knowledge(
    vector_db=PgVector(
        table_name="docs",
        db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
    ),
)
# Load content (run once)
knowledge.add_content(path="./handbook.pdf")

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    knowledge=knowledge,
    search_knowledge=True,        # agentic RAG: the agent searches when needed
    instructions="Answer using the handbook. Cite the relevant section.",
)
agent.print_response("What is our refund policy?", stream=True)

Note

With search_knowledge=True (the default when knowledge is set), the agent gets a search tool and decides when to query — this is Agentic RAG. Set add_knowledge_to_context=True instead to always inject retrieved chunks into every prompt.

Knowledge filters

Restrict searches by document metadata:

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    knowledge=knowledge,
    knowledge_filters={"department": "finance"},
)

Set enable_agentic_knowledge_filters=True to let the agent choose filters dynamically.

9. Memory

Memory captures durable facts about a user — preferences, history, context — and recalls them in future sessions. Unlike session_state (scoped to one conversation), memories persist across sessions for a user_id.

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.db.sqlite import SqliteDb

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    db=SqliteDb(db_file="agent.db"),
    user_id="user_123",
    enable_agentic_memory=True,     # the agent manages memories with tools
    add_memories_to_context=True,   # recall them in the prompt
)

agent.print_response("Remember that I'm vegetarian and allergic to peanuts.")
# ... later, in a new session ...
agent.print_response("Suggest a dinner recipe.")   # respects dietary facts

Important

Memory requires a db. Without one, there is nowhere to persist memories between sessions.

10. Sessions, State, and History

Sessions

A session is one conversation thread, identified by session_id and persisted in a db. Reuse a session_id to continue a conversation:

from agno.db.sqlite import SqliteDb

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    db=SqliteDb(db_file="agent.db"),
    session_id="chat_42",
    add_history_to_context=True,
    num_history_runs=5,
)
agent.print_response("My name is Sam.")
agent.print_response("What's my name?")   # "Sam" — history is in context

Session state

session_state is a mutable dict persisted with the session. Use it for counters, preferences, or scratch data:

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    db=SqliteDb(db_file="agent.db"),
    session_state={"cart": []},
    add_session_state_to_context=True,
    enable_agentic_state=True,   # let the agent mutate the state via tools
)

History controls

11. Structured Input and Output

Typed output

Pass a Pydantic model as output_schema to get validated structured data instead of free text:

from pydantic import BaseModel
from agno.agent import Agent
from agno.models.openai import OpenAIChat

class StockAnalysis(BaseModel):
    ticker: str
    sentiment: str
    target_price: float

agent = Agent(model=OpenAIChat(id="gpt-4o"), output_schema=StockAnalysis)

result = agent.run("Analyze NVDA")
analysis = result.content          # a StockAnalysis instance
print(analysis.ticker, analysis.target_price)

Typed input

Validate inputs before the run with input_schema:

class AnalysisRequest(BaseModel):
    ticker: str
    horizon_days: int

agent = Agent(model=OpenAIChat(id="gpt-4o"), input_schema=AnalysisRequest)
agent.run(AnalysisRequest(ticker="AAPL", horizon_days=30))

Warning

When input_schema is set, input is required and validated. Passing a mismatched type raises Cannot validate <type> against input_schema. Expected dict or <Model> instance.

12. Reasoning

Enable explicit step-by-step reasoning to improve accuracy on hard problems:

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    reasoning=True,
    reasoning_min_steps=2,
    reasoning_max_steps=8,
)
agent.print_response("If a train leaves at 3pm going 60mph...", stream=True)

You can dedicate a separate model to the reasoning phase (often a stronger or cheaper model):

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    reasoning_model=Claude(id="claude-sonnet-4-5"),
    reasoning=True,
)

13. Guardrails, Hooks, and Human-in-the-Loop

Pre and post hooks

Hooks run custom logic around the agent's processing. Use them for validation, logging, redaction, or evaluation:

def redact_pii(run_input, **kwargs):
    # mutate or inspect the input before processing
    ...

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    pre_hooks=[redact_pii],
)

pre_hooks run after the session loads but before the model is called; post_hooks run after output is generated but before it is returned. Hooks may be plain callables, BaseGuardrail subclasses, or BaseEval evaluators.

Guardrails

Subclass BaseGuardrail to enforce policies (e.g. block spam or off-topic requests):

from agno.guardrails import BaseGuardrail

class SpamGuardrail(BaseGuardrail):
    def check(self, run_input, **kwargs):
        if "buy now" in str(run_input).lower():
            raise ValueError("Spam detected")

agent = Agent(model=OpenAIChat(id="gpt-4o"), pre_hooks=[SpamGuardrail()])

Human-in-the-loop and approvals

Agno can pause a run to wait for human confirmation (for example, before a destructive tool call), then resume with continue_run(). This pattern powers approval gates in AgentOS, where the /approvals API surfaces pending actions. See the Admin Guide for the server-side approval workflow.

14. Multi-Agent Teams

A Team has a leader and a list of members (agents or nested teams). The leader coordinates the members according to the team's mode.

from agno.agent import Agent
from agno.team import Team
from agno.models.openai import OpenAIChat

researcher = Agent(name="Researcher", role="Finds facts", model=OpenAIChat(id="gpt-4o"),
                   tools=[DuckDuckGoTools()])
writer = Agent(name="Writer", role="Writes prose", model=OpenAIChat(id="gpt-4o"))

team = Team(
    name="Content Team",
    members=[researcher, writer],
    model=OpenAIChat(id="gpt-4o"),
    instructions="Research the topic, then write a short article.",
)
team.print_response("Write about the James Webb Space Telescope.", stream=True)

Team modes

from agno.team import Team
team = Team(members=[...], mode="route")   # or "coordinate", "broadcast", "tasks"

Useful Team arguments

Teams accept most of the same memory, knowledge, session, and db arguments as agents.

Note

In coordinate mode with persistence, ensure your db is configured so member sessions survive process restarts; otherwise resuming a paused team run may fail to find a member's prior session.

15. Workflows

Workflows give you deterministic orchestration: explicit control flow over agents, teams, and functions. Unlike a team (where the LLM leader decides routing), a workflow's structure is code you define.

Building blocks

Sequential workflow example

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.workflow import Workflow, Step

researcher = Agent(name="Researcher", model=OpenAIChat(id="gpt-4o"), tools=[DuckDuckGoTools()])
writer = Agent(name="Writer", model=OpenAIChat(id="gpt-4o"))

workflow = Workflow(
    name="Article Pipeline",
    steps=[
        Step(name="research", agent=researcher),
        Step(name="write", agent=writer),
    ],
)
workflow.print_response("Write an article about black holes.", stream=True)

Each step receives a StepInput (the prior step's output plus shared context) and returns a StepOutput. You can mix agents, teams, and plain functions as step executors.

Parallel and conditional flow

from agno.workflow import Workflow, Step, Parallel, Condition

workflow = Workflow(
    name="Multi-source research",
    steps=[
        Parallel(
            Step(name="web", agent=web_agent),
            Step(name="news", agent=news_agent),
        ),
        Step(name="synthesize", agent=writer),
    ],
)

CEL expressions

Conditions and routers can use CEL expressions for declarative logic (pip install "agno[cel]"). Validate them with validate_cel_expression().

Tip

Use a Team when you want the model to decide how to delegate; use a Workflow when you need a repeatable, auditable pipeline with explicit branches, loops, and parallelism.

16. Running as a Service: AgentOS

AgentOS turns your agents into a production FastAPI application — 50+ REST endpoints with SSE and WebSocket streaming, plus optional auth, tracing, scheduling, and chat interfaces.

pip install "agno[os]"

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.db.sqlite import SqliteDb
from agno.os import AgentOS

agent = Agent(
    name="Assistant",
    model=OpenAIChat(id="gpt-4o"),
    db=SqliteDb(db_file="agentos.db"),
)

agent_os = AgentOS(agents=[agent])
app = agent_os.get_app()      # a FastAPI app

# Run with: uvicorn main:app --reload --port 7777

uvicorn main:app --port 7777

Visit http://localhost:7777/docs for the interactive OpenAPI explorer.

What AgentOS exposes

Key AgentOS options

Chat interfaces

Expose an agent through a messaging platform:

from agno.os.interfaces.slack import Slack

agent_os = AgentOS(
    agents=[agent],
    interfaces=[Slack(agent=agent)],
)

Available interfaces: Slack, Telegram, WhatsApp, AG-UI, A2A.

Important

AgentOS persistence, auth, scheduling, and deployment are covered in depth in the Admin Guide. This section is the user-facing overview.

17. Deploying with the ag CLI

The separate agno-infra package provides the ag (alias agno) command-line tool for scaffolding and deploying AgentOS projects to Docker and AWS.

pip install "agno-infra"          # or: pip install "agno[infra]"

Commands

All deployment commands live under ag infra:

ag infra create --name my-agentos
cd my-agentos
ag infra up

Note

agno-infra targets Docker and AWS (ECS, load balancers, RDS, S3, and more). Because Agno deploys as a container, you can also run it on any platform that runs containers — Railway, GCP, Fly, etc. See the Admin Guide for deployment architecture.

18. Common Recipes

A research agent with web search and citations

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.tools.exa import ExaTools

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    tools=[ExaTools()],
    instructions=["Always cite sources with URLs.", "Be concise."],
    add_datetime_to_context=True,
    markdown=True,
)
agent.print_response("Summarize recent advances in battery technology.", stream=True)

A persistent chat assistant

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.db.sqlite import SqliteDb

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    db=SqliteDb(db_file="chat.db"),
    session_id="user-sam",
    add_history_to_context=True,
    enable_user_memories=True,
    markdown=True,
)
agent.cli_app()   # interactive REPL

A structured data extractor

from pydantic import BaseModel
from agno.agent import Agent
from agno.models.openai import OpenAIChat

class Invoice(BaseModel):
    vendor: str
    total: float
    due_date: str

agent = Agent(model=OpenAIChat(id="gpt-4o"), output_schema=Invoice)
invoice = agent.run("Vendor: Acme, $1,250 due 2026-07-01").content

A multi-agent team served over HTTP

from agno.os import AgentOS
agent_os = AgentOS(teams=[content_team])
app = agent_os.get_app()
# uvicorn main:app --port 7777

19. Troubleshooting

Error: Invalid model string format: 'gpt-4o'

Cause: A model passed as a string must be "<provider>:<model_id>". Solution: Use "openai:gpt-4o", or pass a model object: OpenAIChat(id="gpt-4o"). Prevention: Prefer model objects in code; reserve strings for config files.

Error: Model provider '<x>' is not supported.

Cause: The provider prefix in your model string isn't recognized. Solution: Check the provider name against the provider reference; install the corresponding extra.

Error: '<package>' not installed. Please install using 'pip install agno[<extra>]'

Cause: You used a tool, model, or backend whose optional dependency isn't installed (e.g. mistralai, PyJWT, filetype). Solution: Install the named extra, e.g. pip install "agno[mistral]" or pip install "agno[os]". Prevention: Install the extras for every provider/tool/db you use up front.

Error: Either agents, teams, workflows, knowledge bases or a database must be provided.

Cause: AgentOS(...) was constructed with nothing to serve. Solution: Pass at least one of agents=, teams=, workflows=, knowledge=, or db=.

Error: Instructions function is async, use 'agent.arun()' instead

Cause: You used an async callable for instructions / system_message / a tool, then called the sync run(). Solution: Use await agent.arun(...) / await agent.aprint_response(...).

Error: At least one JWT verification key or JWKS file is required when validate=True

Cause: JWT auth is enabled in AgentOS but no verification key is configured. Solution: Set JWT_VERIFICATION_KEY or JWT_JWKS_FILE (env vars), or pass verification_keys / jwks_file. See the Admin Guide.

Error: Input required when input_schema is set

Cause: input_schema is configured but no input was passed to run(). Solution: Provide an input matching the schema (a dict or a model instance).

High latency on every agent.run()

Cause: Telemetry currently runs synchronously and can add ~1s per call. Solution: Set telemetry=False on the agent, or globally: export AGNO_TELEMETRY=false.

CPU spins to 100% after MCP setup fails

Cause: A failed MCP toolkit initialization could corrupt the cancel scope in older releases. Solution: Upgrade to the latest Agno; wrap MCPTools(...) setup in try/except and ensure servers are reachable before connecting.

Knowledge base isn't searched

Cause: With a pre-supplied messages array (rather than a single input), the knowledge search tool may not be triggered automatically. Solution: Pass a natural-language query as input, ensure search_knowledge=True, or set add_knowledge_to_context=True to always inject references.

Multi-turn conversation breaks

Cause: Some patch releases have regressed multi-turn handling. Solution: Pin a known-good version, confirm db + add_history_to_context=True are set, and reuse the same session_id across turns.

20. Frequently Asked Questions

Q: Is Agno a hosted service or a library? A library/SDK you run yourself. There is a companion control-plane UI and managed offering, but the framework runs entirely in your own infrastructure.

Q: Do I need an API key? You need credentials for whichever model provider you use (e.g. OPENAI_API_KEY). Agno itself doesn't require an account to run agents locally.

Q: How is a Team different from a Workflow? A Team lets the LLM leader decide how to delegate (dynamic). A Workflow is deterministic code-defined control flow (sequences, loops, branches, parallelism). Use teams for open-ended delegation, workflows for repeatable pipelines.

Q: Can I switch model providers without rewriting my agent? Yes. Swap the model= argument (or the "provider:id" string). The rest of the agent definition is provider-agnostic.

Q: Where is conversation history stored? In the db you attach to the agent (SQLite, PostgreSQL, MySQL, MongoDB, Redis, DynamoDB, and more). Without a db, runs are stateless.

Q: What's the difference between session state and memory? session_state is scoped to one conversation; memory holds durable facts about a user_id recalled across sessions.

Q: How do I disable telemetry? Set telemetry=False on the agent/AgentOS, or export AGNO_TELEMETRY=false.

Q: Can agents call my own functions? Yes — any typed, docstringed Python function passed in tools= becomes a callable tool.

Q: Does Agno support local models? Yes, via Ollama, LM Studio, llama.cpp, and vLLM providers.

Q: How do I serve agents over HTTP? Wrap them in AgentOS(...) and run the returned FastAPI app with uvicorn. See Running as a Service.

Q: How do I add streaming? Pass stream=True to run() / print_response(). For intermediate events (tool calls, reasoning), add stream_events=True.

Q: Can I structure agent output as JSON? Yes — set output_schema to a Pydantic model. The result's .content will be a validated instance.

Q: Which Python versions are supported? 3.7+ per the package metadata; 3.10+ is recommended for the best typing experience.

21. Reference

Import map (public API)

Note

Agno's top-level agno package exposes only agno.__version__. Public classes are imported from their submodules as shown above.

Common environment variables

Team modes

Agent run methods

Further reading

• Admin Guide — architecture, the monorepo layout, AgentOS deployment, JWT/RBAC, OpenTelemetry, scheduling, storage backends, security hardening, and the complete configuration reference.
• Official docs: https://docs.agno.com