Chapter 2 · Environment Setup and Your First Agent

Learning objectives: Set up a reusable development environment, run through your first DeepSeek-connected Agent, and learn to troubleshoot the three most common connection errors.

2.1 Installing Agno

Always develop in a virtual environment to avoid polluting your system Python:

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -U agno python-dotenv

Verify installation:

python -c "import agno; print(agno.__version__)"
# 3.0.x (the current major version when this tutorial was written is 3.x)

Version note

Agno has had many breaking changes since 2.x (e.g., the storage class migrated from agno.storage.sqlite.SqliteStorage to agno.db.sqlite.SqliteDb). Version 3.x continues and consolidates this unified API — all usage covered in this course applies to 3.x. Many tutorials online are based on 1.x; please refer to this course and the official documentation.

2.2 Managing API Keys with .env

Never hard-code keys in your code. Create a .env file at the project root:

DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx

Then create .gitignore to exclude it from version control. Load it in code with python-dotenv:

# load_env.py
import os
from dotenv import load_dotenv

load_dotenv()  # Read .env from the current directory and inject env vars

key = os.getenv("DEEPSEEK_API_KEY")
print("Key loaded: " + key[:6] + "..." if key else "DEEPSEEK_API_KEY not found!")

2.3 Your First Agent: Step-by-Step Breakdown

# agent_01.py —— Your first Agno Agent
import os
from dotenv import load_dotenv
from agno.agent import Agent
from agno.models.openai import OpenAIChat

load_dotenv()

agent = Agent(
    model=OpenAIChat(
        id="deepseek-chat",                              # Model ID defined by the third-party provider
        api_key=os.getenv("DEEPSEEK_API_KEY"),           # Read secret from env var
        base_url="https://api.deepseek.com/v1",          # OpenAI-compatible endpoint
    ),
    instructions=["Answer concisely in Chinese", "Say explicitly when unsure"],
    markdown=True,
)

agent.print_response("Introduce AI Agents in one sentence")

Run python agent_01.py and you'll see DeepSeek's reply printed out. Understanding each parameter:

• id: The model name, as defined by the third-party provider (DeepSeek also offers a reasoning model deepseek-reasoner);
• base_url: The compatible endpoint address. Switch to OpenRouter, Tongyi, Kimi, etc. by changing just this line;
• instructions: A list of behavior directives; Agno assembles them into the system message;
• markdown=True: Renders output as Markdown, making tables and code blocks more readable in the terminal.

If you don't want to remember base_url, you can also use Agno's generic class OpenAILike (at agno.models.openai.like) — parameters are identical.

2.4 Troubleshooting Common Connection Errors

Ninety percent of beginner errors fall into these three categories:

# debug_connection.py —— Reproducing the three typical errors
import os
from agno.agent import Agent
from agno.models.openai import OpenAIChat

def make_agent(base_url):
    return Agent(model=OpenAIChat(
        id="deepseek-chat",
        api_key=os.getenv("DEEPSEEK_API_KEY"),
        base_url=base_url,
    ))

# Error 1: 401 Unauthorized → Key not loaded or typo
# Check: is os.getenv("DEEPSEEK_API_KEY") None?

# Error 2: 404 Not Found → base_url has extra or missing path segment
# DeepSeek's correct form ends with /v1; writing https://api.deepseek.com will 404

# Error 3: Model not found → id doesn't match the provider's name
# For example, mistyping "deepseek-chat" as "deepseek_v3"

try:
    make_agent("https://api.deepseek.com/v1").run("ping")
    print("Connection successful")
except Exception as e:
    print("Failure reason:", e)

Troubleshooting mantra: check Key first (401), then URL (404), then model name (400).

2.5 Making Your First Agent More Useful: Add a Tool

An Agent without tools can only answer from internal knowledge. Adding a search tool lets it fetch live information — the dividing line between an Agent and a plain chatbot:

# agent_search.py —— Agent with search tool
import os
from dotenv import load_dotenv
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.tools.duckduckgo import DuckDuckGoTools

load_dotenv()

news_agent = Agent(
    model=OpenAIChat(
        id="deepseek-chat",
        api_key=os.getenv("DEEPSEEK_API_KEY"),
        base_url="https://api.deepseek.com/v1",
    ),
    tools=[DuckDuckGoTools()],            # Inject DuckDuckGo search capability
    instructions=["Search for the latest info before answering", "List reference links at the end"],
    markdown=True,
    show_tool_calls=True,                 # Show the tool call process in output
)

news_agent.print_response("What are the AI news today?", stream=True)

You'll notice an extra section in the output: the model first requests the search tool, Agno executes it, then feeds the result back to the model for the final answer — exactly the run loop described in Chapter 1. Tool principles and definitions are covered in Chapters 7–8.

2.6 Chapter Summary

• Virtual environment + pip install -U agno is the standard starting point; all usage in this course applies to Agno 3.x, old 1.x APIs are incompatible;
• API Keys always go through .env + python-dotenv; never hard-code;
• Connecting to a third-party model = OpenAIChat(id, api_key, base_url); switching providers means changing only base_url;
• Connection error troubleshooting order: 401 check Key → 404 check URL → 400 check model name;
• Adding tools=[...] upgrades the Agent from "chatting" to "acting."

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. Receiving a 404 Not Found when requesting DeepSeek — what is the most likely cause?

2. What does show_tool_calls=True do?

3. Which practice follows the tutorial's security convention?

4. To let an Agent search the web before answering, what is the minimal change needed?

🛠️ Hands-On Exercises

1. Get a DeepSeek API Key, configure .env, and run agent_01.py; screenshot the first successful output.
2. Intentionally break base_url (remove /v1), observe the error message, then fix it — write the error and cause into your study notes.
3. Replace the question in 2.5 with one you're genuinely interested in (e.g., "What are the new features in the latest Python version?"); compare answer quality with and without the tool.

Once you can reliably run a tool-equipped Agent, proceed to Chapter 3: Running Agents and Parsing RunOutput.