CrewAI OpenAI 兼容路由器：一键搞定多智能体工作流

当您希望多个 CrewAI 智能体使用一个网关边界，而不是将提供商密钥、基础 URL 和模型别名分散到工作流中的每个角色时，设置 CrewAI OpenAI 兼容路由器 非常有用。

CrewAI 当前的 LLM 文档展示了两种重要的 OpenAI 兼容端点设置路径：环境变量（如 OPENAI_API_BASE）和显式 LLM(...) 属性（如 model、base_url 和 api_key）。Flatkey 正好适用于这个边界。其公共站点将 OpenAI 兼容的客户端指向 https://router.flatkey.ai/v1，并在产品仪表板中提供用量、成本、路由和错误审查功能。

本指南展示了一个用于多智能体工作流的实用 CrewAI OpenAI 兼容路由器 模式。代码是一个模板：在路由生产智能体之前，请使用您自己的 Flatkey 密钥验证确切的模型别名、工具行为和日志。

CrewAI OpenAI 兼容路由器的快速解答

使用一个网关 API 根目录和明确的路由名称。不要将路由信息隐藏在提示文本中。

这就是 CrewAI OpenAI 兼容路由器 模式的核心：让 CrewAI 负责编排，让 Flatkey 负责 OpenAI 兼容的网关边界，并使运营检查可见。

为什么多智能体工作流需要网关边界

CrewAI 工作流通常以一个简单的结构开始：一个管理者智能体、几个专家智能体和一个最终任务。在工作流从演示版转变为其他团队依赖的服务之前，这种方式是可行的。

生产环境中的多智能体系统通常需要的不仅仅是一个能正常工作的响应：

对于相关的设计控制，请参阅 Flatkey 的 AI 智能体网关控制指南。一个 CrewAI OpenAI 兼容路由器 应该为每个智能体角色具体化这些控制措施。

第 1 步：创建 Flatkey 路由值

为此工作负载创建一个 Flatkey 密钥，并将路由值置于源代码控制之外。

FLATKEY_API_KEY=sk-fk-your-key
FLATKEY_BASE_URL=https://router.flatkey.ai/v1
FLATKEY_DEFAULT_MODEL=your-default-flatkey-model-alias
FLATKEY_PLANNER_MODEL=your-planner-model-alias
FLATKEY_TOOL_MODEL=your-tool-capable-model-alias
FLATKEY_VERIFIER_MODEL=your-verifier-model-alias

将 API 根目录与端点路径分开。CrewAI 的 LLM 对象应接收基础 URL。直接的 curl 测试会添加 /chat/completions。

curl "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_DEFAULT_MODEL"'",
    "messages": [
      { "role": "user", "content": "Reply with exactly: flatkey route ok" }
    ]
  }'

如果此直接请求失败，请先修复 Flatkey 密钥、模型别名、端点族或账户路由。CrewAI OpenAI 兼容路由器 无法补偿网关账户无法调用的模型别名。

第 2 步：显式配置 CrewAI LLM 对象

CrewAI 支持通过 base_url 为 LLM 设置基础 API URL，其文档展示了通过环境变量或 LLM 类属性来设置 OpenAI 兼容的 LLM。对于生产工作，显式的 LLM 对象更易于审查，因为每个智能体角色都指向一个已知的路由。

import os

from crewai import Agent, Crew, LLM, Process, Task


BASE_URL = os.environ.get("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1")
API_KEY = os.environ["FLATKEY_API_KEY"]


def flatkey_llm(model_env: str, temperature: float = 0.2) -> LLM:
    return LLM(
        model=os.environ[model_env],
        base_url=BASE_URL,
        api_key=API_KEY,
        temperature=temperature,
    )


planner_llm = flatkey_llm("FLATKEY_PLANNER_MODEL", temperature=0.1)
tool_llm = flatkey_llm("FLATKEY_TOOL_MODEL", temperature=0.0)
verifier_llm = flatkey_llm("FLATKEY_VERIFIER_MODEL", temperature=0.0)

这是 **CrewAI OpenAI 兼容路由器** 迁移中最重要的设置决策。模型别名可以根据环境而变化，但 CrewAI 代码保留一个 OpenAI 兼容的 API 根和一个网关密钥所有者。

第 3 步：按智能体职责分配路由

为每个 CrewAI 智能体分配一个与其风险状况相匹配的 LLM 路由。从一个小的路由集开始。在日志证明第一个策略有效后，您随时可以拆分更多角色。

planner = Agent(
    role="工作流规划师",
    goal="将请求分解成一个简短的执行计划。",
    backstory="你负责保持团队的工作范围，避免不必要的模型调用。",
    llm=planner_llm,
)

researcher = Agent(
    role="研究员",
    goal="只收集任务所需的事实。",
    backstory="你更喜欢有来源支持的笔记，而不是宽泛的推测。",
    llm=planner_llm,
)

tool_user = Agent(
    role="工具操作员",
    goal="仅在任务需要时使用经批准的工具。",
    backstory="你在调用外部系统之前会验证工具输入。",
    llm=tool_llm,
)

verifier = Agent(
    role="验证员",
    goal="根据要求和证据检查最终答案。",
    backstory="你负责寻找缺失的证据、工具错误和回滚风险。",
    llm=verifier_llm,
)

对于首次 **CrewAI OpenAI 兼容路由器** 的部署，请避免为每个智能体分配一个唯一的模型。两到三种路由类型通常就足够了：规划、具备工具能力的执行和验证。

第 4 步：构建一个小团队并保留证据字段

