Rystem.PlayFramework.Adapters 10.1.1

Rystem.PlayFramework.Adapters

Rystem.PlayFramework.Adapters is the Azure OpenAI adapter package for Rystem.PlayFramework.

It registers named IChatClient and IVoiceAdapter instances, defaults to the Azure OpenAI Responses API, and adds a file-upload wrapper for non-image, non-audio content.

Installation

dotnet add package Rystem.PlayFramework.Adapters

The package uses OpenAI 2.12.0 directly with Microsoft.Extensions.AI.OpenAI 10.9.0. Azure.AI.OpenAI is not included. The dependency range is exactly [2.12.0]. A direct consumer reference can override this range under NuGet's direct-dependency-wins rule, but restore emits NU1608; that graph is unsupported and should be treated as an error by CI.

Azure OpenAI v1 endpoint

Requests use the Azure OpenAI v1 surface. Both forms below are accepted:

• https://your-resource.openai.azure.com/
• https://your-resource.openai.azure.com/openai/v1/

Resource-root endpoints are normalized to /openai/v1 automatically. Legacy deployment-specific endpoints such as /openai/deployments/<deployment> are rejected. The configured deployment is sent as the v1 request's model value.

What this package adds

The public registration methods are:

• AddAdapterForAzureOpenAI(...)
• AddVoiceAdapterForAzureOpenAI(...)

These methods register singleton factory-backed services so they can be referenced by PlayFramework instance name.

Registering a chat adapter

Unnamed registration:

builder.Services.AddAdapterForAzureOpenAI(settings =>
{
    settings.Endpoint = new Uri("https://your-resource.openai.azure.com/");
    settings.ApiKey = builder.Configuration["AzureOpenAI:Key"];
    settings.Deployment = "gpt-4o";
});

Named registration, which is the most common pattern with PlayFramework:

builder.Services.AddAdapterForAzureOpenAI("default", settings =>
{
    settings.Endpoint = new Uri(builder.Configuration["AzureOpenAI:Endpoint"]!);
    settings.ApiKey = builder.Configuration["AzureOpenAI:Key"]!;
    settings.Deployment = builder.Configuration["AzureOpenAI:Deployment"] ?? "gpt-4o";
});

builder.Services.AddPlayFramework("default", framework =>
{
    framework.WithChatClient("default");
});

Managed identity mode:

builder.Services.AddAdapterForAzureOpenAI("default", settings =>
{
    settings.Endpoint = new Uri("https://your-resource.openai.azure.com/");
    settings.UseAzureCredential = true;
    settings.Deployment = "gpt-4o";
});

UseAzureCredential uses DefaultAzureCredential with the https://ai.azure.com/.default scope. In Azure, prefer Managed Identity and assign the identity an Azure OpenAI data-plane role such as Cognitive Services OpenAI User. Do not configure ApiKey when UseAzureCredential is enabled; the adapter rejects ambiguous authentication configuration during registration.

Chat adapter settings

AdapterSettings exposes:

If an existing application encounters a Responses-only service incompatibility, set UseResponsesApi = false to use Chat Completions temporarily. This disables automatic file upload because EnableFileUpload applies only to Responses.

Runtime tool declarations

Starting with 10.0.11-beta.22, the adapter is compatible with the declaration-only AIFunctionDeclaration instances published by PlayFramework when scene and local-tool descriptions are refreshed at runtime. Name, description, and JSON Schema are forwarded to Azure OpenAI through the official Microsoft.Extensions.AI.OpenAI bridge.

This applies to both adapter modes:

• Chat Completions (UseResponsesApi = false)
• Responses API (UseResponsesApi = true)

Declaration-only tools describe routing and callable tools to the model; PlayFramework keeps the executable function separately and invokes it after receiving the tool call.

File upload behavior

When both of these are true:

• UseResponsesApi = true
• EnableFileUpload = true

the adapter wraps the inner IChatClient with MultiModalChatClient.

That wrapper:

• uploads non-image, non-audio DataContent through the Files API
• replaces inline content with HostedFileContent(file_id)
• caches uploads by SHA256 hash
• tries remote file reuse by filename if hash lookup misses

Cache priority is:

1. IDistributedCache
2. IMemoryCache
3. internal in-memory dictionary

