Agno 是 2026 年增长很快的一个 Python Agent 框架，特点是极快、代码少、原生支持工具调用、知识库和记忆。本教程带你用不到 30 行代码，写出一个会联网搜索的 Agent——它不再只会「凭记忆编」，而是能自己调用工具取真数据。全程可复现，跟着敲就行。
⚡ 本教程适合：会一点 Python、想把「调一个模型」升级成「会干活的智能体」的开发者。你需要 Python 3.10+ 和一个 OpenAI 兼容的 API Key（DeepSeek、通义也行）。
Step 1：准备环境
1 建虚拟环境并安装
# 用 uv（推荐）或普通 venv 都行
uv venv --python 3.12
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -U agno openai duckduckgo-search
export OPENAI_API_KEY="sk-..." # Windows 用 setx OPENAI_API_KEY sk-...💡
duckduckgo-search 是后面联网搜索工具要用的依赖，提前装上省得报错。OPENAI_API_KEY 用环境变量传入，别写死在代码里。Step 2：写一个最简单的 Agent
2 模型 + 人设就能跑
from agno.agent import Agent
from agno.models.openai import OpenAIChat
agent = Agent(
model=OpenAIChat(id="gpt-4o-mini"), # 模型名以官方文档为准
description="你是一个热情、擅长讲故事的新闻播报员！",
markdown=True, # 让回答带 Markdown 格式
)
agent.print_response("用一句话讲一个今天科技圈的新鲜事", stream=True)模型名会变：示例里 gpt-4o-mini 只是举例，Agno 支持 OpenAI、DeepSeek、Groq 等几十家。具体可用模型 ID 以 Agno 官方文档和你所用厂商的当前命名为准，别照抄旧名字。
Step 3：给它装上「联网搜索」工具
3 一行 tools 让 Agent 会查资料
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.tools.duckduckgo import DuckDuckGoTools
agent = Agent(
model=OpenAIChat(id="gpt-4o-mini"),
description="你是一个热情的新闻播报员，擅长讲故事！",
tools=[DuckDuckGoTools()], # 关键：把搜索工具交给 Agent
show_tool_calls=True, # 在回答里展示「它调用了搜索」
markdown=True,
)
agent.print_response("今天 AI 圈有什么大新闻？给我列三条并附上来源", stream=True)🔍 现在 Agent 会先「思考要搜什么」→ 调用 DuckDuckGo → 读结果 → 组织回答。
show_tool_calls=True 能让你看见它每一步在干嘛，调试特别方便。Step 4：加知识库（Agentic RAG 默认开启）
4 让 Agent 优先查你的文档
Agno 的亮点之一：知识库默认就是 Agentic RAG——Agent 会自己判断「该搜知识库哪部分」，而不是盲目塞全部文档。下面给一个最小可跑示例：
from agno.knowledge.pdf_url import PDFUrlKnowledgeBase
from agno.vectordb.lancedb import LanceDb, SearchType
from agno.embedder.openai import OpenAIEmbedder
knowledge = PDFUrlKnowledgeBase(
urls=["https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf"],
vector_db=LanceDb(
uri="tmp/lancedb",
table_name="recipes",
search_type=SearchType.hybrid,
embedder=OpenAIEmbedder(id="text-embedding-3-small"),
),
)
# 首次运行先建索引：knowledge.load()
agent = Agent(
model=OpenAIChat(id="gpt-4o-mini"),
knowledge=knowledge,
tools=[DuckDuckGoTools()],
instructions=["优先用知识库回答，知识库没有再联网补充"],
markdown=True,
)
agent.print_response("怎么做椰奶鸡汤？", stream=True)📚 跑这个示例需额外装
pip install lancedb tantivy pypdf。真实项目里把 urls= 换成你自己的文档路径或向量库即可。Step 5：把 Agent 跑成常驻服务（可选）
5 一行 serve 出 API + 界面
# pip install "agno[os]"
from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.os import AgentOS
from agno.tools.workspace import Workspace
from agno.models.openai import OpenAIChat
agent = Agent(
name="Workbench",
model=OpenAIChat(id="gpt-4o-mini"),
db=SqliteDb(db_file="workbench.db"), # 会话存储
tools=[Workspace(".")],
enable_agentic_memory=True, # 跨会话记忆
add_history_to_context=True,
num_history_runs=3,
)
agent_os = AgentOS(agents=[agent], tracing=True)
app = agent_os.get_app()
if __name__ == "__main__":
agent_os.serve(app="__main__:app", reload=True) # 默认 http://localhost:7777端口暴露注意：serve 会在本机起一个 7777 端口的服务。只在本地或受信任的内网用；若要放到公网，务必加鉴权、用反向代理，并确认防火墙规则，别把未设防的 Agent 直接暴露出去。
常见问题速查
| 现象 | 大概率原因 & 解决 |
|---|---|
| ImportError: cannot import name ... | Agno 版本过旧，pip install -U agno 升级 |
| 报错说找不到 API Key | 没设 OPENAI_API_KEY 环境变量，或 Key 无效 |
| 知识库问答不生效 | 忘了先 knowledge.load() 建索引 |
| 想换 DeepSeek / 通义 | 把 OpenAIChat 换成对应模型类，或改用字符串 "openai:模型id" 形式 |