在 agno 中使用 N1N 模型OpenAI 兼容集成实战指南【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno导读本文以 agno 仓库中 cookbook/90_models/n1n 的 cookbook 示例为核心讲解如何在 agno Agent 中接入 N1N 这一 OpenAI 兼容的模型提供商。你将掌握N1N模型类的环境变量配置、基础对话与流式输出、工具调用三个核心能力并通过源码级剖析理解其认证机制与底层调用链最终能够将 N1N 模型无缝替换进自己的 agno 应用中。N1N 集成概览N1N 是一个使用 OpenAI API 协议的服务提供商agno 为其提供了开箱即用的模型封装。在 agno 中N1N类位于 libs/agno/agno/models/n1n/n1n.py并在 libs/agno/agno/models/n1n/init.py 中导出。从源码结构看N1N的继承链为N1N → OpenAILike → OpenAIChat → ModelOpenAILike 是 agno 为使用 OpenAI API schema 的任何第三方提供商设计的基类因此 N1N 天然获得完整的 OpenAI 协议支持包括 Chat Completions、流式输出、结构化输出与工具调用OpenAIChat 提供底层的客户端管理与请求封装。N1N类自身的默认配置如下见 n1n.py属性默认值说明idgpt-4o模型标识可选gpt-5.6-luna、gpt-5-mini等nameN1N模型显示名称providerN1N提供商名称api_key环境变量N1N_API_KEY认证密钥未显式传入时从环境变量读取base_urlhttps://api.n1n.ai/v1API 端点地址环境准备安装与 API Key在使用 N1N 模型之前需要完成两步准备工作。第一步安装 agno 及 WebSearch 工具依赖工具调用示例需要pip install -U agno agno-tools第二步设置 N1N API Key 环境变量。N1N模型类的api_key字段通过getenv(N1N_API_KEY)读取见 n1n.pyexport N1N_API_KEYyour-api-key-here值得强调的是如果你没有设置N1N_API_KEYagno 并不会在创建 Agent 时立即报错而是在真正发起请求、调用_get_client_params()构建客户端参数时才抛出ModelAuthenticationError错误信息为 N1N_API_KEY not set. Please set the N1N_API_KEY environment variable.见 n1n.py。这一点已被 test_n1n.py 中的test_n1n_initialization_without_api_key用例明确验证。基础对话创建 Agent 并运行cookbook 示例 basic.py 演示了使用 N1N 模型创建 agno Agent 的最小完整流程核心代码只有三行from agno.agent import Agent from agno.models.n1n import N1N agent Agent(modelN1N(idgpt-5.6-luna), markdownTrue)关键点说明N1N(idgpt-5.6-luna)显式指定模型 ID。cookbook 中选用了gpt-5.6-luna实际可选 ID 以 N1N 平台提供为准省略id参数时默认使用gpt-4omarkdownTrue让 Agent 以 Markdown 格式渲染输出便于阅读。示例同时演示了同步模式与同步 流式streaming模式两种运行方式if __name__ __main__: # --- 同步模式 --- agent.print_response(Share a 2 sentence horror story.) # --- 同步 流式模式 --- agent.print_response(Share a 2 sentence horror story., streamTrue)两种模式通过print_response的stream参数切换streamFalse默认时等待完整响应后一次性打印streamTrue时启用流式输出Token 逐个到达并实时展示适合对响应延迟敏感的场景。运行 cookbook 示例README 中给出的标准命令.venvs/demo/bin/python cookbook/90_models/n1n/basic.py工具调用让 N1N Agent 联网搜索N1N 模型基于 OpenAI 协议实现函数调用能力这意味着你可以直接为 Agent 挂载 agno 工具包。cookbook 示例 tool_use.py 展示了将WebSearchTools挂载到 N1N Agent 上的完整用法from agno.agent import Agent from agno.models.n1n import N1N from agno.tools.websearch import WebSearchTools agent Agent( modelN1N(idgpt-5-mini), markdownTrue, tools[WebSearchTools()], ) agent.print_response(What is happening in France?, streamTrue)工作流程如下用户提问 What is happening in France?Agent 判断该问题需要实时信息向 N1N 模型发起包含工具定义的请求模型返回工具调用指令Agent 执行WebSearchTools检索网页检索结果回传给模型模型综合生成最终回答并流式输出。注意该示例在模块顶层直接调用agent.print_response(...)if __name__ __main__:块为空因此直接运行脚本即可触发一次完整的搜索 回答流程.venvs/demo/bin/python cookbook/90_models/n1n/tool_use.py源码级剖析N1N 的认证与客户端构建要深入理解 N1N 集成核心在 n1n.py 中的_get_client_params()方法它覆盖了OpenAIChat的同名方法专门处理 N1N 的 API Key 与基础连接参数def _get_client_params(self) - Dict[str, Any]: # 1. 若未显式传入 api_key则从环境变量获取 if not self.api_key: self.api_key getenv(N1N_API_KEY) if not self.api_key: # 2. Key 缺失时立即抛出认证错误 raise ModelAuthenticationError( messageN1N_API_KEY not set. Please set the N1N_API_KEY environment variable., model_nameself.name, ) # 3. 组装基础客户端参数 base_params { api_key: self.api_key, organization: self.organization, base_url: self.base_url, timeout: self.timeout, max_retries: self.max_retries, default_headers: self.default_headers, default_query: self.default_query, } # 4. 过滤掉值为 None 的参数避免污染 OpenAI 客户端 client_params {k: v for k, v in base_params.items() if v is not None} # 5. 允许用户通过 client_params 注入额外参数优先级最高 if self.client_params: client_params.update(self.client_params) return client_params这段代码揭示了几条重要实现事实认证优先级显式传入的api_key优先于环境变量两者皆无才抛错参数过滤值为None的字段会被剔除确保 OpenAI 客户端不会收到无效参数可扩展性timeout、max_retries、default_headers、default_query等字段均继承自 OpenAIChat可在构造N1N时直接覆盖。例如需要加大请求超时与重试次数时可这样配置from agno.agent import Agent from agno.models.n1n import N1N agent Agent( modelN1N( idgpt-5.6-luna, timeout60.0, # 请求超时秒 max_retries3, # 失败重试次数 ), markdownTrue, )客户端构建链路_get_client_params()的返回值会传入 OpenAIChat 的OpenAIClient(**client_params)与AsyncOpenAIClient(**client_params)调用用于创建同步与异步两个 OpenAI 客户端实例。因此 N1N Agent 既支持print_response同步调用也支持异步接口与官方 OpenAI 模型在 agno 中的使用体验完全一致。测试验证单元测试保障集成正确性仓库在 libs/agno/tests/unit/models/test_n1n.py 中为 N1N 集成提供了 4 个单元测试覆盖了关键行为测试用例验证内容test_n1n_initialization_with_api_key显式传入 API Key 时模型id、api_key、base_url均正确设置test_n1n_initialization_without_api_key清空环境变量后调用_get_client_params()抛出ModelAuthenticationErrortest_n1n_initialization_with_env_api_key仅设置N1N_API_KEY环境变量时模型自动读取该值test_n1n_client_params_get_client_params()返回的api_key与base_url与预期一致其中test_n1n_client_params直接断言了client_params[base_url] https://api.n1n.ai/v1从测试层面锁定了默认端点地址。这些测试可作为你验证本地环境配置是否正确的参考运行以下命令即可执行python -m pytest libs/agno/tests/unit/models/test_n1n.py -v总结与进阶方向至此你已完整掌握在 agno 中集成 N1N 模型的三步走配置安装 agno、导出N1N_API_KEY接入Agent(modelN1N(id...))用streamTrue切换流式输出增强挂载WebSearchTools等工具让模型具备实时检索能力。由于N1N完全复用 OpenAI 协议所有 agno 的通用能力——结构化输出、记忆与存储、多 Agent 团队协作、Workflow 编排等——均可直接应用于 N1N 模型无需任何额外适配。若需进一步探索可阅读 agno 的模型基类 libs/agno/agno/models/base.py 了解 Agent 与模型的完整交互契约或参考仓库中其他基于OpenAILike实现的提供商如 libs/agno/agno/models/xai、libs/agno/agno/models/openrouter对比各自的定制方式。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考