最近看 AI Agent 框架，会明显感觉到一个变化：大家不再满足于“让模型调用几个函数”。真正被推到前台的问题，变成了怎样把智能体从一个 demo，变成能长期运行、可观测、可接入业务系统、能被权限约束的 agent platform。

Agno 正好站在这个位置上。

这篇是“Agno 从入门到精通”系列的第一篇。我们先不急着上 Teams、Workflows、AgentOS、MCP、生产部署这些大菜，第一篇只解决一个朴素问题：

Agno 到底是什么？一个最小可用的 Agno Agent 是怎样跑起来的？

读完这篇，你应该能明白 Agno 的基本抽象，并能写出一个会读取项目目录、调用工具、输出整理建议的简单智能体。

1. Agno 到底是什么

如果用一句话说：Agno 是一个用于构建、运行和管理 Agent Platform 的 Python 框架与运行时。

它不是只给你一个chat()函数，也不是只给模型挂几个工具。官方 README 把 Agno 拆成三层：

所以 Agno 的野心不只是“帮你写一个会回答问题的助手”，而是提供一套从本地脚本到线上服务的连续路径：

写一个 Agent -> 加工具、知识库、记忆、存储 -> 变成 API / MCP / Slack / Telegram 等入口 -> 加 tracing、evals、approval、scheduler -> 进入可管理、可复盘、可治理的 agent platform

这也是它最近值得关注的原因。LangGraph 更强调图式编排，CrewAI 更强调角色协作，OpenAI Agents SDK 更贴近 OpenAI 模型与工具生态，而 Agno 最近的重心很明确：把 agent 平台所需的运行时能力也一起打包进来。

2. 为什么最近 Agno 比较火

从全网与 GitHub 检索看，Agno 的热度主要来自四条线索。

第一，主仓关注度高，而且活跃。GitHub API 快照显示，agno-agi/agno在 2026-07-29 当天仍有 push；Apache-2.0 许可证也降低了企业和个人二次开发的顾虑。

第二，版本迭代密集。PyPI 最新版本2.8.5与 GitHub Releasev2.8.5都出现在 2026-07-27，Release notes 里重点提到 AgentOS 工具、traces 统计和 SQL 注入修复。这说明项目不只在堆功能，也在补运维、安全和观测能力。

第三，生态形态变清晰。Agno 官方组织下除了主仓，还有agentos-railway、agentos-docker、agentos-aws、agentos-gcp、agentos-azure、agentos-helm等部署模板，以及dash、scout、coda、context这类用 Agno 思路构建的应用型项目。换句话说，它不是只做 SDK，而是连“怎么把 agent 交付出去”也在设计。

第四，第三方仓库开始把 Agno 当成可集成对象。GitHub 搜索里能看到监控工具 AgentOps 声称兼容 Agno，也能看到基于 Agno 的多智能体博客生成、MCP sequential thinking、文件整理、旅行规划、金融分析等示例项目。生态不一定都成熟，但这类“别人愿意适配你”的信号，通常比单个 demo 更有价值。

下面是 2026-07-29 15:52（Asia/Shanghai）附近抓取的一组 GitHub / PyPI 快照，数据会变化，适合判断趋势，不应当被当成永久事实：

3. 入门先抓住一个核心：Agent 是运行循环，不是提示词模板

Agno 官方文档对 Agent 的定义很实在：Agent 会构建模型上下文，处理模型响应，执行模型请求的工具，并返回RunOutput。

这句话比“智能体会思考”更靠谱。把它拆开，就是一个基础 agent loop：

用户输入 -> Agent 组装上下文：系统指令、用户消息、历史、记忆、知识、状态 -> 调用模型 -> 模型选择回答，或请求工具调用 -> Agno 校验参数并执行工具 -> 工具结果写回上下文 -> 模型继续生成 -> 没有新工具调用时，返回最终 RunOutput

这就是 Agno 入门最重要的心智模型。