Audio modes

The chat adapter supports three audio paths:

• AudioMode.None - audio is passed through as-is
• AudioMode.MultiModal - audio is sent inline to a model that natively supports it
• AudioMode.SpeechToText - audio is transcribed through Whisper and injected as text

Example:

builder.Services.AddAdapterForAzureOpenAI("default", settings =>
{
    settings.Endpoint = new Uri("https://your-resource.openai.azure.com/");
    settings.ApiKey = "...";
    settings.Deployment = "gpt-4o";
    settings.AudioMode = AudioMode.SpeechToText;
    settings.SpeechToTextDeployment = "whisper";
});

Voice adapter

The same package also registers IVoiceAdapter for the PlayFramework voice pipeline.

builder.Services.AddVoiceAdapterForAzureOpenAI("default", settings =>
{
    settings.Endpoint = new Uri(builder.Configuration["AzureOpenAI:Endpoint"]!);
    settings.ApiKey = builder.Configuration["AzureOpenAI:Key"]!;
    settings.SttDeployment = "<transcription-deployment>";
    settings.TtsDeployment = "<speech-deployment>";
    settings.TtsVoice = "alloy";
});

builder.Services.AddPlayFramework("default", framework =>
{
    framework.WithVoice("default");
});

VoiceAdapterSettings exposes:

The voice adapter requests verbose_json transcription first so detected language and audio duration remain available for language instructions and STT cost tracking. Some transcription models, including current gpt-4o-mini-transcribe deployments, reject that format. For those deployments the adapter retries with json; transcription text remains available, but detected language and duration are null, so language substitution and duration-based STT cost cannot be calculated from the service response.

Cost tracking

Set CostTracking on AdapterSettings to record input/output token costs per LLM call:

builder.Services.AddAdapterForAzureOpenAI("default", settings =>
{
    settings.Endpoint = new Uri(builder.Configuration["AzureOpenAI:Endpoint"]!);
    settings.ApiKey = builder.Configuration["AzureOpenAI:Key"]!;
    settings.Deployment = "gpt-4o";
    settings.CostTracking = new TokenCostSettings
    {
        Enabled = true,
        Currency = "USD",
        InputTokenCostPer1K = 0.005m,
        OutputTokenCostPer1K = 0.015m,
        CachedInputTokenCostPer1K = 0.0025m, // optional: cached input is usually ~50% of regular
    };
});

TokenCostSettings exposes:

When CostTracking is set the adapter wraps the underlying IChatClient with CostTrackingChatClient — a DelegatingChatClient that reads response.Usage after every LLM call and embeds a CostCalculation into AdditionalProperties. ChatClientManager picks that value up passively and surfaces it as AiSceneResponse.Cost (per-call) and AiSceneResponse.TotalCost (cumulative across the full request).

Critical: you must call .WithChatClient("name") in AddPlayFramework with the same factory name used for the adapter. Without it the framework falls back to a direct IChatClient resolution path that does not see the cost wrapper and reports zero for all costs.

See Example: cost tracking in the PlayFramework README for budget enforcement, response fields, and per-model / per-client pricing.

Important caveats

The streaming path blocks during file preprocessing

GetStreamingResponseAsync(...) preprocesses uploadable files with a sync wait via GetAwaiter().GetResult(). It works, but it is not the cleanest async path.

Remote file reuse is filename-based after hash miss

If the local content-hash cache misses, the wrapper checks Azure's existing file list by filename. That is convenient, but it is not a content-identity guarantee.

Images and audio are not part of the file-upload wrapper

The Files API wrapper only handles non-image, non-audio binary content. Images stay inline, and audio is handled through the adapter's audio-mode logic.

Factory names should match your PlayFramework names

If you register the adapter as "default", your PlayFramework builder should typically reference WithChatClient("default") and WithVoice("default").

Grounded by source files

• src/AI/Rystem.PlayFramework.Adapters/ServiceCollectionExtensions.cs
• src/AI/Rystem.PlayFramework.Adapters/MultiModalChatClient.cs
• src/AI/Test/Rystem.PlayFramework.Api/Program.cs

Use this package when your PlayFramework backend should run on Azure OpenAI with optional file upload, speech-to-text, and voice output.