
在 Agno 中通过 Cloudflare AI Gateway 统一接入 Workers AI 与多厂商模型【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agnoCloudflare AI Gateway 对外暴露一个 OpenAI 兼容的统一 API让你只通过一个端点即可调用多家模型厂商只需要把 model id 设置为vendor/model的形式。本 cookbook 指南围绕 Agno 框架中的Cloudflare模型类展开默认使用 Workers AI只需 Cloudflare API token 与 account id无需 OpenAI 或其他厂商密钥同时讲解如何为openai/...、anthropic/...、google/...等其他厂商配置 BYOK 密钥、如何用cloudflare:...字符串语法快速切换模型、以及如何规避 No such modelHTTP 400这类常见错误。读完本文你将能在一个 Agno Agent 中稳定调用 Workers AI 托管模型、结构化输出与工具调用能力并通过 AI Gateway 的动态路由实现模型切换与回退。1. 前置概念AI Gateway 的统一 API 与 Workers AI 模型绑定Cloudflare AI Gateway 的 Chat Completion 统一 API 以 OpenAI 兼容协议收口多个上游厂商模型 id 形如vendor/model。本 cookbook 默认使用Workers AI其好处是只需要 Cloudflare 侧凭证即可完成端到端调用而openai/...、anthropic/...等其他厂商路由还需要在 Cloudflare 控制台配置 BYOKBring Your Own Key密钥。Workers AI 模型在模型目录model catalog中使用绑定 idbinding id格式如cf/google/gemma-4-26b-a4b-it。AI Gateway 的兼容端点要求的是workers-ai/binding形式。Agno 的Cloudflare模型类会自动完成这一映射。1.1 源码中的模型 id 归一化逻辑在 libs/agno/agno/models/cloudflare/cloudflare.py 中normalize_cloudflare_gateway_model_id()实现了三种输入的归一路径以cf/开头的绑定 id如cf/google/gemma-4-26b-a4b-it自动在前面拼接workers-ai/得到workers-ai/cf/google/gemma-4-26b-a4b-it已经以workers-ai/开头的完整形式原样保留其他厂商路由openai/...、google/...、dynamic/...不做改动。默认模型常量定义在 cloudflare.pyDEFAULT_GATEWAY_MODEL cf/meta/llama-3.3-70b-instruct-fp8-fast对应的单元测试见 libs/agno/tests/unit/utils/test_model_string.py验证了cloudflare:workers-ai/...字符串解析和cf/...绑定 id 归一化两种路径。2. 环境准备虚拟环境与凭证导出2.1 创建并激活虚拟环境参照仓库的 Development setup 文档CONTRIBUTING.md创建并激活虚拟环境。2.2 导出凭证export CLOUDFLARE_API_TOKEN*** export CLOUDFLARE_ACCOUNT_ID*** # 可选默认使用自动创建的 default gateway # export CLOUDFLARE_AI_GATEWAY_IDmy-gateway需要在 Cloudflare 控制台创建一个具有 AI Gateway 使用权限的 API token用于你的账号。从源码看这三个环境变量的读取逻辑集中在 cloudflare.py 的_get_client_params()中CLOUDFLARE_API_TOKEN作为 OpenAI 客户端 api_key缺失时抛出ModelAuthenticationErrorCLOUDFLARE_ACCOUNT_ID用于拼接 base_url缺失时抛出ModelProviderErrorCLOUDFLARE_AI_GATEWAY_ID可选默认default。最终请求 URL 构成为https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat若显式传入base_url则 account_id 与 gateway_id 不再参与 URL 拼接。2.3 安装依赖uv pip install -U openai agnoCloudflare模型类继承自OpenAILike见 cloudflare.py依赖 openai 客户端因此openai与agno都需要安装。3. 运行基础示例python cookbook/90_models/cloudflare/basic.pycookbook/90_models/cloudflare/basic.py 演示了四种调用方式import asyncio from agno.agent import Agent from agno.models.cloudflare import Cloudflare agent Agent( modelCloudflare(cf/meta/llama-3.3-70b-instruct-fp8-fast), markdownTrue, ) if __name__ __main__: # --- 同步 --- agent.print_response(Share a 2 sentence horror story) # --- 同步 流式 --- agent.print_response(Share a 2 sentence horror story, streamTrue) # --- 异步 --- asyncio.run(agent.aprint_response(Share a 2 sentence horror story)) # --- 异步 流式 --- asyncio.run(agent.aprint_response(Share a 2 sentence horror story, streamTrue))根据 cookbook/90_models/cloudflare/TEST_LOG.md该示例在cf/meta/llama-3.3-70b-instruct-fp8-fast上四种调用模式均通过返回一段两句话恐怖故事无错误。3.1 默认模型Workers AIAgno 的Cloudflare模型类默认指向一个 Workers AI 聊天模型因此基础示例仅凭 Cloudflare 凭证即可运行。如果默认 id 发生变化请以 Workers AI 模型目录https://developers.cloudflare.com/workers-ai/models/中的实际 id 为准。3.2 构造 Workers AI 的id在模型目录中打开一个Text generation模型例如 gemma-4-26b-a4b-it。在页面中复制模型绑定 id格式如cf/google/gemma-4-26b-a4b-it。原样粘贴到 Agno 中Cloudflare(idcf/google/gemma-4-26b-a4b-it) # 或者使用字符串语法 Agent(modelcloudflare:cf/google/gemma-4-26b-a4b-it)Agno 会自动把cf/...转成workers-ai/cf/...传给 AI Gateway如果你自己拼写完整的workers-ai/cf/...形式同样可用。注意Workers AI 提供的是 Gemma 以及 Google 托管的其他开放权重模型并不暴露任意的 Gemini API 名称。若要通过网关调用 Gemini请使用统一 API 文档中的google/...模型字符串并在控制台配置 Google BYOK。4. 其他厂商BYOK 模式形如openai/...、anthropic/...的模型会被网关转发到对应厂商。需要在 Cloudflare 控制台AI Gateway / stored keys添加厂商的 API key否则上游可能返回401。此外如果网关 provider 名称不受支持可能会看到Invalid providerHTTP 400错误。5. 字符串模型语法# 直接粘贴目录绑定Agno 自动加 workers-ai/ 前缀 Agent(modelcloudflare:cf/google/gemma-4-26b-a4b-it) # 或使用完整网关形式 Agent(modelcloudflare:workers-ai/cf/meta/llama-3.3-70b-instruct-fp8-fast)字符串语法中只有第一个冒号用于切分 provider 与 model id因此cf/...中的冒号不会被误切。6. 切换模型与 OpenRouter 思路一致OpenRouterCloudflare AI Gateway选择一条路由OpenRouter(idanthropic/claude-3.5-sonnet)Cloudflare(idcf/google/gemma-4-26b-a4b-it)目录粘贴或Cloudflare(idworkers-ai/cf/...)字符串辅助Agent(modelopenrouter:...)Agent(modelcloudflare:cf/...)只有第一个:切分 provider 与 idHTTP body 中的额外回退models[...]OpenRouter 专有兼容端点不支持请使用 Dynamic routes 并配置iddynamic/route运行python cookbook/90_models/cloudflare/switch_model.py查看具体示例。cookbook/90_models/cloudflare/switch_model.py 依次演示了from agno.agent import Agent from agno.models.cloudflare import DEFAULT_GATEWAY_MODEL, Cloudflare ALT_WORKERS_MODEL cf/google/gemma-4-26b-a4b-it if __name__ __main__: # 默认 Workers AI 模型不传 id Agent(modelCloudflare(), markdownTrue).print_response(Say hello in five words.) # 与 OpenRouter 相同把网关路由字符串传给 id Agent(modelCloudflare(idDEFAULT_GATEWAY_MODEL), markdownTrue).print_response( Say hello in five words. ) # 切换模型用不同 id 新建客户端实例 Agent(modelCloudflare(idALT_WORKERS_MODEL), markdownTrue).print_response( Say hello in five words. ) # 字符串语法第一个冒号之后的部分即为网关 model id Agent( modelfcloudflare:{ALT_WORKERS_MODEL}, markdownTrue, ).print_response(Say hello in five words.) # 在 Cloudflare 控制台配置的动态路由示例 id 仅作说明 # Agent(modelCloudflare(iddynamic/my-route), markdownTrue).print_response(...)根据 TEST_LOG默认模型与备选模型cf/google/gemma-4-26b-a4b-it均正常响应字符串简写路径也会正确归一化为workers-ai/cf/...。7. 常见错误No such model400Workers AI 绑定 id 必须与模型目录完全一致例如cf/meta/llama-3.1-8b-instruct或完整的workers-ai/cf/...形式。凭空拼造的路径如cf/meta/google/gemini-...会直接失败。如果需要通过统一 API 调用 GoogleGemini请使用google/...网关模型 id 并配置 BYOK而不是杜撰一个不存在的 Workers AI slug。8. 进阶实战工具调用与结构化输出除基础对话外同目录下还有两个可直接运行的进阶示例。8.1 工具调用tool_use.pycookbook/90_models/cloudflare/tool_use.py 演示了通过/compat端点使用工具调用import asyncio from agno.agent import Agent from agno.models.cloudflare import Cloudflare from agno.tools.websearch import WebSearchTools agent Agent( modelCloudflare(idcf/zai-org/glm-4.7-flash), tools[WebSearchTools()], markdownTrue, add_datetime_to_contextTrue, ) if __name__ __main__: agent.print_response(Whats happening in France?) agent.print_response(Whats happening in France?, streamTrue) asyncio.run(agent.aprint_response(Whats happening in France?, streamTrue))网关会原样转发 OpenAI 的tools/tool_callsschema但上游 Workers AI 模型必须支持函数调用。测试日志指出多个具备函数调用能力的模型在工具调用上表现不一最终选定cf/zai-org/glm-4.7-flash——它在工具调用循环和回答质量上最干净部分较大的 MoE 模型会在工具调用后死循环或返回空的 assistant turn。需要先安装ddgsuv pip install ddgs8.2 结构化输出structured_output.pycookbook/90_models/cloudflare/structured_output.py 演示了两种结构化输出路径from typing import List from agno.agent import Agent from agno.models.cloudflare import Cloudflare from pydantic import BaseModel, Field class MovieScript(BaseModel): setting: str Field(..., descriptionProvide a nice setting for a blockbuster movie.) ending: str Field( ..., descriptionEnding of the movie. If not available, provide a happy ending. ) genre: str Field( ..., descriptionGenre of the movie. If not available, select action, thriller or romantic comedy., ) name: str Field(..., descriptionGive a name to this movie) characters: List[str] Field(..., descriptionName of characters for this movie.) storyline: str Field(..., description3 sentence storyline for the movie. Make it exciting!) # 使用 JSON 模式的 Agent json_mode_agent Agent( modelCloudflare(idcf/google/gemma-4-26b-a4b-it), descriptionYou write movie scripts., output_schemaMovieScript, use_json_modeTrue, ) # 使用原生结构化输出的 Agent structured_output_agent Agent( modelCloudflare(idcf/google/gemma-4-26b-a4b-it), descriptionYou write movie scripts., output_schemaMovieScript, ) json_mode_agent.print_response(New York) structured_output_agent.print_response(New York)关键结论来自 TEST_LOGWorkers AI 不会在服务端强制校验response_format/json_schema因此模型本身的能力比开关标志更重要。测试发现granite-4.0-h-micro仅 JSON 模式可用原生结构化输出不可用gpt-oss-20b仅原生模式可用JSON 模式不可用gpt-oss-120b、llama-4-scout-17b-16e-instruct、llama-3.3-70b-instruct-fp8-fast两种模式均失败cf/google/gemma-4-26b-a4b-it在两种模式下都稳定是性价比最优的选择。9. 小结通过 Agno 的Cloudflare模型类接入 Cloudflare AI Gateway只需一次配置即可获得 OpenAI 兼容的统一 API 体验默认 Workers AI 模型无需任何第三方密钥凭证仅需CLOUDFLARE_API_TOKEN与CLOUDFLARE_ACCOUNT_IDcf/...绑定 id 会被自动归一化为workers-ai/cf/...归一化源码其他厂商走vendor/model路由并依赖控制台 BYOK 密钥模型切换沿用 OpenRouter 式的id字符串思路回退与 A/B 分流请使用 AI Gateway 动态路由iddynamic/route结构化输出与工具调用对模型选型敏感建议以 TEST_LOG.md 中的实测结果为准。相关代码与测试可进一步查看basic.py、switch_model.py、structured_output.py、tool_use.py 及模型实现 cloudflare.py。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考