用 OpenAIChatCompletionClient 把 Microsoft AutoGen 接到 Router One

安装 autogen-agentchat 与 autogen-ext[openai]，再设置两个变量

使用 Python 3.10 或更新版本。模型客户端在 autogen-ext 里，需要它的 openai extra，这会带上 openai 库（1.93 及以上任意版本；本指南运行时为 3.17.0）和 tiktoken；autogen-agentchat 则提供 Agent 与团队。把两个包都固定在 0.7.5，也就是本指南核对的版本。有两个名字相近的包，都不能装出本指南的这套环境：PyPI 上的 autogen 现在是 AG2 Classic；pyautogen 0.10.0 是微软发布的过渡包，只会拉取 autogen-agentchat，不带 autogen-ext[openai]，也不固定 0.7.5，所以请直接安装上面两个包；如果你的代码写的是 import autogen，请看下方常见问题。微软建议新项目使用 Agent Framework；如果你正在迁移，本站的 Agent Framework 接入指南写明了 base URL 在那边填在哪里。下面是 macOS/Linux 的 shell 示例，ROUTER_ONE_* 是本示例自己定义并显式读取的变量名。省略 api_key 或 base_url 时，openai 库会回退读取 OPENAI_API_KEY 和 OPENAI_BASE_URL；完全没有 Key 时，构造函数在发出任何请求之前就会抛出 OpenAIError（openai 3.17.0 的报错消息以 Missing credentials 开头；1.93 等较早版本写的是 The api_key client option must be set）。

python -m pip install "autogen-agentchat==0.7.5" "autogen-ext[openai]==0.7.5"
export ROUTER_ONE_API_KEY="sk-your-router-one-key"
export ROUTER_ONE_MODEL_ID="anthropic/claude-sonnet-5"

把 AutoGen 配置到 Router One base URL

保存为 autogen_router_one.py，再运行 python autogen_router_one.py。model 填目录里的模型 ID，原样发送：客户端既不会去掉也不会解析 provider 前缀，所以 Dashboard → Logs 里每条记录的模型应与 /models 逐字一致。base_url 填带 /v1 的 base URL，它会交给 openai 库的 AsyncOpenAI 客户端，由后者拼接 /chat/completions；少了 /v1，请求会发到 /chat/completions，而不是 /v1/chat/completions。api_key 显式传入。model_info 告诉 AutoGen 这个模型能做什么，因为它内置的能力表只收录 gpt-5、gemini-2.5-flash 这类厂商原始模型名，没有任何目录 ID 能匹配上：vision、function_calling、json_output 和 family 是必填项，缺任何一个都会抛出 ValueError；structured_output 缺失时在构造阶段只发出警告，但一用到结构化输出就会抛出 KeyError，所以务必填写；multiple_system_messages 可选。vision 和 function_calling 按模型详情页的「视觉理解」与「工具调用」填写；本示例不发图片，所以 vision 保持 False。详情页不列 JSON 模式和结构化输出，这两项在一次真实请求成功之前保持 False。这些标志决定 AutoGen 同意发送什么，下一节列出每个键的作用。family 保持 ModelFamily.UNKNOWN，这是目录 ID 的中性取值。AutoGen 自己的参考文档也写明，用这个客户端调用非 OpenAI 模型未经测试、也不作保证，所以工具、流式和图片都要各用一次真实请求确认。第一个 Agent 带一个 Python 函数作为工具：AutoGen 把它的 JSON schema 放进 tools 字段并带上 tool_choice auto，模型调用它时在你的进程里执行该函数；max_tool_iterations=2 让它在第二次请求里把工具结果发回去，这次请求带着同样的 tools。如果模型对这次请求用文本作答，这条回复就结束运行；如果它再次调用工具，这第二轮就是最后一轮，运行以 ToolCallSummaryMessage 结束。保持默认设置时，运行在第一次请求后就结束，返回一条装着工具原始输出的 ToolCallSummaryMessage。reflect_on_tool_use=True 同样会多发一次请求，但那次请求去掉了 tools 字段、只保留工具调用历史，所以依赖它之前，先用一次真实请求在 Logs 里确认你的 ID 能处理。total_usage() 汇总该客户端各次调用中 API 报告的 prompt 与 completion token。第二个 Agent 走流式：model_client_stream=True 会把 stream 设为 true，stream_options include_usage 则要求最后返回一个带 token 用量的分块。它单独用一个客户端，因为传给构造函数的 stream_options 会随该客户端的每个请求发送，非流式的 create() 调用也不例外。

