Agno：轻量级模型无关的 Agent 框架

为什么需要 Agno：多模型 Agent 开发的重复劳动

构建 LLM Agent 时，每个模型厂商（OpenAI、Anthropic、Google、Mistral 以及 Ollama 本地模型）都有自己的 SDK、消息格式和工具调用（function calling，即让模型输出结构化调用指令的能力）约定。直接在业务代码里适配这些差异，会产生大量样板代码：手动维护对话历史、自己解析工具调用并回填结果、为每个模型写一套请求构造逻辑。项目一旦需要切换模型或做 A/B 对比，改动面大且容易引入不一致。

Agno 把「模型无关」做成框架的核心：模型只通过统一的 models 接口注入（例如 OpenAIChat、AnthropicChat、Gemini、Ollama），Agent 内部自动完成消息格式转换、工具调用解析与回填、流式输出。切换模型通常只需要替换一个类并重跑，业务代码不动。同时 Agent 类内置短期记忆（会话上下文）、长期记忆（storage 持久化）与知识库（RAG），这些高频能力无需自行实现。

与 LangChain 大量抽象组件不同，Agno 坚持「少即是多」：核心概念只有 Agent、Model、Memory、Knowledge、Tools 五类对象，绝大多数场景从一个 Agent 实例开始。这让它在快速原型和中小型生产服务中特别顺手，代码量直观可审。

安装与环境配置：4 步就绪

第一步：创建并激活虚拟环境，需要 Python 3.9 以上。开发 Agent 应用强烈建议用 venv 隔离依赖，避免与系统 Python 冲突。

第二步：安装 agno 主包。

第三步：按需安装要使用的模型 SDK。Agno 的模型接入是独立子包，用哪个模型装哪个 SDK。

第四步：配置 API Key，可通过环境变量注入，或写进 .env 文件由 python-dotenv 加载。

# 1. 虚拟环境（Windows 用 .venv\Scripts\activate）python -m venv .venvsource .venv/bin/activate # 2. 安装框架本体pip install agno # 3. 按需安装对应模型 SDKpip install openai                # OpenAI 及兼容接口pip install anthropic             # Claudepip install google-generativeai   # Geminipip install ollama                # 本地模型 # 4. 配置 API Key（环境变量方式）export OPENAI_API_KEY="sk-..."export ANTHROPIC_API_KEY="sk-ant-..." # 5. 验证安装python -c "from agno.agent import Agent; print('agno ok')"

快速上手：8 分钟跑通第一个 Agent

最小可用流程不需要任何配置文件：实例化一个 Agent、指定模型、调用 print_response 即可输出回复。第一个示例建议用 gpt-4o-mini（成本低）或本地 Ollama，先验证链路通。

分步操作：

1. 在项目目录创建 .env，写入 OPENAI_API_KEY=sk-...。

2. 按上文安装 agno 与 openai 两个包。

3. 新建 hello_agent.py，粘贴下方最小示例。

4. 运行 python hello_agent.py，终端会流式打印回复。

5. 若输出正常，再改用 run 方法拿返回值做程序化处理。

进阶技巧：给 Agent 挂上工具后，它会自动完成「识别意图 → 调用工具 → 汇总结果」的多轮循环，无需手写 function calling 逻辑：

# hello_agent.py —— 最小可用示例（真实 API）from agno.agent import Agentfrom agno.models.openai import OpenAIChat agent = Agent(    model=OpenAIChat(id="gpt-4o-mini"),    description="You are a helpful assistant.",    markdown=True,) # 流式打印回复（终端友好）agent.print_response("用一句话介绍你自己", stream=True) # 编程式获取返回对象resp = agent.run("请返回 JSON：{'ok': true}")print(resp.content)

from agno.agent import Agentfrom agno.models.openai import OpenAIChatfrom agno.tools.duckduckgo import DuckDuckGoTools  # 需要 pip install duckduckgo-search agent = Agent(    model=OpenAIChat(id="gpt-4o-mini"),    tools=[DuckDuckGoTools()],    show_tool_calls=True,  # 打印工具调用过程)agent.print_response("搜索 2025 年 AI Agent 框架排名", stream=True)

