Connect Microsoft Agent Framework to Router One with the Chat Completions client

Install agent-framework-openai and set your credentials

Use Python 3.10 or newer. The OpenAI clients live in the agent-framework-openai package, which pulls in agent-framework-core and the openai Python library; pip install agent-framework installs the full standard package set instead. Released packages no longer need --pre. Importing a client from agent_framework.openai without the provider package raises ModuleNotFoundError naming agent-framework-openai. The shell example below is for macOS/Linux. Replace both placeholders before running it, using a Router One key and the exact ID of a current chat model. The ROUTER_ONE_* names belong to this example, which reads them explicitly. The client has its own fallbacks when an argument is omitted: OPENAI_API_KEY, OPENAI_BASE_URL, and for the model OPENAI_CHAT_COMPLETION_MODEL, then OPENAI_MODEL. Agent Framework does not load .env files by itself; call load_dotenv() or pass env_file_path if you keep the values in a file. Keep the same environment active when running the Python file.

python -m pip install agent-framework-openai
export ROUTER_ONE_API_KEY="sk-your-router-one-key"
export ROUTER_ONE_MODEL_ID="<exact-model-id-from-/models>"

Configure Microsoft Agent Framework to use the Router One base URL

Save this as maf_router_one.py and run python maf_router_one.py. OpenAIChatCompletionClient takes the catalog ID as model, unchanged, including any provider prefix that is part of the ID; base_url is the /v1 base URL and is handed to the openai library's AsyncOpenAI client, which appends /chat/completions, so every model round trip in a run is one POST /v1/chat/completions; api_key is read from ROUTER_ONE_API_KEY, and passing it explicitly keeps the client on OpenAI routing even when AZURE_OPENAI_* variables exist in the shell. The @tool decorator turns a typed Python function into a function tool: its JSON schema travels in the request's tools field, and when the model asks for it, the framework executes the function in your process and sends the result back in the next request. approval_mode is written out because the official samples do the same; never_require is the default, and always_require holds the call until explicit approval is given. function_invocation_configuration bounds that loop, here at 5 model round trips and 10 tool executions per run. Agent(client=..., instructions=..., tools=[...]) is the current constructor, and client.as_agent(...) builds the same object. agent.create_session() returns an AgentSession; with this client the history lives in the session inside your process and is resent as messages on each run. The first run returns an AgentResponse: text is the final answer, and usage_details sums the input and output token counts the API reported across the run's requests. The second run passes stream=True and iterates AgentResponseUpdate chunks; the request is the same with stream set and stream_options include_usage.

import asyncio
import os
from typing import Annotated

from agent_framework import Agent, tool
from agent_framework.openai import OpenAIChatCompletionClient


@tool(approval_mode="never_require")
def get_order_status(order_id: Annotated[str, "The order number to look up."]) -> str:
    """Look up the shipping status of an order."""
    return f"Order {order_id} shipped yesterday and arrives on Friday."


async def main() -> None:
    # Chat Completions client: every model round trip is one POST /v1/chat/completions
    client = OpenAIChatCompletionClient(
        model=os.environ["ROUTER_ONE_MODEL_ID"],
        api_key=os.environ["ROUTER_ONE_API_KEY"],
        base_url="https://api.router.one/v1",
    )
    # Bound the tool loop (defaults: max_iterations=40, max_function_calls=None)
    client.function_invocation_configuration.update({"max_iterations": 5, "max_function_calls": 10})

    agent = Agent(
        client=client,
        name="SupportAgent",
        instructions="You answer order questions. Call the tool when you need order data.",
        tools=[get_order_status],
    )
    session = agent.create_session()  # history stays in this process

    # 1. Non-streaming run: text is the answer, usage_details sums the reported tokens
    result = await agent.run("Where is order A-1042?", session=session)
    print(result.text)
    print(result.usage_details)

    # 2. Same session, streamed: same request with stream=true
    async for update in agent.run("When does it arrive?", session=session, stream=True):
        if update.text:
            print(update.text, end="", flush=True)
    print()


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

Which Agent Framework setting sends which request

The client class picks the endpoint, and the agent decides what each request carries. The rows below give the value for each setting in this guide, the request it produces, and what to confirm before relying on it. One class in the same package is out of scope: OpenAIEmbeddingClient posts to /v1/embeddings, which Router One does not serve, so embeddings for a RAG pipeline stay on another provider or a local model.

.NET: set OpenAIClientOptions.Endpoint and call AsAIAgent