import asyncio
import os

from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.ui import Console
from autogen_core.models import ModelFamily
from autogen_ext.models.openai import OpenAIChatCompletionClient

# AutoGen cannot look up capabilities for any catalog ID, openai/ ones included.
# vision / function_calling: True only if the model's page lists Vision / Tool calling.
# json_output / structured_output: True only after one real request works.
MODEL_INFO = {
    "vision": False,
    "function_calling": True,
    "json_output": False,
    "structured_output": False,
    "family": ModelFamily.UNKNOWN,
    "multiple_system_messages": False,
}


def router_one_client(**extra) -> OpenAIChatCompletionClient:
    # Every model call is one POST /v1/chat/completions
    return OpenAIChatCompletionClient(
        model=os.environ["ROUTER_ONE_MODEL_ID"],
        api_key=os.environ["ROUTER_ONE_API_KEY"],
        base_url="https://api.router.one/v1",
        model_info=MODEL_INFO,
        **extra,
    )


async def get_order_status(order_id: str) -> str:
    """Look up the shipping status of an order."""
    return f"Order {order_id} shipped yesterday and arrives on Friday."


async def main() -> None:
    # 1. One tool call, then a second request (with the same tools) that writes the answer
    client = router_one_client()
    agent = AssistantAgent(
        "support_agent",
        model_client=client,
        tools=[get_order_status],
        system_message="You answer order questions. Call the tool for order data.",
        max_tool_iterations=2,
    )
    result = await agent.run(task="Where is order A-1042?")
    print(result.messages[-1].to_text())
    print(client.total_usage())  # usage the API reported, summed
    await client.close()

    # 2. Streaming: without stream_options the reported usage stays at 0
    stream_client = router_one_client(stream_options={"include_usage": True})
    streamer = AssistantAgent("streamer", model_client=stream_client, model_client_stream=True)
    await Console(streamer.run_stream(task="Say hello in one sentence."))
    await stream_client.close()


if __name__ == "__main__":
    asyncio.run(main())

AutoGen 0.7.5 里 model_info 每个键的作用

AutoGen 在构造请求之前先检查 model_info，并拒绝标志不允许的功能，所以标志填错，要么挡住模型本来具备的功能，要么放行模型无法处理的请求。把标志设为 True 并不会增加任何能力：以 /models 上的模型详情页为准，再用一次真实请求确认。另有两个构造参数独立于 model_info 影响消息格式：user 消息会带一个取值为消息来源的 name 字段（任务消息为 user），如果模型拒绝这个字段，可用 include_name_in_message=False 去掉；add_name_prefixes=True 会在正文开头额外写入「<source> said:」，但 name 字段仍会发送，需要在正文里标明发言者、又不想带这个字段时，要同时设 include_name_in_message=False。下表各行都对照 0.7.5 源码和本地模拟服务核对过。

AutoGen 的哪个类发出哪种请求

OpenAIChatCompletionClient 是本指南配置的类，它只调用 Chat Completions。AutoGen 的其他组件自带客户端，会调用别的端点，其中一些 Router One 并不提供，所以把组件指向网关之前先确认它用的是哪个端点。

数清一次运行或一个团队背后的请求

