From Zero to Agent Hero: Getting Started with Agno Agents, uv, and a Dash of RAG Magic

Picture this: it’s 2026, and you’re ready to unleash an AI sidekick that doesn’t just chat, but searches the web, remembers that you love spicy Thai food, and dives into PDFs faster than you can say “where’s my coffee?” Enter Agno, an open-source Python framework for building AI agents. Paired with uv, the Rust-powered package manager that leaves pip in the dust (think 10-100x faster), you’re about to embark on a coding adventure that’s equal parts thrilling and hilarious.

This guide is a full refresh for Agno 2.x — as of August 2026 the current release is 2.8.6. If you’ve seen older Agno tutorials (including my original March 2025 version of this very article), brace yourself: the API got a major overhaul in v2.0. Old favorites like SqliteAgentStorage, PDFUrlKnowledgeBase, and Agent(team=[...]) are gone, replaced by a cleaner, more powerful toolkit. Everything below is verified against the real thing, so the code will just work.

We’ll turbocharge your setup with uv, then craft an Agno agent that evolves from a chatty newbie to a memory-savvy, Retrieval-Augmented Generation (RAG) maestro, powered by LanceDB and DuckDuckGo. We’ll cap it off with a two-agent dream team that collaborates like peanut butter and jelly—or better yet, chicken and galangal. With code snippets, witty asides, and troubleshooting tips, you’ll be laughing your way to AI mastery.

Getting Started with Agno Agents

Step 1: Turbocharge Your Setup with uv—Python Management at Warp Speed

Before we unleash Agno’s powers, we need a lightning-fast foundation. That’s where uv comes in—a package manager from the Astral crew (the same folks behind ruff) that’s so quick, it’ll have you wondering why you ever tolerated pip’s leisurely pace. Let’s get it rolling!

You can check more on how you can get started with uv

Installing uv

For macOS/Linux:

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

For Windows (PowerShell):

irm https://astral.sh/uv/install.ps1 | iex

Check it’s alive:

uv --version  # Expect "uv 0.9" or newer

Initializing a Project

Time to kick off your Agno adventure:

uv init agno-adventure
cd agno-adventure

This whips up a tidy project structure: pyproject.toml for dependencies, .python-version, main.py to code in, a README.md, and—new in recent uv versions—a fresh git repo. Lock in Python 3.12 for consistency:

uv python pin 3.12

Setting Up the Environment

Now, create a virtual environment faster than you can blink:

uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

Load up the essentials for our AI escapade. Note the extras — Agno splits its integrations into opt-in extras, so you only install what you need:

uv add "agno[openai,lancedb,pdf,ddg,sqlite]" typer rich

That single line pulls in:

• agno — the framework itself, plus:
  • openai — the OpenAI model provider (GPT models are Agno’s default)
  • lancedb — our vector database for RAG later
  • pdf — the PDF reader (pypdf under the hood)
  • ddg — DuckDuckGo web search (via the modern ddgs package, which replaced the old duckduckgo-search library)
  • sqlite — SQLite session storage (sqlalchemy + friends)
• typer and rich — for the snazzy interactive CLI we’ll build in Step 5

Agno needs an OpenAI API key to flex its muscles, so set it up:

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

Pro Tip: Keep your keys in a .env file. Bonus: uv run auto-loads .env from your project directory, so no extra tooling needed. Just add OPENAI_API_KEY=your-key-here to .env and run scripts with uv run python main.py.

Why uv? It’s not just fast—it’s a one-stop shop replacing pip, venv, and more, with a sleek workflow that saves you from dependency nightmares. Think of it as the turbo engine powering your Agno rocket.

Step 2: Your First Agno Agent—Simple, Yet Chatty

Let’s meet Agno, the star of our show. It’s an open-source Python framework that makes building AI agents as easy as ordering takeout—but way more fun. Our first agent? A cheerful chatterbox ready to brighten your day.

The Code

Edit main.py:

from agno.agent import Agent

agent = Agent(
    model="openai:gpt-5.5",
    description="You're a cheerful AI pal who loves a good chat!",
    markdown=True
)

agent.print_response("Hey! What's cooking today?", stream=True)

Run it:

uv run python main.py

How It Works

• Agent: The heart of Agno, this class is your agent’s command center, letting you define its personality and powers.
• model="openai:gpt-5.5": Agno 2.x uses model string references like "provider:model-id". This is the modern, recommended way to pick a model — the string resolves to the right model class under the hood (for OpenAI it maps to OpenAIResponses). You can swap in any provider: "anthropic:claude-sonnet-4-5", "google:gemini-3-pro", "ollama:llama4", you name it. The older class-based style (from agno.models.openai import OpenAIChat) still imports for backwards compatibility, but string refs are cleaner and easier to switch.
• description: Sets the vibe. Here, we’ve got a peppy pal who’s all about good vibes.
• markdown=True: Spices up responses with formatting—because plain text is so last decade.
• print_response: Streams the reply in real-time, like watching your agent think out loud.

