# 通过 OpenAILike 把 Agno Agent 接到 Router One

> https://router.one/zh/integrations/agno 的 Markdown 镜像，供 AI 助手与爬虫使用。Router One 是 OpenAI 兼容的统一 LLM API 网关。
> 最后更新：2026-09-20

Agno 在你的应用中运行 Agent、工具和团队。OpenAILike 把其中的 Chat Completions 请求发给 Router One，Agent 循环、状态与工具执行仍由 Agno 负责。本指南基于 Agno 3.0.10 的 OpenAILike Chat Completions 适配器。

## 安装客户端，并显式设置两个变量

在 Python 环境中安装 agno 和 openai。为这个 Agent 创建专用 Router One Key，并在控制台设置 maxSpend。ROUTER_ONE_MODEL 填 /models 中当前可用的聊天模型完整 ID，保留厂商前缀。先运行下方不带工具的示例，再逐步加入应用逻辑。

`terminal`

```bash
python -m pip install "agno==3.0.10" openai
export ROUTER_ONE_API_KEY="sk-your-router-one-key"
export ROUTER_ONE_MODEL="<exact-model-id-from-/models>"
python agent.py
```

## 把 Agno 配置到 Router One base URL

从 agno.models.openai.like 导入 OpenAILike，把模型实例传给 Agent。base_url 填 https://api.router.one/v1，显式传入 api_key，id 填精确目录 ID。OpenAILike 原样发送 id：anthropic/claude-sonnet-5 前面不需要再加 openai/ 或 custom/。首次运行的示例关闭 SDK、模型层和指导性重试，方便核对请求次数。成功后可改用 agent.print_response("Say hello in one sentence.", stream=True) 开启流式；这个适配器会自动请求 stream_options.include_usage。

`agent.py`

```python
from os import environ
from agno.agent import Agent
from agno.models.openai.like import OpenAILike

agent = Agent(
    model=OpenAILike(
        id=environ["ROUTER_ONE_MODEL"],
        api_key=environ["ROUTER_ONE_API_KEY"],
        base_url="https://api.router.one/v1",
        max_retries=0,
        retries=0,
        retry_with_guidance=False,
    ),
)
agent.print_response("Say hello in one sentence.")
```

## 模型类决定请求协议

Agno 3.0.10 会把 openai:<model-id> 这样的字符串简写解析为 OpenAIResponses，而不是 OpenAILike。简写中的前缀选择适配器，与 openai/gpt-5.5 这样的 Router One 模型 ID 是两回事。本指南走 Chat Completions，因此显式构造 OpenAILike 实例。若主动换成 OpenAIResponses 或 OpenResponses，先确认所选模型及需要的功能支持 /v1/responses。模型 ID 不变，换一个类也可能改变请求端点。

## 分别核对 Agent 运行与模型请求次数

一次 Agent 运行可能在每次工具结果返回后继续调用模型。tool_call_limit 限制工具执行次数，不是 token 预算，也不限制每一种模型请求。重试也分层：max_retries 属于 OpenAI 客户端，model.retries 重发模型请求，Agent.retries 则可能重跑整个运行过程。加入会修改外部状态的工具之前，应先明确这些设置。使用带消费上限的专用 Key，再按模型、时间、tokens 和 request_id 与 Dashboard → Logs 核对；Agno 的 metrics 是用量报告，不是 Router One 的结算金额。仅凭没有日志不能证明请求没到网关：尚待定价的记录可能暂时不展示。

## 知识库的 Embedding 要单独配置

修改 Agent.model 不会顺带改掉知识库或它的 embedder。例如 Agno 官方 PgVector 示例单独配置 OpenAIEmbedder，与 Agent 模型是两个客户端。Embedding 保留在本地模型或提供该接口的供应商上；Router One 没有 /v1/embeddings。文档、检索、会话存储与工具执行仍在你的 Agno 应用中。如果另配 reasoning、parser 或 output model，也要分别指定连接参数，它们会发起额外模型请求。

## Agno 该填哪个模型 ID？

从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 Agno 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个工具单独建 API Key，并设置 maxSpend 消费上限。

## Agno 用的是哪种 API 协议？

OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

## 在 trace 里验证 Agno 的调用

先在 Agno 发出一次简单文本请求，再到 Dashboard → Logs 按时间、模型和 request_id 核对 trace：tokens、花费、延迟和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