很多人第一次写 Agent 会把注意力放在 prompt 上，但真正决定可用性的通常是四件事：

1. 模型是否选对：模型能力、工具调用能力、结构化输出能力不同。
2. 工具是否收敛：工具太多会让选择变难，也会扩大权限面。
3. 指令是否具体：告诉 agent 目标、边界、输出格式和不能做什么。
4. 状态是否持久：没有数据库、记忆和会话历史，agent 每次都像第一次见你。

第一篇我们先把 1、2、3 跑通；状态持久化和记忆留到后续文章展开。

4. Agno 的基础方法：从最小 Agent 到可运行输出

4.1 安装

Agno 官方示例推荐使用uv创建环境：

uv venv--python3.12source.venv/bin/activate uv pipinstall-Uagno openai

如果用 OpenAI 模型，需要设置环境变量：

exportOPENAI_API_KEY="your_api_key_here"

如果你更在意隐私，可以加一行：

exportAGNO_TELEMETRY=false

Agno README 说明它默认会发送每次 agent run 的遥测事件，用于判断优先支持哪些模型提供商；同时说明 prompts、messages 和 outputs 不会发送。是否关闭，按你的使用场景决定。

4.2 一个 Agent 的最小构成

一个 Agno Agent 通常由几类参数组成：

fromagno.agentimportAgent agent=Agent(name="My Agent",model="openai:gpt-5.5",instructions="Answer clearly.",markdown=True,)agent.print_response("Hello",stream=True)

这里最重要的是：

如果你只是试验，用print_response()很舒服；如果你要接 API、UI 或后端业务逻辑，就应该用run()/arun()，拿到结构化的返回对象再处理。

4.3 工具：Agent 真正“能做事”的地方

Agno 的工具可以来自多种来源：

官方文档里有一个订单查询函数示例，Agno 会根据函数名、docstring 和类型注解构建工具 schema。模型看到 schema 后，会决定何时调用、传什么参数，Agno 再负责校验和执行。

一个简单的自定义工具大概是这样：

deflookup_order(order_id:str)->dict:"""Return the status and delivery date for an order. Args: order_id: The order ID to look up. """return{"order_id":order_id,"status":"shipped","delivery_date":"2026-07-22",}

这个设计的关键不在“函数能不能执行”，而在“模型能不能正确理解它”。所以工具函数要做到：

1. 函数名具体，不要叫do()、process()。
2. docstring 讲清楚什么时候该用。
3. 参数加类型注解，避免模型猜错参数结构。
4. 返回值尽量结构化，别返回一大坨难解析文本。
5. 初期少暴露工具，先让 Agent 的选择空间变窄。

5. 实践：实现一个只读项目清点智能体

下面这个实践来自 Agno 官方 First Agent 的思路，但我们稍微改成更适合中文开发者的“项目清点智能体”。

它做三件事：

1. 读取当前目录。
2. 列出和搜索文件。
3. 输出项目结构、重点文件、可能入口和整理建议。

为了安全，第一版只开放read、list、search三个权限，不让它改文件。

5.1 创建文件

保存为project_inventory_agent.py：

frompathlibimportPathfromagno.agentimportAgentfromagno.tools.workspaceimportWorkspace ROOT=Path(__file__).parent project_inventory_agent=Agent(name="Project Inventory Agent",model="openai:gpt-5.5",tools=[Workspace(root=str(ROOT),allowed=["read","list","search"],)],instructions=["You are a cautious project inventory assistant.","Only read, list, and search files in the workspace. Do not modify files.","First inspect the directory structure, then summarize the project purpose.","Group important files by role, identify likely entry points, and suggest next cleanup steps.","Return the answer in concise Markdown.",],markdown=True,debug_mode=True,)if__name__=="__main__":project_inventory_agent.print_response(f"Inventory this project directory and propose a clean organization plan:{ROOT}",stream=True,)

5.2 安装并运行

