什么是AgnoAgno是一个用于构建多智能体系统Multi-Agent Systems的全栈Python框架。它的名字源于希腊语“ἁγνὸ”agno意为“纯粹”体现了其设计理念追求简单、极致性能和真正的模型无关性架构和设计理念Agno 的架构可以从两个不同的维度来理解一个是面向能力成长的“渐进式五级架构”另一个是面向生产环境的“全栈三层架构”。它们共同勾勒出 Agno 从简单智能体到生产级系统的完整蓝图。渐进式五级架构Agno采用渐进式增强模型它将智能体的能力从简单到复杂划分为五个清晰的等级。可以像升级一样从 Level 1 开始根据需求逐步叠加能力而无需重写已有代码┌─────────────────────────────────────────────────────────────┐ │ Level 5: 确定性智能体工作流 │ │ (Agentic Workflows) │ │ 用 Workflow 编排 Agent/Team/函数 │ │ 支持顺序、并行、循环流程确定且状态可追踪 │ ├─────────────────────────────────────────────────────────────┤ │ Level 4: 多智能体团队协作 │ │ (Agent Teams) │ │ 领导 成员模式多种协作策略 │ │ coordinate / route / collaborate / tasks │ ├─────────────────────────────────────────────────────────────┤ │ Level 3: 智能体 记忆 推理 │ │ (Memory Reasoning) │ │ 长期记忆用户偏好、历史思维链 (CoT) 推理 │ ├─────────────────────────────────────────────────────────────┤ │ Level 2: 智能体 知识库 存储 │ │ (Knowledge Storage) │ │ 外挂知识库 向量数据库 (RAG)支持多种文档格式 │ ├─────────────────────────────────────────────────────────────┤ │ Level 1: 基础智能体 工具 │ │ (Agents with Tools Instructions) │ │ 核心智能体 指令 工具调用 │ └─────────────────────────────────────────────────────────────┘ ▲ ▲ ▲ ▲ ▲ │ │ │ │ │ └───┴───┴───┴───┘ (能力逐层叠加)Level 1: 基础工具型智能体 (Agents with Tools Instructions)核心一个能调用工具来执行具体任务的“行动派”。能力画像通过指令 (Instructions)指导行为并配备工具 (Tools)与外部世界交互。适用场景执行单一、明确的任务如查询天气、搜索信息、调用 API 等。Level 2: 知识增强型智能体 (Agents with Knowledge Storage)核心一个拥有“外挂大脑”——知识库 (Knowledge)的专家。能力画像在 Level 1 的基础上引入了知识库 (Knowledge)和存储 (Storage)。通过 RAG检索增强生成技术智能体可以访问外部文档、数据库等实现基于特定知识库的问答。适用场景企业知识库问答、基于私有文档的客服机器人、法律/医疗文档检索等。核心组件KnowledgeVectorDb(如 PgVector, Pinecone)Level 3: 记忆推理型智能体 (Agents with Memory Reasoning)核心一个拥有“长期记忆”并能进行“深度思考”的智者。能力画像在 Level 2 的基础上增加了记忆 (Memory)和推理 (Reasoning)能力。记忆让智能体能在多轮对话中记住用户偏好和历史推理如思维链 CoT则使其能处理更复杂的逻辑问题。适用场景需要上下文理解的个人助理、需要分步解决的复杂问题如数学推理、逻辑分析等。Level 4: 多智能体团队 (Agent Teams)核心一个由多个各有所长的“专家”组成的协作团队。能力画像引入团队 (Team)概念由“领导”智能体协调多个“成员”智能体分工协作。Agno 提供了coordinate(协调)、route(路由)、collaborate(协作) 和tasks(任务) 等多种团队协作模式。适用场景需要多领域知识或步骤的复杂任务如撰写包含研究、分析和撰写的综合报告Level 5: 确定性工作流 (Agentic Workflows)核心一个将智能体能力封装在确定性流程中的“自动化产线”。能力画像引入工作流 (Workflow)通过预定义的步骤Step来编排智能体、团队和函数确保流程的状态性和确定性。它支持顺序、并行、循环等复杂逻辑。适用场景需要严格流程控制的自动化任务如定期生成报告的数据流水线、需要多步审批的自动化流程等。全栈三层架构如果说五级架构是“深度”那么三层架构就是“广度”。它从软件工程的角度展示了 Agno 如何将一个智能体应用从“能用”推向“用好”和“生产可用”。┌─────────────────────────────────────────────────────────────┐ │ Layer 3: 生产层 (Production Layer) │ │ ─── 解决 如何生产可用 │ │ 审计、治理、合规、人机回环 (HITL)、实时监控 (agno.com) │ │ 提供工具级 / 工作流级 / 审批级三层人工介入 │ ├─────────────────────────────────────────────────────────────┤ │ Layer 2: 运行时层 (Runtime - AgentOS) │ │ ─── 解决 如何执行 │ │ 高性能执行引擎、会话管理、状态持久化、异步支持 │ │ 实现微秒级实例化、超低内存占用 │ ├─────────────────────────────────────────────────────────────┤ │ Layer 1: 框架层 (Framework) │ │ ─── 解决 如何构建 │ │ Agent / Team / Workflow 原语 │ │ 工具、记忆、知识、模型、存储等模块化组件 │ └─────────────────────────────────────────────────────────────┘Layer 1: 框架层 (Framework)目标解决“如何构建 (How to build)”智能体的问题。内容提供构建智能体的核心抽象如Agent、Team、Workflow等原语以及工具调用、记忆、知识检索等基础能力。价值让开发者无需从零开始能够快速搭建智能体的核心逻辑。Layer 2: 运行时层 (Runtime - AgentOS)目标解决智能体“如何执行 (How to execute)”的问题。内容即AgentOS一个高性能的运行时环境负责处理智能体的执行、会话管理、状态存储等核心基础设施。价值确保智能体能以极致的性能和可靠性运行是 Agno 实现微秒级实例化和低内存占用的关键。Layer 3: 生产层 (Production Layer)目标解决智能体“如何生产可用 (How to run in production)”的问题。内容这是 Agno v2.5 补齐的最后一环涵盖了治理、审计、合规等生产环境必需的能力。例如内置的人机回环 (HITL)机制提供工具级、工作流级和审批级三层控制可选的编排模式将架构决策从代码中解耦以及通过agno.com提供的实时监控 (Monitoring)功能。价值填补了从“构建智能体”到“将其作为业务能力运行”之间的鸿沟让企业能够安全、合规地大规模部署智能体。核心组件Agno 是一个用于构建多智能体系统的 Python SDK。其核心组件可以分为两个层面最基础的三大原语 (Primitives)以及可以附加在这些原语上的丰富能力 (Capabilities)原语 (Primitive)核心概念关键能力最佳实践Agent (智能体)单兵作战的专家。一个能够进行推理、使用工具并维护状态的AI程序。围绕大模型构建有状态的控制循环可附加记忆、知识、存储等能力。任务单一、领域明确时。例如一个专门负责撰写邮件的助手。Team (团队)各司其职的委员会。由“领导”智能体协调多个“成员”智能体或子团队分工协作。专业化分工每个成员精通特定领域。并行处理独立子任务可同时进行。多种协作模式如coordinate(协调)、route(路由)、broadcast(广播)、tasks(任务)。任务复杂、跨越多个领域时。例如撰写一份需要市场调研、数据分析和内容创作的研究报告。Workflow (工作流)标准化的流水线。通过预定义的步骤Step来编排 Agent、Team 和函数实现确定性的流程。确定性流程和步骤是预先定义好的。丰富模式支持顺序 (Sequential)、并行 (Parallel)、条件 (Condition)、循环 (Loop) 和动态路由 (Router)。需要严格流程控制的自动化任务。例如一个定期执行的“数据提取-分析-生成报告”流水线。Agno 提供了大量的可选“能力”模块你可以根据需求将它们“安装”到 Agent、Team 或 Workflow 上。这些能力可以分为四大类模型与工具 (Model Tools)Models: 提供统一的 API可接入30 多种模型提供商。Tools: 提供100 多种内置工具如网络搜索、文件操作、API 调用并支持轻松创建自定义工具。Skills: 可组合的能力能以结构化指令的形式附加给智能体。Multimodal: 支持图像、音频、视频等多模态数据的输入和输出。Structured I/O: 使用 Pydantic 模型实现类型安全的输入和输出。记忆与上下文 (Memory Context)Storage: 提供会话、记忆等数据的持久化存储。Sessions: 管理多轮对话包含摘要、历史和指标。Memory: 支持按用户和按会话的记忆让智能体“记住”过去。Knowledge:知识库支持对文档、URL、数据库等进行检索增强生成 (RAG)。Learning: 让智能体通过经验不断改进和学习。Compression: 压缩上下文确保长会话不超出模型窗口限制。控制与安全 (Control Safety)Guardrails: 对输入和输出进行校验确保行为符合预期。Hooks: 生命周期钩子可在特定节点注入自定义逻辑。Human-in-the-Loop (HITL):人机回环可暂停运行以等待人工审批、输入或外部执行。运维与可观测性 (Operations Observability)Background execution: 支持长时间运行的后台任务。Evals: 用于评估智能体的准确性、性能和可靠性。Observability: 集成 Langfuse、Logfire 等 12 多种追踪工具。Scheduler: 支持按计划定时运行 Agent。智能体构建环境搭建#0.安装python建议Python3.10最好3.12 #1.新建项目文件夹agno-learn #2.进入项目文件夹使用uv初始化项目 uv init #3.安装依赖 uv add agno openai pycountry baidusearch #4.环境变量配置新建.env文件配置如下 DEEPSEEK_API_KEYxxx QWEN_API_KEYxxx #5.新建src文件夹作为代码目录版本(agno-learn) applelocalhost agno-learn % uv pip list Package Version ------------------ --------- agno 2.6.22 annotated-doc 0.0.4 annotated-types 0.7.0 anyio 4.14.1 baidusearch 1.0.3 beautifulsoup4 4.15.0 certifi 2026.6.17 charset-normalizer 3.4.7 distro 1.9.0 docstring-parser 0.18.0 gitdb 4.0.12 gitpython 3.1.50 h11 0.16.0 h2 4.3.0 hpack 4.2.0 httpcore 1.0.9 httpx 0.28.1 hyperframe 6.1.0 idna 3.18 jiter 0.16.0 lxml 6.1.1 markdown-it-py 4.2.0 mdurl 0.1.2 openai 2.44.0 packaging 26.2 pycountry 26.2.16 pydantic 2.13.4 pydantic-core 2.46.4 pydantic-settings 2.14.2 pygments 2.20.0 python-dotenv 1.2.2 python-multipart 0.0.32 pyyaml 6.0.3 requests 2.34.2 rich 15.0.0 shellingham 1.5.4 smmap 5.0.3 sniffio 1.3.1 soupsieve 2.8.4 tqdm 4.68.3 typer 0.26.8 typing-extensions 4.16.0 typing-inspection 0.4.2 urllib3 2.7.0构建智能体简单的智能体from agno.agent import Agent from agno.models.deepseek import DeepSeek from dotenv import load_dotenv load_dotenv() deepseek DeepSeek(iddeepseek-chat) # 创建智能体 agent Agent( name助手, modeldeepseek, instructions[你是一个智能助手], markdownTrue ) # 运行智能体 agent.print_response(你好请介绍一下自己, streamTrue)调用工具的智能体from agno.agent import Agent from agno.models.deepseek import DeepSeek from agno.tools.baidusearch import BaiduSearchTools from dotenv import load_dotenv load_dotenv() deepseek DeepSeek(iddeepseek-chat) agent Agent( name网络搜索助手, modeldeepseek, tools[BaiduSearchTools()], instructions[你是一个智能助手可以调用工具来执行操作。], ) resp agent.run(搜索一下agno教程) print(resp.content)代码结构详解Agent参数说明1. 核心标识与模型参数类型说明modelOptional[Union[Model, str]]主语言模型实例或标识符fallback_modelsOptional[List[Union[Model, str]]]备用模型列表主模型失败时尝试fallback_configOptional[FallbackConfig]精细降级策略配置nameOptional[str]Agent 名称idOptional[str]Agent 唯一 ID自动生成2. 用户与会话参数说明user_id当前用户 IDsession_id会话 ID跨运行保持上下文session_state会话状态字典持久化add_session_state_to_context是否将 session_state 注入上下文overwrite_db_session_state是否覆盖数据库中的状态默认合并enable_agentic_state是否提供工具让 Agent 动态更新 session_statecache_session是否在内存中缓存会话search_past_sessions是否允许搜索历史会话num_past_sessions_to_search最多搜索的历史会话数num_past_session_runs_in_search每个历史会话中读取的运行数3. 记忆与摘要参数说明memory_manager记忆管理器实例enable_agentic_memory是否允许 Agent 自主管理用户记忆update_memory_on_run运行结束后是否更新用户记忆enable_user_memories已弃用用上面替代add_memories_to_context是否将记忆注入上下文enable_session_summaries是否生成会话摘要session_summary_manager摘要管理器add_session_summary_to_context是否将会话摘要注入上下文4. 数据库与存储参数说明db数据库连接BaseDb 或 AsyncBaseDbcheckpoint检查点策略runs / tool-batch / tools5. 历史消息参数说明add_history_to_context是否将历史消息添加到当前上下文num_history_runs包含的历史运行数num_history_messages包含的历史消息数与 runs 二选一max_tool_calls_from_history从历史中提取的工具调用数量上限6. 知识库Knowledge RAG参数说明knowledge知识库实例或返回知识库的工厂knowledge_filters检索时的过滤条件enable_agentic_knowledge_filters是否允许 Agent 自主调整过滤器add_knowledge_to_context是否将检索到的知识注入上下文knowledge_retriever自定义检索函数替代默认references_format引用格式json / yaml7. 技能Skills参数说明skillsSkills 实例结构化指令、参考文档等8. 工具与调用参数说明tools工具列表或返回工具列表的可调用工厂tool_call_limit单次运行最大工具调用次数tool_choice控制工具选择auto/none/指定函数tool_hooks工具调用前后的钩子函数9. 钩子Hooks参数说明pre_hooks运行前执行的钩子含护栏、评估post_hooks运行后执行的钩子10. 推理Reasoning参数说明reasoning是否启用逐步推理CoTreasoning_model推理专用模型reasoning_agent自定义推理 Agentreasoning_min_steps最少推理步骤reasoning_max_steps最多推理步骤11. 默认工具参数说明read_chat_history是否添加“读取聊天历史”工具search_knowledge是否添加“搜索知识库”工具Agentic RAGadd_search_knowledge_instructions是否在系统提示中添加搜索指令update_knowledge是否添加“更新知识库”工具read_tool_call_history是否添加“读取工具调用历史”工具send_media_to_model是否将媒体图片等传给模型store_media是否在运行输出中存储媒体store_tool_messages是否存储工具调用消息store_history_messages是否存储完整历史消息默认仅当前运行12. 系统消息与指令参数说明system_message直接提供系统消息字符串/函数/Messagesystem_message_role系统消息角色默认 systemintroductionAgent 的第一条自我介绍消息build_context是否自动构建上下文descriptionAgent 简短描述添加到系统提示instructions指令字符串/列表/函数use_instruction_tags是否用instructions标签包裹指令expected_output对输出的描述additional_context额外上下文追加到系统提示末尾markdown是否要求模型输出 Markdownadd_name_to_context是否将 Agent 名称加入系统提示add_datetime_to_context是否加入当前日期时间add_location_to_context是否加入位置信息datetime_format自定义日期时间格式timezone_identifier时区标识符resolve_in_context是否解析上下文中的占位符如 session_state13. 学习Learning参数说明learning学习机器实例或布尔值启用学习add_learnings_to_context是否将学习内容加入上下文14. 额外消息与用户消息参数说明additional_input在系统消息后插入的额外消息few-shotuser_message_role用户消息角色默认 userbuild_user_context是否构建用户上下文15. 重试与输出解析参数说明retries失败重试次数delay_between_retries重试间隔秒exponential_backoff是否指数退避parser_model用于解析主模型输出的辅助模型parser_model_prompt解析模型的提示词input_schema输入验证的 Pydantic 模型output_schema强制输出符合的 Pydantic 模型或 JSON Schemaparse_response是否自动解析为 output_schemaoutput_model用于生成最终输出的模型output_model_prompt输出模型的提示词structured_outputs是否使用模型原生结构化输出use_json_mode是否强制 JSON 输出通过提示save_response_to_file将响应保存到文件路径16. 后续追问Follow-ups参数说明followups是否生成后续追问num_followups追问数量followup_model用于生成追问的模型17. 流式与事件参数说明stream是否启用流式响应stream_events是否发送中间事件store_events是否在 RunOutput 中存储事件events_to_skip跳过的事件类型列表18. 团队/工作流集成参数说明role作为团队成员时的角色team_id所属团队 IDworkflow_id所属工作流 ID19. 元数据与实验特性参数说明metadata任意元数据字典culture_manager文化知识管理器enable_agentic_culture是否允许 Agent 管理文化知识update_cultural_knowledge是否自动更新文化知识add_culture_to_context是否将文化知识注入上下文compress_tool_results是否压缩工具结果节省上下文compression_manager压缩管理器20. 调试与工厂缓存参数说明debug_mode是否开启调试日志debug_level调试详细程度1/2telemetry是否发送匿名使用统计cache_callables是否缓存工厂返回结果callable_tools_cache_key自定义工具缓存键函数callable_knowledge_cache_key自定义知识缓存键函数方法及说明1. 核心执行运行方法说明run(input, ...)同步运行返回RunOutput或流式迭代器。支持工具调用、知识检索等完整流程。arun(input, ...)异步运行返回Coroutine[RunOutput]或异步迭代器。continue_run(run_response, ...)恢复中断的运行用于 HITL。可从指定run_id或RunOutput继续。acontinue_run(...)异步版本。cancel_run(run_id)静态方法取消正在运行的运行同步。acancel_run(run_id)异步取消。2. CLI 交互方法说明print_response(input, ...)在控制台以美观格式打印响应支持流式、Markdown。aprint_response(...)异步版本。cli_app(input, ...)启动交互式命令行对话应用。acli_app(...)异步版本。3. 会话管理方法说明get_session(session_id, user_id)获取会话对象AgentSession。aget_session(...)异步版本。save_session(session)保存会话到数据库。asave_session(session)异步版本。rename(name, session_id)重命名会话。set_session_name(session_id, autogenerate, session_name)设置会话名称可自动生成。aset_session_name(...)异步版本。generate_session_name(session)使用 LLM 生成会话名称。get_session_name(session_id)获取会话名称。aget_session_name(...)异步版本。get_session_state(session_id)获取会话状态字典。aget_session_state(...)异步版本。update_session_state(session_state_updates, session_id)更新会话状态合并。aupdate_session_state(...)异步版本。get_session_metrics(session_id)获取会话指标运行次数、耗时等。aget_session_metrics(...)异步版本。delete_session(session_id, user_id)删除会话。adelete_session(...)异步版本。get_session_messages(...)获取会话中的历史消息可过滤。aget_session_messages(...)异步版本。get_chat_history(session_id, last_n_runs)获取对话历史用户助手消息。aget_chat_history(...)异步版本。get_session_summary(session_id)获取会话摘要。aget_session_summary(...)异步版本。fork_session(source_session_id, user_id)复制一个现有会话到新会话深拷贝返回新 session_id。afork_session(...)异步版本。4. 运行结果读取方法说明get_run_output(run_id, session_id, user_id)根据 run_id 获取某次运行的输出。aget_run_output(...)异步版本。get_last_run_output(session_id)获取会话最后一次运行的输出。aget_last_run_output(...)异步版本。5. 记忆与文化知识方法说明get_user_memories(user_id)获取当前用户的长期记忆。aget_user_memories(...)异步版本。get_culture_knowledge()获取文化知识列表。aget_culture_knowledge()异步版本。6. 工具与知识操作方法说明add_tool(tool)动态添加一个工具。set_tools(tools)替换整个工具列表。get_tools(run_response, run_context, session, user_id)运行时获取工具列表处理工厂缓存。aget_tools(...)异步版本。add_to_knowledge(query, result)将内容添加到知识库若update_knowledgeTrue。get_relevant_docs_from_knowledge(query, ...)从知识库检索相关文档。aget_relevant_docs_from_knowledge(...)异步版本。clear_callable_cache(kind, close)清除工具或知识的工厂缓存。aclear_callable_cache(...)异步版本。7. 系统消息构建方法说明get_system_message(session, run_context, tools, ...)构建系统消息整合 description、instructions 等。aget_system_message(...)异步版本。8. 持久化与序列化方法说明to_dict()将 Agent 配置序列化为字典。from_dict(cls, data, registry)类方法从字典反序列化创建 Agent。save(db, stage, label, notes)将 Agent 配置保存到数据库。load(cls, id, db, registry, label, version)类方法从数据库加载 Agent。delete(db, hard_delete)从数据库删除 Agent 配置。9. 初始化与工具方法说明set_id()生成唯一 ID若未提供。initialize_agent(debug_mode)初始化 Agent 内部状态模型、工具等。deep_copy(update)创建 Agent 的深度副本可更新部分属性。save_run_response_to_file(...)将运行输出保存到文件。scrub_run_output_for_storage(run_response)清理运行输出中的敏感/冗余信息存储前。10. 其他辅助方法说明background_executor属性返回后台线程池执行器用于异步任务。cached_session属性返回缓存的会话对象。learning_machine属性返回学习机器实例惰性初始化。