@pleach/transport-azure-openai

@pleach/transport-azure-openai is the Azure OpenAI Service route for a Pleach session whose buyer reaches OpenAI models through their Azure tenancy rather than the direct OpenAI API. createAzureOpenAIProvider(config) returns an AgentProvider that POSTs to the Azure chat-completions endpoint and decodes the text/event-stream response. The @azure/openai SDK isn't required. Cascade decisions and audit shape are the same as any other provider; only the transport and the credential source change.

What it provides

• An AgentProvider (execute + abort + capabilities) for the OpenAI family on Azure (gpt-4o, gpt-4o-mini, o1, o3-mini, …). Anthropic-via-Azure and Mistral-via-Azure throw "family not yet supported" at invoke time.
• Three auth modes: a static apiKey, an azureADCredentials token callback, or the host's managed identity via an explicit credential: "default".
• Deployment-name routing, since Azure addresses models by deployment name: providerConfig.deployment, then defaultDeployment, then the model id.
• Generic auth errors: the stream never carries the underlying credential error or an HTTP 401/403 body.
• createResolveRegion(config) and regionFromEndpoint(endpoint), which read the region from a regional *.<region>.api.cognitive.microsoft.com hostname and return null for *.openai.azure.com.
• Per-call abort: each execute() owns its own AbortController. abort() cancels every in-flight call.

Where it fits

@pleach/transport-azure-openai plugs into the same provider slot on SessionRuntime that the direct-API providers fill — it satisfies the AgentProvider contract documented in Providers. For the architectural shape of a cloud-routed deployment — transport vs family, IAM federation, region as a hard constraint, cost reconciliation — see Cloud-routed agent.

Install

This package is not on npm yet, so there is no npm install step. Build it from the source repository and add it as a workspace dependency alongside @pleach/core:

{
  "dependencies": {
    "@pleach/core": "0.1.0",
    "@pleach/transport-azure-openai": "workspace:*"
  }
}

Once the package publishes, this page will switch to a regular npm install.

@azure/identity (^4.0.0) is an optional peer dependency, imported lazily and only on the credential: "default" path. If it's absent there, the first execute() throws a "missing optional peer dependency @azure/identity" error. API-key and token-callback auth need nothing extra.

Auth

Exactly one mode applies. azureADCredentials wins over apiKey when both are set. Construction throws when no auth is configured, when apiKey is an empty string, or when credential: "default" is combined with either of the other two.

Managed identity is opt-in

Managed identity is never a fallback. On a multi-tenant or BYOK host, a tenant whose key is missing must fail, not silently authenticate as (and bill to) the host's own identity. To use the host's identity, install @azure/identity and set credential: "default":

import { createAzureOpenAIProvider } from "@pleach/transport-azure-openai";

const provider = createAzureOpenAIProvider({
  endpoint: "https://my-resource.openai.azure.com",
  credential: "default",
  defaultDeployment: "prod-gpt4o",
});

Because the host's Entra token is attached, the endpoint must be https on *.openai.azure.com or *.cognitiveservices.azure.com, or an exact hostname listed in allowedEndpointHosts (a private gateway, for example). Any other endpoint throws at construction.

The transport builds one DefaultAzureCredential per provider, requests a token for https://cognitiveservices.azure.com/.default, and caches it until credentialRefreshSkewMs before expiry. The skew must be a finite number >= 0 and defaults to 300000 (5 minutes).

Token callback

For a specific credential, such as a user-assigned identity, pass azureADCredentials: () => Promise<string>. It runs on every request, so cache inside it if you need to.

Auth errors

A credential failure yields one error event with the fixed text "azure-openai: authentication failed". The underlying error goes only to the optional onAuthError(error) hook, and a throwing hook is ignored. An HTTP 401/403 from Azure is handled the same way: its body isn't echoed, and the cached managed-identity token is dropped so the next request mints a new one.

Configuration

The package's README and src/types.ts in the source repository are the reference. If a claim here disagrees with the source, the source wins.

Where to go next