How to Use Agno: The Beginner's Guide to Building AI Agents

CodexFuse Team · 2026-11-01T16:19:43.955Z · 14 min read

Build your first AI agent with Agno: install the SDK, add tools and memory, swap models freely, and avoid the v2/v3 API traps. Tested against the current SDK.

What Is Agno, Exactly?

Agno is an open-source Python framework for building AI agents — programs that take a goal, call tools, remember context, and return answers. This guide walks through how to use Agno from a blank folder to your first running agent, tested against the current SDK (version 3.1.12, checked October 29, 2026), so the code below actually runs instead of dying on a renamed import.

Agno used to be a niche library with a few thousand users. It is now one of the most-starred agent frameworks on GitHub — 43,003 stars and 6,223 forks as of this week — and its headline trick is simplicity: a working agent is about ten lines of Python, not a framework ceremony. The mental model is one sentence: an Agno Agent combines a model, tools, and memory, and the framework handles the loop between them.

The Mental Model: Agent + Model + Tools + Memory

Every Agno agent is the same four-part deal, and every section of this guide maps to one part. The model is the LLM that does the reasoning — OpenAI, Anthropic, Google, or Groq. The tools are typed Python functions the agent can call when the model decides it needs real-world data. The memory is how the agent stops being a goldfish: conversation history and persistent facts about the user, stored in a database.

The Agent object glues the three together. As the Agno docs put it, an agent "builds context for a model, processes model responses, executes requested tools, and returns a RunOutput." You configure the pieces; the framework runs the loop. Tool access can also come through external servers using the MCP protocol, which this guide covers as the advanced arc — if the term is new to you, the MCP explainer page is worth five minutes first.

Install Agno Without Breaking Your Python

Agno needs Python 3.9 or newer, and the current official quickstart assumes uv, the fast Python package manager. Install uv once, then scaffold a bare project:

curl -LsSf https://astral.sh/uv/install.sh | sh

uv init --bare --python 3.14
cd your-project-folder
uv add "agno[os,sqlite]" openai

The agno[os,sqlite] extra pulls in AgentOS support and SQLite storage; openai is the model provider package. Agno publishes extras for other providers too — anthropic, groq, google, plus toolkits like ddg (DuckDuckGo search) and mcp — install only the ones your agent needs. If you are new to Python environments, the GitHub beginner guide covers the workflow this pattern assumes.

One rule before you write a line of agent code: put API keys in environment variables, never in your source files. Agno's SDK reads provider keys from the environment automatically:

export OPENAI_API_KEY="sk-your-key-here"

Add that line to your shell profile so it survives restarts. Keys checked into a repo are the single most common way first agents get abused, and this is the one habit that prevents it.

Your First Agno Agent in 6 Steps

This is the fastest complete arc: install, key, agent, run, serve. Follow it verbatim and you will have a named agent with memory and a web interface in under ten minutes.

1. Install uv from the command above if it is not on your machine yet.
2. Scaffold the project with uv init --bare --python 3.14 and add the dependencies: uv add "agno[os,sqlite]" openai.
3. Export your API key — export OPENAI_API_KEY="sk-your-key-here" — and keep it out of your code.
4. Write the agent file. Create personal_agent.py with the code below. The model can be a plain string like "openai:gpt-5.6" — Agno resolves provider and model from the prefix.
5. Run it with uv run personal_agent.py. You should see the agent answer your test question in the terminal.
6. Serve it. Add the two serve lines at the bottom of the file (shown below) and re-run — your agent is now a web service on http://localhost:7777.

from agno.agent import Agent
from agno.db.sqlite import SqliteDb

db = SqliteDb(db_file="personal_agent.db")

agent = Agent(
    name="Pip",
    model="openai:gpt-5.6",
    db=db,
    instructions=["You are a helpful assistant."],
    add_history_to_context=True,
    add_datetime_to_context=True,
)

agent.print_response("What is the capital of France?", stream=True)

That is a complete first agent: a named agent (Pip), a model, a SQLite database, two context flags, and one run call. print_response() is the terminal-friendly way to run — it streams the answer and returns a RunOutput you can inspect. When you want the answer as data instead of console output, use result = agent.run("...") and read result.content; the async versions are arun() and aprint_response().

The Tools Lesson: Docstrings Are the Schema

An agent without tools can only talk. Give it tools and it can do. The good news: an Agno tool is just a typed Python function with a docstring — the docstring is literally what the model reads to decide when to call it. Write the function well and the agent knows what it does.

def get_weather(city: str) -> str:
    """Return the current weather for a city like Paris or Tokyo."""
    # call a real weather API here
    return f"{city} is 18C and sunny."

agent = Agent(
    model="openai:gpt-5.6",
    tools=[get_weather],
)