In .NET the connection belongs to the official OpenAI library, and Agent Framework adds the agent on top. Install Microsoft.Agents.AI.OpenAI; the Learn page still appends --prerelease, but NuGet lists stable 1.x releases (1.22.0 when this guide was checked), so the flag is optional. OpenAIClientOptions.Endpoint takes the URL with /v1: the library's default endpoint is https://api.openai.com/v1 and it appends /chat/completions itself, so https://api.router.one alone ends in 404 not_found. GetChatClient(model) selects Chat Completions, and the AsAIAgent extension wraps it in a ChatClientAgent; snippets that call CreateAIAgent predate the January 2026 rename to AsAIAgent. GetResponsesClient().AsAIAgent(model: ...) is the Responses variant and follows the same family rule as the Python OpenAIChatClient. Function tools are passed as tools: [AIFunctionFactory.Create(Method)] and run in your process through the FunctionInvokingChatClient of Microsoft.Extensions.AI, whose MaximumIterationsPerRequest defaults to 40. RunAsync returns the complete response, and RunStreamingAsync streams updates.

// dotnet add package Microsoft.Agents.AI.OpenAI
using System.ClientModel;
using Microsoft.Agents.AI;
using OpenAI;
using OpenAI.Chat;

var key = Environment.GetEnvironmentVariable("ROUTER_ONE_API_KEY")
    ?? throw new InvalidOperationException("ROUTER_ONE_API_KEY is not set.");
var model = Environment.GetEnvironmentVariable("ROUTER_ONE_MODEL_ID")
    ?? throw new InvalidOperationException("ROUTER_ONE_MODEL_ID is not set.");

AIAgent agent = new OpenAIClient(
        new ApiKeyCredential(key),
        new OpenAIClientOptions { Endpoint = new Uri("https://api.router.one/v1") })
    .GetChatClient(model)
    .AsAIAgent(instructions: "You answer order questions.", name: "SupportAgent");

Console.WriteLine(await agent.RunAsync("Where is order A-1042?"));

Budget one agent run and reconcile its requests

One agent.run() is a loop, not one request. A plain answer is one request; each batch of tool calls adds a round trip, because the tool results go back to the model in a new request that also resends the conversation so far, so input tokens grow with every iteration. max_iterations (default 40) bounds the round trips, and when it is used up the framework sends one more request with tool_choice set to none to get a final answer; max_function_calls and max_duration_seconds are unlimited by default, and the documentation notes that they are checked only after each batch of parallel tool calls, so one batch can overshoot them. None of them is a spend cap. Below the framework, the openai library retries connection errors and 408, 409, 429, and 5xx responses 2 times by default. The framework builds that client without a max_retries argument, so to change it pass your own: async_client=AsyncOpenAI(base_url=..., api_key=..., max_retries=0). Every attempt that reaches the gateway is its own request in Dashboard → Logs with its own request_id, trace, and charge. Give each agent a dedicated key with maxSpend: a looping run then gets HTTP 402 at the cap you set, the openai library does not retry a 402, and the wallet and your other keys are untouched. Workflows built with WorkflowBuilder also run in your process, and each agent executor's model call is one more request on the same key. Agent Framework's OpenTelemetry layer is on by default but exports nothing until you configure an exporter, for example with configure_otel_providers(); it emits invoke_agent, chat, and execute_tool spans, and prompts are recorded only when sensitive data is enabled (ENABLE_SENSITIVE_DATA, off by default). Those spans are your application's traces and stay wherever you export them. result.usage_details is the framework's sum of the usage the API reported; the charge is what Logs records. Reconcile by key, time, model, and token counts, and keep the request_id when reporting a failure. Router One records model-call metadata; it does not run the agent loop, your tools, your middleware, or your workflows.

Which model ID should Microsoft Agent Framework send?

Copy the exact model ID from /models, preserving case, hyphens, and version suffixes; do not substitute a display name. Open its detail page and match the supported API endpoints, context window, and capabilities such as tool calling to the provider and features selected in Microsoft Agent Framework. A catalog listing does not mean the client can use every feature of that model. Give each tool a dedicated API key with a maxSpend cap.

Which API protocol is Microsoft Agent Framework using?

OpenAI-compatible describes an interface format; it does not make Chat Completions (/v1/chat/completions), Responses (/v1/responses), and Anthropic Messages (/v1/messages) interchangeable. Check the installed client version, provider configuration, and actual request path against the model detail page and API compatibility fact sheet. A successful plain-text chat does not establish support for hosted tools, conversation state, or file-editing features.

Verify the Microsoft Agent Framework call in your request trace

Send a simple text request from Microsoft Agent Framework, then match its trace in Dashboard → Logs by time, model, and request_id: tokens, cost, latency, and status. Next, test streaming, tool calls, and multi-turn history separately. For failures, retain the actual request path, full error message, and request_id. If there is no matching log, check client configuration and connectivity before attributing the error to the gateway or upstream.

FAQ