最近看 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 SDK编写 Agent、Team、Workflow接工具、知识库、记忆、数据库写智能体逻辑AgentOS Runtime用 FastAPI 把 Agent 服务化暴露 API、MCP、调度、追踪等能力把智能体变成服务AgentOS Control Plane在 Web UI 中聊天、看 traces、管 sessions、knowledge、memory、approval管理和观测运行态所以 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 当天仍有 pushApache-2.0 许可证也降低了企业和个人二次开发的顾虑。第二版本迭代密集。PyPI 最新版本2.8.5与 GitHub Releasev2.8.5都出现在 2026-07-27Release 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:52Asia/Shanghai附近抓取的一组 GitHub / PyPI 快照数据会变化适合判断趋势不应当被当成永久事实来源快照信息说明agno-agi/agno约 41480 stars / 5714 forks当天 pushAgno 主仓PyPIagno最新 2.8.52026-07-27 上传Python 包仍在快速发布GitHub Releasev2.8.52026-07-27 发布AgentOS Tools、Tracing、Kimi K3、ClickHouse 修复agno-agi/agentos-*多个部署模板 2026-07-27 有更新Railway、Docker、AWS、GCP、Azure、Helm 等部署路径GitHub 搜索AgentOps、MCP sequential thinking、AI blog generator 等项目提到 Agno第三方适配和用例扩散3. 入门先抓住一个核心Agent 是运行循环不是提示词模板Agno 官方文档对 Agent 的定义很实在Agent 会构建模型上下文处理模型响应执行模型请求的工具并返回RunOutput。这句话比“智能体会思考”更靠谱。把它拆开就是一个基础 agent loop用户输入 - Agent 组装上下文系统指令、用户消息、历史、记忆、知识、状态 - 调用模型 - 模型选择回答或请求工具调用 - Agno 校验参数并执行工具 - 工具结果写回上下文 - 模型继续生成 - 没有新工具调用时返回最终 RunOutput这就是 Agno 入门最重要的心智模型。很多人第一次写 Agent 会把注意力放在 prompt 上但真正决定可用性的通常是四件事模型是否选对模型能力、工具调用能力、结构化输出能力不同。工具是否收敛工具太多会让选择变难也会扩大权限面。指令是否具体告诉 agent 目标、边界、输出格式和不能做什么。状态是否持久没有数据库、记忆和会话历史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_KEYyour_api_key_here如果你更在意隐私可以加一行exportAGNO_TELEMETRYfalseAgno README 说明它默认会发送每次 agent run 的遥测事件用于判断优先支持哪些模型提供商同时说明 prompts、messages 和 outputs 不会发送。是否关闭按你的使用场景决定。4.2 一个 Agent 的最小构成一个 Agno Agent 通常由几类参数组成fromagno.agentimportAgent agentAgent(nameMy Agent,modelopenai:gpt-5.5,instructionsAnswer clearly.,markdownTrue,)agent.print_response(Hello,streamTrue)这里最重要的是参数含义name给 Agent 一个可识别名字后续 tracing、UI、团队协作都会用到model选择模型提供商和模型 ID可以用字符串形式也可以用具体模型类instructions给 Agent 的行为边界与输出要求tools模型可以调用的函数、工具包、MCP 工具或上下文 Providermarkdown让输出更适合终端、文档或 CSDN 这类阅读场景print_response()适合开发调试直接把结果打印出来run()/arun()适合生产代码返回RunOutput或事件流如果你只是试验用print_response()很舒服如果你要接 API、UI 或后端业务逻辑就应该用run()/arun()拿到结构化的返回对象再处理。4.3 工具Agent 真正“能做事”的地方Agno 的工具可以来自多种来源工具来源适合场景Python 函数调用你自己的业务逻辑、内部 API、小工具Toolkit使用官方或社区封装好的 GitHub、Slack、YFinance、HackerNews 等集成MCPTools接入 Model Context Protocol 生态里的外部服务Context Provider给复杂外部系统提供更紧凑、更安全的读写接口Callable Factory根据用户、session、角色动态决定本次运行暴露哪些工具官方文档里有一个订单查询函数示例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,}这个设计的关键不在“函数能不能执行”而在“模型能不能正确理解它”。所以工具函数要做到函数名具体不要叫do()、process()。docstring 讲清楚什么时候该用。参数加类型注解避免模型猜错参数结构。返回值尽量结构化别返回一大坨难解析文本。初期少暴露工具先让 Agent 的选择空间变窄。5. 实践实现一个只读项目清点智能体下面这个实践来自 Agno 官方 First Agent 的思路但我们稍微改成更适合中文开发者的“项目清点智能体”。它做三件事读取当前目录。列出和搜索文件。输出项目结构、重点文件、可能入口和整理建议。为了安全第一版只开放read、list、search三个权限不让它改文件。5.1 创建文件保存为project_inventory_agent.pyfrompathlibimportPathfromagno.agentimportAgentfromagno.tools.workspaceimportWorkspace ROOTPath(__file__).parent project_inventory_agentAgent(nameProject Inventory Agent,modelopenai:gpt-5.5,tools[Workspace(rootstr(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.,],markdownTrue,debug_modeTrue,)if__name____main__:project_inventory_agent.print_response(fInventory this project directory and propose a clean organization plan:{ROOT},streamTrue,)5.2 安装并运行uv venv--python3.12source.venv/bin/activate uv pipinstall-Uagno openaiexportOPENAI_API_KEYyour_api_key_herepython project_inventory_agent.py如果你的账号没有openai:gpt-5.5这个模型就把model改成你当前可用、且支持工具调用的模型。Agno 文档里同时支持字符串形式和模型类形式例如fromagno.models.openaiimportOpenAIResponses modelOpenAIResponses(idyour_model_id)5.3 这段代码背后的运行过程这段代码看起来短但它已经包含了 Agent 的关键组件。第一Workspace(rootstr(ROOT), allowed[read, list, search])把当前目录变成一个受限工具空间。模型不是直接拥有你的电脑权限而是只能通过 Agno 暴露的工具做被允许的事情。第二instructions告诉 Agent 任务边界先检查结构再总结用途再给整理建议同时明确“不修改文件”。这比单纯说“帮我整理项目”可靠得多。第三debug_modeTrue适合学习阶段。你可以看到更多执行细节理解 Agent 是怎么构建上下文、什么时候调用工具、工具返回了什么。第四streamTrue会让结果边生成边打印。对长报告、长推理、工具多次调用的任务来说流式输出体验更好。一个可能的输出结构会类似## 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 页面在跑通脚本后立刻把例子推进到 AgentOSfromagno.agentimportAgentfromagno.db.sqliteimportSqliteDbfromagno.osimportAgentOSfromagno.tools.workspaceimportWorkspace workbenchAgent(nameWorkbench,modelopenai:gpt-5.5,dbSqliteDb(db_fileworkbench.db),tools[Workspace(.)],enable_agentic_memoryTrue,add_history_to_contextTrue,num_history_runs3,)agent_osAgentOS(agents[workbench],tracingTrue)appagent_os.get_app()if__name____main__:agent_os.serve(appworkbench:app,reloadTrue)这一步很重要因为它把“一次性脚本”变成了“可访问的服务”能力脚本模式AgentOS 模式运行入口命令行REST API / SSE / WebSocket / MCP / UI会话临时可持久化观测看终端日志traces、sessions、metrics多用户需要自己写JWT / RBAC / service account调度需要 cron 或外部系统AgentOS Scheduler审批需要自己做Human approval / pending approvals但我不建议第一天就直接上生产运行时。正确节奏应该是先写单 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。简单说概念保存什么作用范围Storage会话历史、运行记录通常按session_idMemory用户偏好、事实、长期上下文通常按user_idKnowledge文档、业务资料、FAQ、数据库知识被检索后进入上下文Session State应用自己维护的状态当前会话或任务流程这一点很关键。不要把所有聊天记录都塞进 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。但一旦你想让它长期服务真实用户就会遇到一串工程问题会话怎么保存多用户怎么隔离工具调用怎么审批出错后怎么追踪运行结果怎么评估Agent 怎么以 API 暴露给产品定时任务、后台任务、长任务怎么跑外部系统权限怎么收敛Agno 的答案是SDK 负责写 AgentAgentOS 负责运行Control Plane 负责管理。这个分层本身是合理的。它的不足也很明显能力多概念就多。对于只想写一个 20 行 demo 的新手Agno 可能显得“重”但对于想把 agent 做成产品的人这种“重”反而可能是必要的秩序。我建议用 Agno 时保持一个判断标准先把 Agent 当函数写稳再把 Agent 当服务运行最后才把它当平台管理。这句话也会是这个系列的主线。9. 这个系列后面怎么写我会把“Agno 从入门到精通”拆成一个渐进系列而不是一篇文章塞满所有概念。暂定路线如下篇章主题第一篇入门、核心概念、基础方法、只读项目清点智能体第二篇Tools 深入Python 函数、Toolkit、MCPTools、工具权限与可靠性第三篇Storage / Memory会话历史、用户记忆、长期上下文设计第四篇Knowledge 与 Agentic RAG文档导入、向量库、检索策略第五篇Teams多智能体协作、路由、广播、任务拆分第六篇Workflows固定流程、并行、条件、循环与可复用任务管线第七篇AgentOSAPI 化、MCP、UI、tracing、scheduler、approval第八篇生产实践权限、观测、evals、成本、部署与故障排查今天这篇只做第一步。把一个只读 Agent 跑起来比一次性讲完所有概念更重要。因为 Agent 工程不是背 API而是在真实任务里反复回答三个问题它知道什么 它能做什么 它做错了我怎么知道Agno 的价值也正是在这三个问题上逐渐显现出来。参考来源Agno GitHub 主仓https://github.com/agno-agi/agnoAgno 官方文档https://docs.agno.comAgno First Agenthttps://docs.agno.com/first-agentAgno Agents Overviewhttps://docs.agno.com/agents/overviewAgno Building Agentshttps://docs.agno.com/agents/building-agentsAgno Running Agentshttps://docs.agno.com/agents/running-agentsAgno Tools Overviewhttps://docs.agno.com/tools/overviewAgno Knowledge Overviewhttps://docs.agno.com/knowledge/overviewAgno Memory Overviewhttps://docs.agno.com/memory/overviewAgno Database Overviewhttps://docs.agno.com/database/overviewAgno Teams Overviewhttps://docs.agno.com/teams/overviewAgno Workflows Overviewhttps://docs.agno.com/workflows/overviewAgno AgentOS Introductionhttps://docs.agno.com/agent-os/introductionAgno AgentOS Runtimehttps://docs.agno.com/agent-os/overviewAgno AgentOS Securityhttps://docs.agno.com/agent-os/security/overviewAgno Coding Agentshttps://docs.agno.com/coding-agentsAgno PyPIhttps://pypi.org/project/agno/Agno v2.8.5 Releasehttps://github.com/agno-agi/agno/releases/tag/v2.8.5GitHub API 快照本文仓库热度、Release、组织仓库和第三方生态搜索数据抓取时间为 2026-07-29 15:52Asia/Shanghai原始记录保存在本地研究目录。许可说明本文为原创中文技术解读与实践整理不是对 Agno 官方文档或 README 的完整翻译。Agno 主仓采用 Apache-2.0 License本文只做必要的短引用、结构化概括、代码实践说明和来源链接不搬运第三方受限图片或大段原文。