## 常见问题

### 已经设置 OPENAI_API_KEY，为什么 OpenAILike 还是返回 401？

在 Agno 3.0.10 中，OpenAILike 的 api_key 默认值是字符串 not-provided。这个非空值会阻止 OpenAIChat 回退读取 OPENAI_API_KEY，因此不传 api_key 时实际发送的是 Authorization: Bearer not-provided。应显式写 api_key=environ["ROUTER_ONE_API_KEY"]；本地测试服务已验证这一行为。已经显式传入正确 Key 时，保留响应正文和请求 ID，再检查 Key 是否被撤销或复制错误。

### OpenAILike 会自动去掉模型 ID 的厂商前缀吗？

不会。它的 Chat Completions 实现发送 model=self.id。使用完整目录 ID，原本有 anthropic/ 或 openai/ 就保留；grok-4.6 这类 ID 本来就不带前缀。不要照搬 LiteLLM 或 Mastra 接入指南中额外添加的路由前缀。base_url 缺少 /v1 是另一种路径错误，不是模型名称的问题。

### 使用 OpenAILike 就能让每个模型都返回结构化输出吗？

不能。适配器可以构造结构化输出请求，但端点和所选模型仍需支持相应 schema 与参数。先测通普通文本，再分别验证 output_schema 和工具调用。遇到不支持的参数或 schema 错误时，应核对实际错误与模型能力，不要修改已经正确的 base URL。

### Agno 能通过网关用哪些模型？

选用当前目录中同时支持 Agno 所用端点和所需功能的模型。精确 ID、当前单价与能力以 /models 及模型详情为准；不要仅按 GPT、Claude 等系列名判断兼容性。客户端能列出模型，只证明模型发现成功，仍需验证实际调用。

### 能列出模型，但调用报 400 或 404，怎么办？

先记录实际请求路径和错误消息，再核对精确模型 ID。400 可能是参数、工具类型或模型与端点不匹配；404 可能是请求路径或资源不存在，不能直接判定模型下线。若错误提示 must be called via，按它指明的端点调整客户端 provider，或换用支持当前端点的模型。不要在所有工具里统一增删 /v1 或 /chat/completions。

### 中国大陆能直连吗？

能。网关在大陆可直连、无需 VPN，配置与全球环境完全一致。

### 报 401/402/403/429 怎么排查？

先到 Dashboard → Logs 核对请求及错误消息。401 查 Key 是否传入和有效；402 查钱包余额与 maxSpend；403 查 Key 权限和访问限制；429 查请求频率、token 限额及上游限流，按错误来源处理。保留 request_id，再按错误码速查页逐项排查。

## 相关页面

- 全部接入指南：https://router.one/zh/integrations
- Agno 的 API 错误排查：https://router.one/zh/llm-api-error-codes
- API 兼容性：端点与功能对照：https://router.one/zh/facts/api-compatibility.md
- Responses API 配置与限制：https://router.one/zh/codex-responses-api
- MaxKB 接入：https://router.one/zh/integrations/maxkb
- Pi Agent 接入：https://router.one/zh/integrations/pi
- Agent SDK 接入方式对比：https://router.one/zh/blog/openai-agents-sdk-vs-claude-agent-sdk-vs-pydantic-ai
- Mastra 接入：不同的模型前缀规则：https://router.one/zh/integrations/mastra
- Agno 官方文档：OpenAI 兼容模型：https://docs.agno.com/models/providers/openai-like
- Agno 官方文档：字符串模型与 API 选择：https://docs.agno.com/models/model-as-string
- Agno 官方文档：重试与模型配置：https://docs.agno.com/models/overview
- Agno 官方示例：PgVector 与独立 embedder：https://docs.agno.com/knowledge/agents/agentic-rag-pgvector
- 网关层负责什么：https://router.one/zh/llm-api-gateway
- OpenAI 兼容 API：https://router.one/zh/openai-compatible-api
- API 文档：https://router.one/zh/docs
- 本页规范地址：https://router.one/zh/integrations/agno
- 模型与每模型 token 价格：https://router.one/zh/models （markdown：https://router.one/zh/models.md ）
- 定价：https://router.one/zh/pricing
- API 文档（markdown）：https://router.one/zh/docs.md
- 公司事实（markdown）：https://router.one/zh/facts/company.md