Agno 全景解析：从 SDK 构建 Agent 到 AgentOS 运行时与数据自主权

Agno 是一个用于构建、运行和管理 Agent 平台的框架与运行时，其核心由三层组成：用 Python 定义组件的 Agno SDK、以生产级 API 对外服务这些组件的 AgentOS 运行时、以及用于对话和巡检的 AgentOS UI。本文以仓库中的概览文档 agno_overview.md 为骨架，结合 快速上手目录 与 SDK 源码，逐层拆解这套技术栈的分层职责、最小工具型 Agent 的写法、构建块（Agent / Team / Workflow）的选择依据，以及数据所有权在生产部署中的落地方式。

一、技术栈总览：SDK、AgentOS Runtime、AgentOS UI 三层结构

概览文档将 Agno 定义为 "a framework and runtime for building, running, and managing agent platforms"（用于构建、运行和管理 Agent 平台的框架与运行时）。这三层各自承担明确的职责：

层	职责	仓库中的对应实现
Agno SDK	在 Python 中定义 agent、team、workflow、tool、knowledge、memory、learning	libs/agno/agno/agent/agent.py、team.py、workflow.py
AgentOS Runtime	通过生产级 API 对外提供服务，带会话（sessions）、流式（streaming）、追踪（tracing）、人工审批（human approval）	libs/agno/agno/os/app.py 中的 AgentOS 类（约 L277 起）
AgentOS UI	连接 AgentOS 端点，与组件对话，并查看 sessions、traces、knowledge、memory、learning	由 SDK 侧的接口与路由支撑，见 os/interfaces

从源码结构看，SDK 的核心目录与文档描述一一对应：libs/agno/agno/ 下并列存在 agent、team、workflow、tools、knowledge、memory、learn、session、db、tracing 等模块，分别对应 SDK 层的定义能力；而 os 目录下的 app.py、routers/、auth.py、mcp.py、checkpoints.py 等文件则构成了 AgentOS 运行时的应用壳——包括鉴权（JWT 认证与 RBAC 可从 auth.py、scopes.py 等文件的存在得到印证）、MCP 集成、任务队列等生产特性。

概览文档还强调了一个重要属性：Agno 是模型无关（model-agnostic）的。一个 Agent = 一个模型 + 指令（instructions）+ 工具（tools）+ 可选上下文（如 knowledge、memory）。这一点可以从 SDK 源码直接验证：Agent 类中 model: Optional[Model] = None（agent.py）、instructions: Optional[Union[str, List[str], Callable]]（约 L248）、tools: Optional[Union[List[...], Callable[...]]]（约 L179）、knowledge（约 L156）均为独立的可注入字段。模型层的实现位于 libs/agno/agno/models/，按厂商组织子包（google、openai、anthropic、aws、azure、ollama、litellm、vllm 等数十个目录），与 cookbook/90_models/ 目录中按厂商划分的示例相对应。

二、最小工具型 Agent：约十行代码让模型"行动"起来

概览文档给出的最小示例如下：

from agno.agent import Agent
from agno.models.google import Gemini
from agno.tools.yfinance import YFinanceTools

agent = Agent(
    model=Gemini(id="gemini-3.6-flash"),
    tools=[YFinanceTools()],
)

agent.print_response("What's AAPL's current price?", stream=True)

这段代码的每个要素都值得展开：

• Agent：SDK 中最基础的构建块，来自 agno.agent。它的 __init__ 签名（agent.py 起）暴露了 model、instructions、tools、knowledge、memory 相关参数、session_id、parser_model / output_model / followup_model（用于结构化输出解析与后续建议的独立小模型）等数十个配置项，说明"最小配置"与"完整能力"共用同一个类。
• Gemini(id="gemini-3.6-flash")：模型无关设计的具体体现——换厂商只需替换 import 和实例化（如 from agno.models.openai import OpenAI），Agent 本身不需要改动。
• YFinanceTools()：工具以 Toolkit 形式注入，来自 libs/agno/agno/tools/ 下的预置工具包。在 agent_with_tools.py 中可以看到更完整的用法：

