第 2 章 · 环境搭建与第一个 Agent
本章目标：Set up可复用的开发环境，Run through第一个接入 DeepSeek 的 Agent，并Learn to troubleshootthree most common连接错误。
2.1 安装 Agno
Recommend always in虚拟环境中开发，avoid pollutingsystem Python：
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -U agno python-dotenvVerify installation：
python -c "import agno; print(agno.__version__)"
# 3.0.x（教程编写时的最新大版本为 3.x）Version Note
Agno since 2.x 起to 1.x has many breaking changes（如存储类从 agno.storage.sqlite.SqliteStorage migrated to agno.db.sqlite.SqliteDb），3.x continues and consolidatesthis unified API——本课程覆盖的all usage covered 3.x 下applies to。Many tutorials online are based on 1.x，please refer to this course and the official documentation。
2.2 用 .env 管理 API Key
永远不要把 Key 写死在代码里。项目根目录创建 .env 文件：
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx再创建 .gitignore 把它排除出版本库。代码中用 python-dotenv 加载：
# load_env.py
import os
from dotenv import load_dotenv
load_dotenv() # 读取当前目录的 .env 并注入环境变量
key = os.getenv("DEEPSEEK_API_KEY")
print("Key 已加载：" + key[:6] + "..." if key else "未找到 DEEPSEEK_API_KEY！")2.3 第一个 Agent：完整拆解
# agent_01.py —— 你的第一个 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", # 三方模型的模型 ID
api_key=os.getenv("DEEPSEEK_API_KEY"), # 从环境变量读取密钥
base_url="https://api.deepseek.com/v1", # OpenAI 兼容端点
),
instructions=["用简洁的中文回答", "不确定时要明说"],
markdown=True,
)
agent.print_response("一句话介绍什么是 AI Agent")运行 python agent_01.py，你会看到 DeepSeek 的回答被打印出来。逐个参数理解：
id：模型名称，由三方服务商定义（DeepSeek 还有思考模型deepseek-reasoner）；base_url：兼容端点地址。换成 OpenRouter、通义、Kimi 等只需改这一行；instructions：行为指令列表，Agno 会把它们组装进 system 消息；markdown=True：让输出按 Markdown 渲染，终端里表格和代码块更易读。
如果不想记 base_url，也可以使用 Agno 提供的通用类 OpenAILike（位于 agno.models.openai.like），参数完全一致。
2.4 常见连接错误排查
初学者九成的报错集中在这三种情况：
# debug_connection.py —— 三种典型错误的复现与since查
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,
))
# 错误一：401 Unauthorized → Key 未加载或拼写错误
# since查：os.getenv("DEEPSEEK_API_KEY") 是否为 None？
# 错误二：404 Not Found → base_url 少了或多了路径
# DeepSeek 正确写法以 /v1 结尾；写成 https://api.deepseek.com 会 404
# 错误三：model not found → id 与服务商提供的名称不一致
# 例如把 "deepseek-chat" 误写成 "deepseek_v3"
try:
make_agent("https://api.deepseek.com/v1").run("ping")
print("连接成功")
except Exception as e:
print("失败原因：", e)排查口诀：先查 Key（401），再查 URL（404），最后查模型名（400）。
2.5 让第一个 Agent 更有用：加一个工具
不带工具的 Agent 只能靠模型内部知识回答。加上搜索工具后，它能获取实时信息——这是 Agent 与普通聊天机器人的分水岭：
# agent_search.py —— 带搜索工具的 Agent
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()], # 注入 DuckDuckGo 搜索能力
instructions=["先搜索最新信息再回答", "答案末尾列出参考链接"],
markdown=True,
show_tool_calls=True, # 在输出中展示工具调用过程
)
news_agent.print_response("今天有哪些关于 AI 的新闻？", stream=True)观察输出你会发现多了一段工具调用记录：模型先请求调用搜索工具，Agno 执行后把结果回传给模型生成最终答案——这正是第 1 章讲的运行循环。工具的原理与since定义方法在第 7、8 章展开。
2.6 本章小结
- 虚拟环境 +
pip install -U agno是标准起手式；本课程所有用法适用于 Agno 3.x，旧版 1.x API 已不兼容； - API Key 一律走
.env+python-dotenv，严禁硬编码； - 接入三方模型 =
OpenAIChat(id, api_key, base_url)，换服务商只改base_url； - 连接错误排查顺序：401 查 Key → 404 查 URL → 400 查模型名；
- 加上
tools=[...]后，Agent 就从"聊天"升级为"行动"。
🧪 随堂测验
点击你认为正确的选项。答错时会展示正确答案与原因解析。
1. 请求 DeepSeek 时收到 404 Not Found，最可能的原因是？
2. show_tool_calls=True 的作用是？
3. 以下哪种做法符合教程的安全约定？
4. 想让 Agent 回答前先联网查资料，最少需要改动什么？
🛠️ 动手实践
- 申请一个 DeepSeek API Key，配置好
.env，运行agent_01.py并截图保存第一次成功的输出。 - 故意把
base_url改错（去掉/v1），观察报错信息，然后修复——把报错和原因写进你的学习笔记。 - 把 2.5 的 Agent 换成一个你感兴趣的中文问题（如"最近的 Python 版本有什么新特性"），to比加工具前后答案的质量差异。
能稳定Run through带工具的 Agent 后，进入第 3 章：运行 Agent 与 RunOutput 解析。