第 2 章 · 环境搭建与第一个 Agent
本章目标：搭好可复用的开发环境，跑通第一个接入 DeepSeek 的 Agent，并学会排查三类最常见的连接错误。
2.1 安装 Agno
推荐始终在虚拟环境中开发，避免污染系统 Python：
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -U agno python-dotenv验证安装：
python -c "import agno; print(agno.__version__)"
# 2.9.x（教程编写时的最新大版本为 2.x）版本提示
Agno 2.x 相比 1.x 有大量破坏性变更（如存储类从 agno.storage.sqlite.SqliteStorage 迁移到 agno.db.sqlite.SqliteDb）。网上大量旧教程基于 1.x，请以本课程和官方文档为准。
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 —— 三种典型错误的复现与自查
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 未加载或拼写错误
# 自查：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 章讲的运行循环。工具的原理与自定义方法在第 7、8 章展开。
2.6 本章小结
- 虚拟环境 +
pip install -U agno是标准起手式；注意区分 Agno 2.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 版本有什么新特性"），对比加工具前后答案的质量差异。
能稳定跑通带工具的 Agent 后，进入第 3 章：运行 Agent 与 RunOutput 解析。