NanoGPT API 构建 AI Agent 实战指南

为什么用 NanoGPT 构建 AI Agent

AI Agent 正在取代传统脚本式自动化——不再是一个脚本只做一件事，而是让模型自己推理、决策、调用工具完成任务。NanoGPT 的 API 让这个过程变得低门槛且成本可控。

它的核心优势在于：OpenAI 兼容接口，几乎零迁移成本；一个 API Key 访问 100+ 模型；支持按任务复杂度灵活路由，控制成本。

据原文介绍，这套方案基于 Python 3.10+ 和 openai 包即可跑起来，无需额外 SDK。

环境准备与初始化

需要准备三样东西：一个 NanoGPT 账号、Python 3.10+、以及 openai Python 包。

pip install openai

初始化客户端时，关键是设置 base_url 指向 NanoGPT 的兼容端点：

import openai

client = openai.OpenAI(
    api_key="your-nanogpt-key",
    base_url="https://nano-gpt.com/api/v1"
)

这里的设计哲学很清晰——复用 OpenAI 的 SDK 生态，开发者不需要学习新接口，已有的调用经验直接迁移过来。

构建第一个文件管理 Agent

原文给出的示例是一个文件管理 Agent，通过 Function Calling 让模型自己决定调用 rename_file 还是 list_files。

核心结构分三部分：在 __init__ 中定义 tools（JSON Schema 描述函数名、参数、必填字段），run 方法把用户指令和 tools 一起发给模型，然后返回模型的消息内容。

response = self.client.chat.completions.create(
    model="openai/gpt-6.1-sol",
    messages=[
        {"role": "system", "content": "You are a file management assistant."},
        {"role": "user", "content": instruction}
    ],
    tools=self.tools
)

调用时只需一句：agent.run("List all Python files in the current directory")。

提一嘴，原文这个示例省略了 tool_calls 的实际执行与结果回传环节——真正生产环境中，你需要在拿到模型的 function call 后执行对应函数，再把结果作为 tool 消息回传给模型，形成完整闭环。

Function Calling 的执行闭环是理解 Agent 与普通聊天机器人的分水岭。模型本身并不执行代码，它只是在响应中返回一个 tool_calls 数组，其中包含函数名和 JSON 格式的参数。开发者需要在自己的代码里解析这个数组，用 json.loads 取出参数，再调用本地真实存在的 rename_file 或 list_files 函数。函数执行完毕后，必须把返回值包装成一条 role 为 tool、并携带对应 tool_call_id 的消息追加到对话历史中，再次发起请求，模型才会基于执行结果生成最终答复。这个「请求—返回工具调用—本地执行—回传结果—再请求」的循环就是所谓的 agentic loop，缺少任何一步都会让 Agent 停留在「只说不做」的状态。

多模型路由：一个 API 调用 100+ 模型

原文把「一个 API 访问 100+ 模型」称为 NanoGPT 的杀手级特性。这带来的实际价值是：可以为不同任务分配不同模型。

比如复杂推理任务用 openai/o3-pro，简单任务用 openai/gpt-6.1-mini，再写一个 router 根据指令长度或关键词自动分流：

def router(instruction, client):
    if len(instruction) > 500 or "analyze" in instruction.lower():
        return smart_agent(instruction, client)
    return fast_agent(instruction, client)

这种「快慢模型分离」的架构思路，在成本敏感的场景下非常实用——大部分请求用便宜快速的模型处理，只有少数复杂请求才调用高成本推理模型。

从工程角度看，router 的判断逻辑可以做得更精细，比如基于意图分类、token 预估或历史成功率动态调整，原文的简单启发式只是一个起点。

Router 的两种典型实现路径值得展开：一是规则启发式，即原文演示的按指令长度、关键词或正则匹配分流，优点是零延迟、零额外成本、行为可预测；二是模型辅助路由，先用一个轻量模型对用户意图做分类（如「查询类」「推理类」「生成类」），再据此选择下游模型，准确率更高但会引入一次额外调用。工业界常见的折中是先用规则兜底，再对模糊样本启用分类模型，并结合 token 预估和历史成功率做动态调整。值得注意的是，路由判断本身也会消耗 token，当任务本身很短时，路由开销占比可能反而变大，因此不应把分流逻辑做得过于复杂。

成本优化的两个杠杆

原文强调了两个降低成本的抓手。

一是模型路由本身：简单任务走快模型，复杂任务才用强模型。这是结构性省钱。

二是通过推荐链接注册可获得符合条件的用量 5% 折扣。原文末尾也明确标注了本文使用推荐链接。

对于需要长期跑 Agent 的开发者来说，成本往往是决定项目能否持续的关键变量，模型路由带来的节省通常比折扣更显著。

这套方案的取舍

优点明确：OpenAI 兼容意味着生态工具（LangChain、LlamaIndex 等）可以直接对接；多模型访问带来灵活性；入门门槛低。

需要留意的地方：原文示例偏向入门，缺少 tool call 执行闭环、错误重试、并发控制等生产级要素；模型名称（如 openai/gpt-6.1-sol）属于平台侧映射，实际可用型号需以平台文档为准。

如果你正在寻找一个低成本试水 AI Agent 的入口，NanoGPT 的 OpenAI 兼容接口是一个务实的选择——先用起来，再逐步补齐工程细节。

OpenAI 兼容接口的实质是协议级兼容：只要服务端实现了 /v1/chat/completions 等标准端点，并接受相同的鉴权头与请求体结构，任何为 OpenAI 编写的 SDK 与框架都能无感切换，只需替换 base_url 与 api_key。这解释了两件事：其一是 LangChain、LlamaIndex 等工具能直接对接，因为它们底层同样调用这套协议；其二是不同平台的「模型名」只是别名映射，openai/gpt-6.1-sol 这类字符串是平台侧的路由标识，并不等于上游真实版本号。生产环境中应先通过 /v1/models 端点或平台文档确认真实可用型号，避免因模型下线或改名导致调用失败。