Ask this agent "what is the weather in Paris" and the model reads the docstring, calls get_weather("Paris"), and folds the result into its answer. Type hints matter — they tell the model exactly what arguments the function expects.

Agno also ships ready-made toolkits so you do not write everything yourself. The current docs list DuckDuckGo search tools, web-search tools for other backends, HackerNews tools (from agno.tools.hackernews import HackerNewsTools), and dozens more, each imported as a class and dropped into the tools list. The rule of thumb: custom functions for your own business logic, bundled toolkits for everything standard.

The advanced arc for tools is MCP: instead of writing functions, your agent connects to an external MCP server and discovers its tools at runtime. Keep this as a later section of your learning, not the spine — get local tools working first, then bridge to MCP servers once the agent's behavior is predictable.

The Memory Lesson: Your Agent Forgets Everything Unless You Tell It

This is the lesson every beginner learns the hard way: an Agno agent is stateless by default. Start a new run and it remembers nothing about the last one — not the user's name, not the previous question, nothing. Memory is opt-in, and it lives in the database you pass with db=.

There are two kinds of memory, and they solve different problems. Session history is short-term: the last few exchanges in this conversation. User memory is long-term: persistent facts about the user that survive across sessions. Here is what each one looks like:

from agno.db.sqlite import SqliteDb

db = SqliteDb(db_file="personal_agent.db")

agent = Agent(
    model="openai:gpt-5.6",
    db=db,
    session_id="chat_history",
    add_history_to_context=True,
    num_history_runs=2,
)

Two details that matter. First, without a database file, SQLite storage just creates ./agno.db in the working directory — convenient for experiments, so name your db_file explicitly for anything real. Second, the default session keeps the last three runs; num_history_runs tunes that. For persistent user facts, the current recipe is a MemoryManager attached to the same database, enabled with enable_agentic_memory=True — the manager quietly extracts facts from conversations, and update_memory_on_run=True makes the extraction run concurrently instead of after each response.

The Model-Swap Lesson: One Agent, Any Provider

Agno is model-agnostic: the agent code does not care which provider answers. The quickstart passes a string — model="openai:gpt-5.6" — and Agno resolves the provider from the prefix. When you need provider-specific settings, use the model classes instead:

The swap itself is one line: change the model= argument and keep the tools, memory, and instructions exactly as they are. That is the payoff of the whole design — your agent logic is provider-independent, so a cheaper or faster model is a one-line experiment, not a rewrite. Two freshness notes: the SDK's own default model moved to gpt-5.6-terra in the 3.0.7 changelog, and old model ids you see in dated tutorials (like gemini-2.0-flash) are stale — always copy the id from the provider's current docs, not from a year-old blog post.

The v2/v3 API Trap: Why Old Snippets Break

Agno moved fast: v2 landed with breaking renames, and v3 (~September 2026) restructured storage and teams. Most tutorials you will find through search were written for v1, and their snippets fail on the current SDK. I verified the current API against the official docs while writing this guide — here is the trap list so you do not have to discover it by error message.

Storage and memory became one database. v2 removed the storage and memory constructor arguments from Agent, Team, and Workflow, along with the old AgentMemory and knowledge classes. Everything is now a single db= argument — SqliteDb for local work, Postgres variants for production. If a snippet passes storage= or memory= to Agent(), it is a v1 snippet.

Reasoning flags moved. The constructor arguments reasoning=True, reasoning_min_steps, and reasoning_max_steps are removed — native reasoning is now configured through a reasoning_model instead. Similarly, show_tool_calls appears in old PyPI examples and dated guides but is absent from every current docs page; do not treat it as a current parameter.

MCP got stricter in v3. The MultiMCPTools class and its partial-failure option are gone — create one MCPTools instance per server. And v3 requires a one-time database migration after upgrading and before serving traffic (MigrationManager(db).up(), or POST /databases/all/migrate), because runs moved into a dedicated agno_runs table. Skip the migration and v3 will not serve your old data.

From One Agent to a Team

When one agent accumulates too many tools or too many responsibilities, Agno's answer is a Team: several agents coordinated by a lead. The constructor takes members= — not agents=, a detail that trips people copying v1 code:

from agno.agent import Agent
from agno.tools.websearch import WebSearchTools
from agno.team import Team, TeamMode

web_agent = Agent(name="Searcher", model="openai:gpt-5.6", tools=[WebSearchTools()])
analyst = Agent(name="Analyst", model="openai:gpt-5.6")

team = Team(members=[web_agent, analyst], mode=TeamMode.coordinate)
team.print_response("Summarize today's AI funding news.")

Teams run in modes: coordinate (the default — the lead delegates), route (one member handles the task), broadcast (all members work it), and tasks (structured task distribution). Teams run with the same run() / print_response() interface as single agents. Think of the team as graduation, not the starting point — build one reliable agent first, then split it when the tool list or the scope gets unwieldy.