核心能力详解：5 大支柱

支柱一·模型无关抽象层。Models 子包统一了各厂商接口，切换模型只需更换 model= 参数。除了公有云模型，还支持 Ollama（本地）、OpenRouter（聚合）等；私有化场景可把推理服务包装成 OpenAI 兼容接口接入。适合做多模型 A/B 对比与成本优化。

支柱二·记忆系统。会话内短期记忆默认开启；跨会话长期记忆需配置 storage，内置 SqliteStorage、DynamoDB 等后端；「agentic memory」可自动从对话中提取用户偏好并在后续会话自动应用（如记住用户喜欢简洁回答）。这是 Agno 相比裸调 SDK 的核心优势。

支柱三·知识库 RAG。Knowledge 类负责文档加载与向量化，配合向量数据库（Chroma、Qdrant、PgVector、Pinecone）实现检索增强（RAG，即先检索相关资料再让模型回答）。典型用法：读入 PDF/网页 → 存入向量库 → Agent 在回答前自动检索相关内容、降低幻觉。

支柱四·工具调用与内置 Toolkit。任意 Python 函数加类型注解和 docstring 即可作为工具，框架自动生成 JSON Schema 并完成调用闭环。内置 DuckDuckGo、Shell、File、SQL、Wikipedia、YFinance 等 Toolkit，省去从零封装第三方服务的工作。

支柱五·多 Agent 协作。支持「Agents as Tools」——把整个 Agent 实例作为另一个 Agent 的工具传入；Team 模式可让多个 Agent 分工协作，适用于调研、报表生成等流水线任务。

生产部署与监控：从上线到运维

部署方式一·FastAPI 包装。用 FastAPI 暴露 HTTP 接口，把 Agent 包在 POST 路由中。Agno 的 arun 是异步接口，FastAPI 原生支持；每个会话建议使用独立 Agent 实例或显式传入 session_id，避免状态串扰。

部署方式二·容器与无服务器。将上述应用打成 Docker 镜像，部署到 ECS、GKE 或 Cloud Run。Agno 本体除数据库/向量库外无外部依赖，镜像小、冷启动快，适合按请求弹缩。

可观测性。run 返回 RunResponse，其中 .metrics 含 token 用量、耗时、工具调用次数等结构化数据，可直接采集上报；设置 debug_mode=True 可输出完整内部执行日志，便于排查工具调用链路问题。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>坑 1：高并发下不要共享单个 Agent 的会话状态——Agent 默认按 run 维护上下文，生产服务应为每个会话使用独立实例或传入 session_id，否则对话记忆串线。</li><li>坑 2：切换模型并非零成本——不同模型对 system prompt 与工具调用格式的敏感度差异很大，换模型后必须回归测试 function calling 链路。</li><li>坑 3：长期记忆默认不持久化——不配置 storage 时记忆只存在进程内存，服务重启即丢；生产环境务必配置 SqliteStorage 等后端并做好备份。</li></ul>

# serve_agent.py —— 生产最小模板from fastapi import FastAPIfrom pydantic import BaseModelfrom agno.agent import Agentfrom agno.models.openai import OpenAIChat app = FastAPI()agent = Agent(model=OpenAIChat(id="gpt-4o-mini")) class ChatRequest(BaseModel):    message: str @app.post("/chat")async def chat(req: ChatRequest):    resp = await agent.arun(req.message)    return {"answer": resp.content}

版本迭代

Agno 起源于 2023 年开源的 Phidata，2025 年 1 月正式更名并迁移仓库。更名后保持高频迭代：核心 API 稳定在「Agent + Model + Memory + Knowledge + Tools」五类对象，迭代重点从模型接入数量转向多 Agent 协作、语音与性能优化。（截至训练数据，可能已有更新版本）

AI 应用场景

常见误区

面试题