uv venv--python3.12source.venv/bin/activate uv pipinstall-Uagno openaiexportOPENAI_API_KEY="your_api_key_here"python project_inventory_agent.py

如果你的账号没有openai:gpt-5.5这个模型，就把model改成你当前可用、且支持工具调用的模型。Agno 文档里同时支持字符串形式和模型类形式，例如：

fromagno.models.openaiimportOpenAIResponses model=OpenAIResponses(id="your_model_id")

5.3 这段代码背后的运行过程

这段代码看起来短，但它已经包含了 Agent 的关键组件。

第一，Workspace(root=str(ROOT), allowed=["read", "list", "search"])把当前目录变成一个受限工具空间。模型不是直接拥有你的电脑权限，而是只能通过 Agno 暴露的工具做被允许的事情。

第二，instructions告诉 Agent 任务边界：先检查结构，再总结用途，再给整理建议；同时明确“不修改文件”。这比单纯说“帮我整理项目”可靠得多。

第三，debug_mode=True适合学习阶段。你可以看到更多执行细节，理解 Agent 是怎么构建上下文、什么时候调用工具、工具返回了什么。

第四，stream=True会让结果边生成边打印。对长报告、长推理、工具多次调用的任务来说，流式输出体验更好。

一个可能的输出结构会类似：

## Project Summary This directory appears to contain ... ## Important Files - README.md: ... - pyproject.toml: ... - src/: ... ## Suggested Organization 1. Move temporary files to ... 2. Add documentation for ... 3. Split scripts into ...

注意，这不是传统脚本的确定性输出。Agent 的价值在于它会读取真实目录，并根据实际文件内容生成报告；风险也在这里：如果工具权限给得太大，它就可能做你没准备好的事。所以第一篇我建议只读开始。

6. 再进一步：把脚本变成服务

官方 First Agent 页面在跑通脚本后，立刻把例子推进到 AgentOS：

fromagno.agentimportAgentfromagno.db.sqliteimportSqliteDbfromagno.osimportAgentOSfromagno.tools.workspaceimportWorkspace workbench=Agent(name="Workbench",model="openai:gpt-5.5",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=[workbench],tracing=True)app=agent_os.get_app()if__name__=="__main__":agent_os.serve(app="workbench:app",reload=True)

这一步很重要，因为它把“一次性脚本”变成了“可访问的服务”：

但我不建议第一天就直接上生产运行时。正确节奏应该是：

先写单 Agent -> 收窄工具权限 -> 跑通 3-5 个真实任务 -> 加 session storage -> 再考虑 memory / knowledge -> 最后上 AgentOS 服务化

Agent 开发最怕一开始就把所有能力打开。工具、记忆、知识库、团队协作、工作流、调度、审批全部堆上去，问题会变得很难定位。第一篇的目标就是让单个 Agent 稳稳落地。

7. Agno 里几个容易混淆的概念

7.1 Storage 和 Memory 不一样

Agno 文档明确区分了 Storage 与 Memory。

Storage 主要保存会话历史、session、runs 等内容。你问“刚才我们讨论了什么”，靠的是 storage 和session_id。

Memory 保存的是用户级事实，比如偏好、身份、长期目标。你问“你知道我喜欢什么风格吗”，靠的是 memory 和user_id。

简单说：

这一点很关键。不要把所有聊天记录都塞进 memory，也不要指望 storage 自动理解用户长期偏好。

7.2 Knowledge 是 RAG，不是记忆

Knowledge 的作用是让 Agent 能检索外部内容：PDF、网页、Markdown、CSV、数据库资料等。官方文档把它解释为让 agent 获得训练数据之外的领域信息。

它通常包含三步：

内容导入 -> 切块与 embedding -> 向量/关键词/混合检索 -> 把相关片段加入模型上下文

这适合公司文档、产品说明、支持 FAQ、研究论文、代码文档。后续系列我会单独写 Agno 的 Knowledge 与 Agentic RAG。

7.3 Team 和 Workflow 也不一样