You’ll get a response like, “Hey there! Just here to spice up your day—what’s on the menu?” It’s basic, but it’s alive!

More About Agno

Agno’s lightweight design means it’s nimble yet powerful, perfect for crafting agents that scale from simple chats to complex tasks. Unlike heavier frameworks, it’s built for speed and flexibility, letting you add features like tools and memory without breaking a sweat. And since v2.0, Agno is more than a library: it ships with AgentOS, a runtime that serves your agents as REST APIs with tracing, session isolation, and RBAC — we’ll touch on that in the conclusion.

Troubleshooting

• “ModuleNotFoundError”: Forgot a package? Run uv add "agno[openai]" and try again.
• Silent Agent: Check your OPENAI_API_KEY. No key, no chat—it’s like forgetting to plug in your coffee maker.

Step 3: Adding DuckDuckGo Tools—Your Web-Surfing Sidekick

Our agent’s charming but clueless about the world. Let’s hook it up with DuckDuckGo tools so it can surf the web like a pro.

The Code

Update main.py:

from agno.agent import Agent
from agno.tools.duckduckgo import DuckDuckGoTools

agent = Agent(
    model="openai:gpt-5.5",
    description="You're a web-savvy AI explorer!",
    tools=[DuckDuckGoTools()],
    markdown=True
)

agent.print_response("What's the buzz in New York right now?", stream=True)

Run it:

uv run python main.py

How It Works

• DuckDuckGoTools: Equips your agent with a web search superpower. It decides when to use it based on the question—smart, right?
• Tool calls in the terminal: The old show_tool_calls=True parameter is gone in Agno 2.x — but you don’t need it. When you stream a response, the CLI printer shows tool calls as they happen, like a behind-the-scenes director’s cut. For full trace-level detail, add debug_mode=True to the Agent or run the agent through AgentOS and inspect the trace UI.
• Output: Expect something like, “Calling DuckDuckGo… Here’s the latest from NYC!” It’s now a worldly conversationalist.

Agno’s Tool Power

Agno’s tool system is modular brilliance. DuckDuckGoTools is just one option—Agno supports a growing toolbox you can mix and match to suit your needs, from APIs to custom Python functions (just pass any function in tools=[...]). It’s like giving your agent a utility belt!

Troubleshooting

• No Web Results: Ensure the ddg extra is in your arsenal—run uv add "agno[ddg]".
• Stuck?: Rate limits might be the culprit. Take a breather and retry. Add debug_mode=True to the Agent for a deeper look at what’s tripping it up.

Step 4: Memory That Sticks—From Forgetful to Faithful

Our agent’s got charisma but forgets everything the moment you blink. Let’s give it a memory upgrade with Agno’s SQLite-backed storage, turning it into a loyal companion.

The Code

Create memory_agent.py:

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from rich.pretty import pprint

agent = Agent(
    model="openai:gpt-5.5",
    description="You're an AI with a memory like an elephant!",
    db=SqliteDb(db_file="tmp/agent_storage.db"),
    add_history_to_context=True,
    num_history_runs=3,
    update_memory_on_run=True,
    session_id="my_chat_session",
    markdown=True
)

agent.print_response("I love spicy Thai food. What's your favorite cuisine?")
agent.print_response("What did I just say I love?")

# Inspect what the agent remembers
pprint(agent.get_session_messages(session_id="my_chat_session"))
pprint(agent.get_user_memories())

Run it:

uv run python memory_agent.py

How It Works

The memory API got a big cleanup in Agno 2.x — the old SqliteAgentStorage class and the whole agno.storage package are gone. Here’s the new model:

• db=SqliteDb(db_file=...): Stores sessions, chat history, and extracted memories in a SQLite database. No extra service needed.
• add_history_to_context=True + num_history_runs=3: Feeds the last few runs (each with all its messages) into the prompt, giving conversational context. (These replaced the old add_history_to_messages / num_history_responses.)
• update_memory_on_run=True: Enables automatic memory — after each run, Agno extracts durable facts about the user (preferences, goals) and stores them keyed by user_id. The alternative is agentic memory (enable_agentic_memory=True), where the model itself decides when to inspect, create, or update memories during a run. Pick one mode per agent.
• session_id: Links interactions under one session—use the same ID, and it’s like picking up where you left off.
• get_session_messages() / get_user_memories(): The v2 way to peek inside — chat history and extracted facts, respectively. (The old agent.memory.messages attribute is no more.)

Ask about Thai food, then test its recall. It’ll proudly declare, “You love spicy Thai food!” Memory unlocked!

Agno’s Memory Magic

Agno separates three concepts cleanly:

• Memory: Extracted facts about a user, scoped by user_id, shared across sessions.
• Chat history: Messages and tool calls from previous runs, scoped by session_id, for conversational continuity.
• Session state: Application data (carts, task lists, counters) managed by your code or tools.

This flexibility makes Agno ideal for agents that need to learn and grow with you.

Troubleshooting

• Amnesia: Same session_id? Check tmp/ exists (create it with mkdir tmp if needed).
• No Storage: Run uv add "agno[sqlite]" — it’s the backbone of SQLite storage.

Pro Tip: For big projects, swap SqliteDb for PostgresDb from agno.db.postgres via uv add "agno[postgres]". More power, same simplicity!

---

Step 5: RAG with LanceDB—Knowledge Is Your Superpower

Time to make your agent a Thai cuisine expert with RAG (Retrieval-Augmented Generation). Using LanceDB, it’ll pull recipes from PDFs and back them up with web smarts—interactive style!

The Code

Create rag_agent.py:

import typer
from rich.prompt import Prompt

from agno.agent import Agent
from agno.knowledge.knowledge import Knowledge
from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.knowledge.reader.pdf_reader import PDFReader
from agno.vectordb.lancedb import LanceDb
from agno.vectordb.search import SearchType
from agno.tools.duckduckgo import DuckDuckGoTools

# LanceDB Vector DB
vector_db = LanceDb(
    table_name="recipes",
    uri="tmp/lancedb",
    search_type=SearchType.hybrid,
    embedder=OpenAIEmbedder(id="text-embedding-3-small"),
)

# Knowledge Base
knowledge = Knowledge(
    vector_db=vector_db,
    readers=[PDFReader()],
)

def lancedb_agent(user: str = "user"):
    agent = Agent(
        model="openai:gpt-5.5",
        description="You're a Thai cuisine expert with web backup!",
        user_id=user,
        knowledge=knowledge,
        search_knowledge=True,
        tools=[DuckDuckGoTools()],
        instructions=[
            "Search the knowledge base for Thai recipes first.",
            "Use DuckDuckGo if more info is needed."
        ],
        markdown=True
    )

    print(f"Session ID: {agent.session_id}\n")

    while True:
        message = Prompt.ask(f"[bold] :sunglasses: {user} [/bold]")
        if message in ("exit", "bye"):
            break
        agent.print_response(message, stream=True)