agent_with_tools = Agent(
    name="Agent with Tools",
    model=Gemini(id="gemini-3.6-flash"),
    instructions=[
        "Use Yahoo Finance for facts that can change.",
        "Lead with the answer, then show the evidence.",
        "Use a table when comparing companies.",
        "Say when data is unavailable; never invent a value.",
        "Keep the response concise and do not give personalized financial advice.",
    ],
    tools=[
        YFinanceTools(
            enable_company_info=True,
            enable_stock_fundamentals=True,
            enable_company_news=True,
        )
    ],
    add_datetime_to_context=True,
    markdown=True,
)

这里体现了概览文档所说"一个 Agent 结合模型与指令、工具、可选上下文"的完整形态：YFinanceTools 通过 enable_* 开关按需开启功能子集；instructions 可以是字符串列表；add_datetime_to_context=True 会在上下文中注入当前时间（对应 Agent 类的 add_datetime_to_context: bool = False 字段，约 L261），适合价格、新闻等时效性数据；markdown=True 控制响应以 Markdown 渲染。

• print_response(..., stream=True)：同步打印流式响应，适合本地脚本演示；在服务端场景中则由 AgentOS 运行时以 SSE / WebSocket 形式透出（见 cookbook/05_agent_os 系列示例）。

三、构建块选型：Agent、Team、Workflow 与 AgentOS 的分工

概览文档给出了四条选型原则，这是理解 Agno 架构的关键判断标准：

1. 从一个 Agent 起步——只要是一项连贯（coherent）的工作，单个 Agent 即可承担；
2. 用 Team——当独立的专家或视角确实能显著提升结果质量、且值得为此付出额外延迟和成本时；
3. 用 Workflow——当步骤必须以显式、可重复的顺序执行时；
4. 用 AgentOS——运行和巡检整个系统。

这三者分别对应源码中的三个一等公民：

3.1 Agent：单一职责的执行单元

如前所述，Agent 持有模型、指令、工具、知识、记忆等全部运行所需上下文，一次 run 即完成一轮"推理—调用工具—汇总"的循环。

3.2 Team：多 Agent 动态协作

team.py 定义了 Team 类，并引入 TeamMode 枚举（class TeamMode(str, Enum)）来区分协作模式。Team 的目录结构与 Agent 高度对称（_run.py、_session.py、_storage.py、_managers.py、_tools.py、_task_tools.py 等），说明 Team 并非简单封装，而是拥有独立的任务委派（_task_tools.py）、会话存储与记忆管理能力。概览文档中"独立专家或视角是否值得额外延迟和成本"的取舍，在 cookbook/00_quickstart/multi_agent_team.py 中有具体演示（由 leader 协调 bull/bear 两名研究员）。团队模式的更多变体可参考 cookbook/03_teams/02_modes/。

3.3 Workflow：显式顺序的编排器

workflow.py 中 class Workflow 位于约 L579，同目录还有 step.py、steps.py、router.py（条件路由）、loop.py（循环）、parallel.py（并行）、condition.py 等模块，覆盖顺序、条件、循环、并行等执行拓扑。当"步骤顺序必须可预测"时——例如采集 → 分析 → 撰写的三步市场简报——Workflow 比让 Team 自行决策更可控，对应示例见 cookbook/00_quickstart/sequential_workflow.py，更复杂的条件/CEL 表达式编排可参考 cookbook/04_workflows/。

3.4 一张对照表帮助决策

cookbook/00_quickstart/README.md 中给出的"心智模型"表格对概览文档的选型原则做了操作化补充：

概念	它拥有什么（What It Owns）	适用场景
Tools	模型可选择的动作	API、搜索、代码、数据库操作
Structured output	响应契约	流水线、API、UI、可靠解析
Storage	会话记录	后续继续同一对话
Memory	关于用户的持久事实	偏好与个性化
State	可变结构化数据	列表、计数器、购物车、任务进度
Knowledge	Agent 可检索的信息	文档、政策、产品数据、RAG
Learning	过往工作沉淀的可复用经验	共享启发式规则
Guardrails	输入输出边界	隐私、策略、校验
Human in the loop	待执行动作的审批	发布、写操作、支付、部署
Team	Agent 间的动态委派	多视角或专家分工
Workflow	显式执行顺序	可重复的多步流程

四、数据所有权：把会话、记忆、知识与追踪留在自己的数据库里