团队可以保持普通。但路由证据则不然。在任务描述、输出或您周围的应用程序日志中添加简单的字段，以便请求可以与 Flatkey 日志匹配。

analysis_task = Task(
    description=(
        "审查支持工单并制定一个简短的解决方案。 "
        "除非需要账户查询，否则不要调用工具。 "
        "在此提示之外保留的证据字段：workflow=crew_support_triage, "
        "route_policy=crewai-router-v1."
    ),
    expected_output="一个包含风险、工具需求和下一步行动的简洁计划。",
    agent=planner,
)

verification_task = Task(
    description=(
        "检查计划是否引用了工单事实，避免了无根据的声明， "
        "并指明了任何仍需批准的工具调用。"
    ),
    expected_output="带有必要修复的通过/失败说明。",
    agent=verifier,
    context=[analysis_task],
)

crew = Crew(
    agents=[planner, researcher, tool_user, verifier],
    tasks=[analysis_task, verification_task],
    process=Process.sequential,
)

result = crew.kickoff(
    inputs={
        "ticket_id": "TICKET-123",
        "request_id": "support-triage-2026-07-08-001",
    }
)
print(result)

此模板中的 request_id 本身并不是 CrewAI 的路由功能。它是一种可观察性习惯。您的应用程序应记录请求 ID、路由策略、模型别名、时间戳和密钥标签，以便可以在 Flatkey 中检查 **CrewAI OpenAI 兼容路由器** 的路径。

第 5 步：在广泛部署前验证工具调用

工具使用是 OpenAI 兼容路由存在风险的地方。一个普通的聊天路由可能工作正常，而一个大量使用工具的路由可能会因模式验证失败、工具参数流式传输方式不同或产生执行器拒绝的参数而失败。

在信任 CrewAI 工具路由之前，请进行小范围的工具测试。要了解更广泛的提供商行为，请将本指南与 Flatkey 关于OpenAI 兼容工具调用的文章结合阅读。

不要将此视为可选项。只有当工具路由作为单独的契约进行测试后，**CrewAI OpenAI 兼容路由器** 才算得上是生产就绪的。

第 6 步：在提示之外添加预算、重试和回退规则

不要让智能体用自然语言记住每一条操作规则。将预算和回退规则保留在代码或配置中，以便审查人员可以检查。

当批准回退时，请保持回退别名的明确性。有用的问题不是“工作组完成了吗？”，而是“哪个路由完成了，为什么切换了，以及成本是多少？”这就是 CrewAI OpenAI 兼容路由器 的运营价值。

第 7 步：保存验证包

在将 Flatkey 设为 CrewAI 工作流的默认网关之前，请保存一个紧凑的验证包。

1. 直接向 https://router.flatkey.ai/v1/chat/completions 发送的 curl 请求使用所选模型别名成功。
2. 每个 CrewAI LLM 对象在完整工作组之外运行一个小提示。
3. 完整的工作组运行一个简单的工作流和一个重工具的工作流。
4. 强制失败路径会干净地停止，而不是永远重试。
5. Flatkey 日志显示预期的密钥、模型别名、时间戳和请求所有者。
6. 令牌或使用情况字段足够可见，以便预算所有者审查。
7. 回滚是一次环境或配置更改，而不是 CrewAI 重构。

使用 Flatkey 令牌使用仪表板指南 来决定您的运营团队在第一次冒烟测试后应检查哪些字段。有关定价和账户审查，请从实时的 Flatkey 定价页面 开始，然后在您的账户中验证实际路由。

CrewAI OpenAI 兼容路由器故障排除

如果第一个请求失败，请保持调试范围小：一个密钥、一个基础 URL、一个模型别名、一个 CrewAI LLM、一个直接请求和一个 Flatkey 日志查找。

常见问题解答

CrewAI OpenAI 兼容路由器与模型回退相同吗？

不相同。CrewAI OpenAI 兼容路由器 是 CrewAI 用来访问模型路由的网关和配置边界。回退是在所选路由失败时可能运行的一种策略。请分别测试路由和回退。

每个 CrewAI 智能体都应该使用不同的模型吗？

不应该。从一个默认路由开始，如果需要，可以为重工具或验证器工作设置一个特殊路由。太多的别名会使日志、成本审查和回滚变得更加困难。

CrewAI 可以使用环境变量代替显式的 LLM 对象吗？

可以。CrewAI 文档显示了通过环境变量（如 OPENAI_API_BASE）进行 OpenAI 兼容设置的方法。显式的 LLM 对象通常更容易进行生产审查，因为每个智能体角色都在一个地方显示了 model、base_url 和 api_key。

我可以为每个 CrewAI 工作流使用相同的 Flatkey 密钥吗？

可以，但特定于工作负载的密钥更容易审计。当不同的团队、环境、预算或风险级别需要单独审查时，请使用单独的密钥或标签。

最终核对清单

当满足以下条件时，您的 CrewAI OpenAI 兼容路由器 设置就可以超越模板了：

1. CrewAI LLM 对象使用 Flatkey API 根目录作为 base_url。
2. 模型别名存在于环境或配置中，而不是散布在提示中。
3. 每个智能体角色都有一个明确的路由决策。
4. 重工具路由通过了模式、参数、上限和失败测试。
5. 预算、重试和回退限制在智能体散文之外运行。
6. Flatkey 使用情况或请求日志确认了预期的密钥和模型别名。
7. 回滚是一次配置更改。

当您准备好通过一个网关路由 CrewAI 流量时，请获取一个 Flatkey 密钥，先测试一个低风险的 crew，待日志证明策略有效后再进行扩展。