一次 AutoGen 运行是一串模型调用，每次调用在 Dashboard → Logs 里都是独立请求，有各自的 request_id、token 和费用。AssistantAgent 不调用工具时，一次请求就给出回答。带工具且保持默认设置（max_tool_iterations 为 1、reflect_on_tool_use 为 False）时仍然只有一次请求：工具执行后，它的原始输出就是回复。reflect_on_tool_use=True 会多一次请求来写回答；调高 max_tool_iterations 则允许相应轮数的工具调用，每一轮都会重发到目前为止的对话，所以输入 token 逐轮增长。团队会把这些成倍放大。在 RoundRobinGroupChat 和 SelectorGroupChat 里，每个带模型客户端的 Agent（如 AssistantAgent）每发言一轮，至少产生一次请求，而 max_turns 默认为 None，即不设上限，所以要设置 max_turns 或 MaxMessageTermination 之类的终止条件。SelectorGroupChat 还会在有多个候选参与者、且没有 selector_func 做决定时，让它自己的 model_client 挑选下一位发言者；如果回复里没有点名有效参与者，会重试到 max_selector_attempts（默认 3）次，之后团队退回上一位发言者或第一位参与者。在一次本地测试中，模拟服务的回复从不点名任何 Agent，一个 max_turns=2 的双 Agent SelectorGroupChat 发出了 5 次请求，其中 3 次是选人尝试。在框架之下，openai 库默认对连接错误以及 408、409、429 和 5xx 响应重试 2 次，所以一次失败的调用可能是 3 个请求；测试时给客户端传 max_retries=0。402 不会重试。给每个 Agent 进程单独一把设了 maxSpend 的 Key：失控的循环会在上限处收到 HTTP 402 而停下，花费不会超过这个上限，你的其他 Key 也照常可用。每条消息上的 models_usage 和 client.total_usage() 是 API 报告用量的累加，不是费用；不带 include_usage 的流式调用报告为 0；费用以 Logs 记录为准。有一个上下文类需要 AutoGen 查不到的数字：不传 token_limit 的 TokenLimitedChatCompletionContext 会调用 remaining_tokens，而它对目录 ID 会抛出 KeyError，所以要显式传入 token_limit，取值不超过模型详情页上的上下文窗口，并把它的计数视为本地 tiktoken cl100k_base 估算值。Router One 记录每次模型调用，但不运行 AutoGen 的 Agent、工具、记忆或团队轮次。

AG2：自带配置类的独立项目

AG2 自称前身为 AutoGen，但它是一个独立项目，有自己的维护者、包和类，也不需要 model_info。AG2 1.x（pip install "ag2[openai]"，import ag2；本指南核对的是 1.0.6）用 OpenAIConfig 配置模型：model 原样填目录 ID，base_url 填带 /v1 的 base URL，api_key 填 Key，省略时回退读取 OPENAI_API_KEY。每次调用都是 POST /v1/chat/completions。streaming=True 会自动加上 stream_options include_usage；工具调用之后，Agent 无需额外设置就会在第二次请求里把结果发回去。同一模块里的 OpenAIResponsesConfig 则调用 /v1/responses，store 默认为 true，所以只适用于详情页列出该端点的 ID。代码里 import autogen 并构造 ConversableAgent 或 LLMConfig 的，是 AG2 Classic，见下方常见问题。AG2 1.x（OpenAIConfig）和 AG2 Classic 都用本地模拟服务核对过。

# AG2 1.x: python -m pip install "ag2[openai]"
import asyncio
import os

from ag2 import Agent
from ag2.config import OpenAIConfig

agent = Agent(
    "assistant",
    prompt="You answer order questions.",
    config=OpenAIConfig(
        model=os.environ["ROUTER_ONE_MODEL_ID"],
        api_key=os.environ["ROUTER_ONE_API_KEY"],
        base_url="https://api.router.one/v1",
        streaming=True,  # also requests stream_options include_usage
    ),
)


async def main() -> None:
    reply = await agent.ask("Say hello in one sentence.")
    print(reply.body)


asyncio.run(main())

AutoGen 该填哪个模型 ID？

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

AutoGen 用的是哪种 API 协议？

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

在 trace 里验证 AutoGen 的调用

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

常见问题