AgentOS: Turning the Agent Into a Service

So far everything runs as a script. AgentOS is Agno's runtime for serving agents as production services: a stateless, session-scoped FastAPI backend with a built-in API and MCP endpoint, handling authentication, role-based access, run resume and replay, human approvals, scheduling, and durable execution. Two lines in your agent file switch from script to service:

agent_os.serve(app="personal_agent:app", reload=True)

The quickstart serves at http://localhost:7777, where a local control plane connects for free. The framework and the runtime are open source (Apache 2.0) and free at any scale on your own machine or VPC — Agno's own pricing page states there are no per-event, per-token, or egress fees, and that the company never holds a copy of your data.

Self-hosting that service is a packaging job, not an Agno problem: wrap the FastAPI app in a container and it runs anywhere. If containers are new to you, the Docker beginner guide is the natural next read after this one. Paid tiers only appear when you use Agno's managed control plane and cloud:

The takeaway for pricing questions: building and self-hosting agents costs you nothing beyond your model provider's API bill. The $150/month Pro tier is for the managed control plane — team seats, roles, and live connections — not for the framework itself.

Agno vs LangChain vs CrewAI: Drawing the Lines

Three frameworks, three lanes — they are different tools for different jobs, not rivals to pick between on vibes:

If you are choosing between the first two, the LangChain beginner guide lays out that framework's model so you can compare concretely. If your interest is terminal-based coding agents rather than Python-built ones, the OpenCode beginner guide covers that lane — a different animal from what this guide builds.

7 Beginner Mistakes That Break First Agents

Every one of these comes from a real support pattern. Read the list before you debug, not after:

Sources

Every fact in this guide was verified against a page fetched while writing it — no borrowed statistics, no guessed APIs:

• Agno quickstart (install, first agent, serve) — https://docs.agno.com/quickstart
• What are Agents (Agent definition) — https://docs.agno.com/agents/introduction
• Agent tools (custom tools, toolkits) — https://docs.agno.com/tools/agent
• Agent history and context (add_history_to_context, num_history_runs) — https://docs.agno.com/history/agent/overview
• MemoryManager example (agentic user memory) — https://docs.agno.com/examples/basics/agent-with-memory
• Teams overview (Team, TeamMode, members=) — https://docs.agno.com/teams/overview
• SqliteDb reference — https://docs.agno.com/reference/storage/sqlite
• v2 changelog (removed params) — https://docs.agno.com/other/v2-changelog
• Database migrations (v3 migration) — https://docs.agno.com/other/database-migrations
• Reasoning agents (reasoning_model) — https://docs.agno.com/reasoning/reasoning-agents
• Pricing (Free/Pro/Enterprise) — https://www.agno.com/pricing
• What actually breaks agents in production (v3 notes) — https://www.agno.com/blog/what-actually-breaks-agents-in-production
• PyPI agno (version 3.1.12, Python requirement, extras) — https://pypi.org/project/agno/
• GitHub agno-agi/agno (43,003 stars, Apache 2.0) — https://github.com/agno-agi/agno
• GroqDocs Agno guide (Groq model class) — https://console.groq.com/docs/agno
• aiHola beginner guide (field context) — https://aihola.com/article/build-ai-agents-agno-framework-tutorial
• Bitdoze Agno MCP/Context7 arc (field context) — https://www.bitdoze.com/agno-mcp-tools-context7/

Frequently Asked Questions

Is Agno free to use?

Yes. The framework and the AgentOS runtime are open source under Apache 2.0 and free at any scale, including self-hosting. Paid plans ($150/month Pro and up) only apply to Agno's managed control plane — team seats, roles, and live connections — not to building or running agents yourself. Your only real cost is the model provider's API bill.

How is Agno different from LangChain?

Agno is a lightweight, code-first agent framework: one Agent with a model, tools, and memory, servable via AgentOS. LangChain is a broader ecosystem built around chains, RAG pipelines, and a deep integration catalog. They are different lanes — pick Agno when you want a capable agent in a few lines of Python that you fully own.

Do I need to know how to code to use Agno?

Yes, basic Python. Agno is a developer framework, not a no-code tool: you install it with uv or pip, write an agent in a Python file, and run it. If you can write a function and set an environment variable, you have everything the first six steps require.

Why does my agent forget everything between runs?

Because Agno agents are stateless by default — memory is opt-in. Pass a database with db=SqliteDb(...) and set add_history_to_context=True for session history, or attach a MemoryManager with enable_agentic_memory=True for persistent user facts. Without either, each run starts from a blank slate by design.

Will old Agno tutorials still work?

Usually not without edits. v2 removed the storage and memory constructor params (replaced by db), moved reasoning flags to reasoning_model, and dropped show_tool_calls; v3 requires a database migration and one MCPTools instance per server. Prefer the official docs and guides verified against v3 over dated third-party tutorials.