概览文档的 Data Ownership 一节指出：Agno 应用可以把 sessions、memory、knowledge、traces 保存在应用所有者自己的数据库中；生产部署应配套相应的认证、授权、租户隔离与持久化存储。

在仓库中，这一能力有清晰的实现落点：

• 存储抽象：cookbook/06_storage/ 按后端分目录提供示例——sqlite、postgres、mysql、mongo、redis、dynamodb、firestore、gcs、s3、surrealdb、singlestore、in_memory、json_db 等，说明存储是可插拔的，数据落在哪里由应用方决定；
• 运行时安全：AgentOS 运行时的 libs/agno/agno/os/ 包含 auth.py、scopes.py、service_accounts.py、middleware/ 等文件，从源码结构看支撑了文档所承诺的 JWT 认证与基于范围（RBAC）的授权，配合多用户、多租户隔离；
• 追踪与审计：libs/agno/agno/tracing/ 与 cookbook/observability/ 中的 OpenTelemetry 集成（Langfuse、LangSmith、Arize Phoenix、MLflow 等）说明 traces 同样可以流向自有或自建的观测后端；
• 本地化数据隔离：cookbook/00_quickstart/README.md 中说明各持久化示例仅写入 tmp/quickstart/，每个能力一个独立 SQLite 库或 Chroma 集合，"删除该目录即可完全重新开始"——这正是数据所有者对数据行使控制权的极简体现。

对生产部署的适用前提：概览文档强调"production deployments should use appropriate authentication, authorization, tenant isolation, and durable storage"（生产部署应使用适当的认证、授权、租户隔离和持久化存储），这与 AgentOS 运行时的认证模块（os/auth.py 等）以及各数据库后端示例共同构成该建议的实现路径，具体选型需结合实际基础设施。

五、延伸阅读：按仓库路径深入各子系统

概览文档的 "Where to Go Next" 一节指向外部文档站点与仓库本身；在本仓库内部，以下路径构成继续深入的地图（均为仓库相对路径）：

• 快速上手：cookbook/00_quickstart/——从工具型 Agent 到存储、记忆、知识、学习、护栏、人在环、Team 与 Workflow 的完整能力阶梯，最终由 run.py 把所有组件注册进同一个 AgentOS 运行时，config.yaml 为 AgentOS 聊天界面提供开箱即用的提示词；
• Agent 细节：cookbook/02_agents/——输入输出、上下文管理、工具、状态与会话、记忆与学习、知识、护栏、钩子、人在环、多模态等 22 个专题；
• Team 协作：cookbook/03_teams/——协作模式、委派、记忆共享、上下文压缩、分布式 RAG 等；
• Workflow 编排：cookbook/04_workflows/——条件执行、循环、并行、CEL 表达式、人在环；
• AgentOS 运行时：cookbook/05_agent_os/——数据库对接、运行生命周期、安全、调度、MCP、A2A、Slack/Telegram/WhatsApp 接口、部署等 25 个专题；
• 模型适配：cookbook/90_models/——按厂商组织的模型示例，验证"模型无关"的覆盖范围；
• 工具生态：cookbook/91_tools/——预置 Toolkit（GitHub、Slack、Postgres、搜索、浏览器等）与 MCP 集成；
• SDK 源码：libs/agno/agno/ 下的 agent、team、workflow、os、models、tools、knowledge、memory、learn、db、tracing 等模块，是本文所有实现结论的第一手依据；
• 贡献与测试：CONTRIBUTING.md、AGENTS.md 与 libs/agno/tests/ 测试目录，用于验证行为是否符合文档描述。

六、小结

Agno 的分层设计可以浓缩为一句话：SDK 负责"定义"，AgentOS 运行时负责"运行"，UI 负责"看见"。选型上先问"这项任务是否连贯"——是则用 Agent；问"多视角是否值得延迟与成本"——是则用 Team；问"步骤顺序是否必须显式"——是则用 Workflow；最后用 AgentOS 把整套系统跑成带会话、流式、追踪与人工审批的生产服务，并通过可插拔的存储后端把数据主权留在自己手中。仓库中 cookbook/00_quickstart/ 提供了"一个 API Key、无需 Docker、每个示例独立可运行"的完整验证路径，可将其作为上手与回归验证的基准。