Team 是多个 Agent 协作，由 leader 进行协调、路由或广播。适合“不同角色、不同工具、不同专业能力”的任务。

Workflow 是确定步骤的编排。适合固定顺序、条件分支、循环、并行步骤的任务。

可以粗暴地记：

需要模型动态分工：Team 需要确定流程控制：Workflow

第一篇不展开这两个，是因为它们只有在单 Agent 写稳之后才有意义。

8. 我怎么看 Agno 的技术路线

Agno 有一个非常鲜明的方向：把 Agent 从“模型应用代码”推向“平台工程”。

这在今天很重要。很多 Agent demo 能跑，是因为人坐在旁边帮它补上下文、看报错、复制结果、手动改 prompt。但一旦你想让它长期服务真实用户，就会遇到一串工程问题：

1. 会话怎么保存？
2. 多用户怎么隔离？
3. 工具调用怎么审批？
4. 出错后怎么追踪？
5. 运行结果怎么评估？
6. Agent 怎么以 API 暴露给产品？
7. 定时任务、后台任务、长任务怎么跑？
8. 外部系统权限怎么收敛？

Agno 的答案是：SDK 负责写 Agent，AgentOS 负责运行，Control Plane 负责管理。这个分层本身是合理的。

它的不足也很明显：能力多，概念就多。对于只想写一个 20 行 demo 的新手，Agno 可能显得“重”；但对于想把 agent 做成产品的人，这种“重”反而可能是必要的秩序。

我建议用 Agno 时保持一个判断标准：

先把 Agent 当函数写稳，再把 Agent 当服务运行，最后才把它当平台管理。

这句话也会是这个系列的主线。

9. 这个系列后面怎么写

我会把“Agno 从入门到精通”拆成一个渐进系列，而不是一篇文章塞满所有概念。

暂定路线如下：

今天这篇只做第一步。把一个只读 Agent 跑起来，比一次性讲完所有概念更重要。因为 Agent 工程不是背 API，而是在真实任务里反复回答三个问题：

它知道什么？ 它能做什么？ 它做错了我怎么知道？

Agno 的价值，也正是在这三个问题上逐渐显现出来。

参考来源

• Agno GitHub 主仓：https://github.com/agno-agi/agno
• Agno 官方文档：https://docs.agno.com
• Agno First Agent：https://docs.agno.com/first-agent
• Agno Agents Overview：https://docs.agno.com/agents/overview
• Agno Building Agents：https://docs.agno.com/agents/building-agents
• Agno Running Agents：https://docs.agno.com/agents/running-agents
• Agno Tools Overview：https://docs.agno.com/tools/overview
• Agno Knowledge Overview：https://docs.agno.com/knowledge/overview
• Agno Memory Overview：https://docs.agno.com/memory/overview
• Agno Database Overview：https://docs.agno.com/database/overview
• Agno Teams Overview：https://docs.agno.com/teams/overview
• Agno Workflows Overview：https://docs.agno.com/workflows/overview
• Agno AgentOS Introduction：https://docs.agno.com/agent-os/introduction
• Agno AgentOS Runtime：https://docs.agno.com/agent-os/overview
• Agno AgentOS Security：https://docs.agno.com/agent-os/security/overview
• Agno Coding Agents：https://docs.agno.com/coding-agents
• Agno PyPI：https://pypi.org/project/agno/
• Agno v2.8.5 Release：https://github.com/agno-agi/agno/releases/tag/v2.8.5
• GitHub API 快照：本文仓库热度、Release、组织仓库和第三方生态搜索数据抓取时间为 2026-07-29 15:52（Asia/Shanghai），原始记录保存在本地研究目录。

许可说明

本文为原创中文技术解读与实践整理，不是对 Agno 官方文档或 README 的完整翻译。Agno 主仓采用 Apache-2.0 License；本文只做必要的短引用、结构化概括、代码实践说明和来源链接，不搬运第三方受限图片或大段原文。