if __name__ == "__main__":
    # Load the PDF into the knowledge base (idempotent - safe to run every time)
    knowledge.insert(url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf")
    typer.run(lancedb_agent)

Run it:

uv run python rag_agent.py

How It Works

The knowledge API was completely restructured in Agno 2.x — PDFUrlKnowledgeBase is gone. Here’s the new shape:

• Knowledge: The single knowledge-base class (from agno.knowledge.knowledge). It combines a vector DB, optional readers, and content ingestion.
• readers=[PDFReader()]: Tells the knowledge base how to parse PDFs (the pdf extra installs pypdf under the hood). Readers now live under agno.knowledge.reader — there are ready-made ones for PDF, DOCX, CSV, Markdown, Excel, YouTube, Wikipedia, and more.
• knowledge.insert(url=...): The v2 replacement for knowledge_base.load(recreate=True) — downloads the file, parses it with the matching reader, chunks it, and embeds it into the vector DB. It’s idempotent by default (upsert=True), so re-running the script won’t duplicate content. You can also insert by local path=, raw text_content=, or even topics= for query-based loading.
• LanceDb + SearchType.hybrid: Still the same great combo. Hybrid blends keyword and semantic searches for max accuracy — and since LanceDB moved to native full-text search, you no longer need the tantivy package.
• OpenAIEmbedder: Moved in v2 — it now lives at agno.knowledge.embedder.openai. Same idea: converts text to embeddings using text-embedding-3-small.
• search_knowledge=True: The v2 flag that lets the agent search its knowledge base during a run (agentic RAG — the agent decides when to retrieve).
• typer/Prompt: Keeps the chat going until you say “bye”—perfect for recipe hunting!
• Output: Ask, “How do I make chicken and galangal coconut soup?” It’ll dig into the PDF, then surf the web if needed.

Agno’s RAG Edge

RAG combines retrieval (from LanceDB) with generation (via GPT), making your agent a knowledge ninja. Agno supports 19 vector databases — from local options like LanceDB and ChromaDB to managed services like Pinecone and Weaviate — and lets you swap them by changing a few lines.

Troubleshooting

• PDF Won’t Load: Verify the URL and run uv add "agno[pdf,lancedb]".
• Embedding Errors: OpenAIEmbedder needs the same OPENAI_API_KEY as the chat model — check your .env.
• No Chat Prompt: Add uv add typer rich for the interactive goodies.
• Duplicate Content: Don’t worry — insert() upserts by default, so re-running is safe.

Pro Tip: Add more sources to knowledge.insert() — cookbooks, travel guides, markdown docs, whatever—to create a custom knowledge empire.

Step 6: Team of Two—Chef and Researcher Duo

Why stop at one agent when you can have a dynamic duo? Let’s pair a Thai chef with a web researcher for a collab that’s pure magic.

The Code

Create team_agent.py:

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.knowledge.knowledge import Knowledge
from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.knowledge.reader.pdf_reader import PDFReader
from agno.vectordb.lancedb import LanceDb
from agno.vectordb.search import SearchType
from agno.tools.duckduckgo import DuckDuckGoTools
from agno.team import Team, TeamMode

# Shared knowledge base
vector_db = LanceDb(
    table_name="recipes",
    uri="tmp/lancedb",
    search_type=SearchType.hybrid,
    embedder=OpenAIEmbedder(id="text-embedding-3-small"),
)
knowledge = Knowledge(vector_db=vector_db, readers=[PDFReader()])
knowledge.insert(url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf")

# Chef Agent
chef = Agent(
    name="ThaiChef",
    role="Thai cuisine expert",
    model="openai:gpt-5.5",
    knowledge=knowledge,
    search_knowledge=True,
    instructions=["Provide detailed Thai recipes from the knowledge base."],
    markdown=True
)

# Researcher Agent
researcher = Agent(
    name="WebResearcher",
    role="Web info gatherer",
    model="openai:gpt-5.5",
    tools=[DuckDuckGoTools()],
    instructions=["Search the web for supplementary info when asked."],
    markdown=True
)

# Team Leader
team = Team(
    name="Thai Team",
    members=[chef, researcher],
    mode=TeamMode.coordinate,
    db=SqliteDb(db_file="tmp/team_storage.db"),
    instructions=[
        "Ask ThaiChef for recipes first.",
        "If more context is needed, consult WebResearcher.",
        "Blend their inputs into a cohesive answer."
    ],
    markdown=True
)

team.print_response("Tell me about Thai chicken soup and its cultural significance.", stream=True)

Run it:

uv run python team_agent.py

How It Works

Multi-agent collaboration got a dedicated class in Agno 2.x — Agent(team=[...]) is gone. Say hello to agno.team.Team:

• Team(members=[...]): The team leader coordinates its member agents, delegating tasks based on their roles and synthesizing results. Members can even be nested teams.
• TeamMode: Makes collaboration styles explicit — coordinate (default; decompose work, delegate, synthesize), route (send to a single specialist), broadcast (same task to all members), or tasks (task-list loop until done).
• ThaiChef: Recipe guru, pulling from the PDF via LanceDB — OpenAIEmbedder produces the embeddings, search_knowledge=True lets it retrieve during runs.
• WebResearcher: Web sleuth, digging up cultural context with DuckDuckGo.
• db=SqliteDb(...): Keeps the team’s sessions and history sharp across runs.
• Output: You’ll get a recipe and a story—like, “This soup’s a Thai staple, tied to ancient herbal traditions!”

Agno’s Team Spirit

Teams are a game-changer. Each member has a role, tools, and knowledge, while the leader delegates like a pro. It’s lightweight yet robust, designed to scale without bogging down—perfect for complex tasks.

Troubleshooting

• Team Mute: Add debug_mode=True to the Team to spy on the chatter.
• Storage Snag: Ensure the SqliteDb import is there and tmp/ exists.
• Slow Start: knowledge.insert() upserts by default, so you can move the insert out of the hot path (or guard it with a file check) once the PDF is loaded.

Pro Tip: Add a third agent—like a spice specialist—to turn your duo into a trio of culinary geniuses.

Conclusion: Your Agno Journey Takes Flight!

You’ve just gone from zero to AI hero! With uv’s blazing speed, you set up a pro environment in seconds. Then, with Agno 2.x, you built an agent that chats, surfs, remembers with SQLite, masters RAG with LanceDB, and teams up for epic results. This is Python in 2026—fast, fun, and downright fierce.

Key Wins:

• uv: Your setup’s new best friend—say goodbye to sluggish installs.
• Agno: Lightweight, modular, and speedy, with memory, tools, and RAG that make your agents brilliant.
• Teamwork: Multi-agent collab that tackles big questions with ease.

What’s Next? Two directions worth chasing:

1. Dive into Agno’s extras — multimodal inputs (images, audio, video), workflows (deterministic agent pipelines), and 100+ pre-built toolkits.
2. Ship it with AgentOS — Agno’s runtime turns your agent into a production REST API with streaming, tracing, session isolation, and JWT-based RBAC. Run it locally with uv pip install "agno[os]", serve your agent with AgentOS(agents=[...]), and manage it from the UI at os.agno.com.

Oh, and one more thing—go whip up that Thai chicken soup your agent’s been raving about. You’ve got the code, the skills, and the laughs—go conquer the AI universe!