--- title: "From Zero to Agent Hero: Getting Started with Agno Agents, uv, and a Dash of RAG Magic" description: "Learn how to create powerful AI agents with Agno 2.x in minutes! This beginner-friendly guide walks you through setup, tools, memory, RAG, and multi-agent teams using uv" date: 2025-03-14 categories: ["ai"] tags: ["ai-agents","agno","uv"] --- 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](https://www.agno.com), 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. This article was originally published in March 2025 against Agno 1.x. It has been rewritten and verified against **Agno 2.8.6** (July 2026). The embedded video below shows the older API in action — the code in this guide is current. ## **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](https://www.bitdoze.com/uv-get-start/) #### **Installing uv** For macOS/Linux: ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` For Windows (PowerShell): ```powershell irm https://astral.sh/uv/install.ps1 | iex ``` Check it’s alive: ```bash uv --version # Expect "uv 0.9" or newer ``` #### **Initializing a Project** Time to kick off your Agno adventure: ```bash 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: ```bash uv python pin 3.12 ``` #### **Setting Up the Environment** Now, create a virtual environment faster than you can blink: ```bash 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: ```bash 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: ```bash 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`: ```python 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: ```bash 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`: ```python 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: ```bash 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`: ```python 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: ```bash 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`: ```python 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: ```bash 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`: ```python 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: ```bash 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 `role`s 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](https://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!