Microsoft Azure OpenAI
Follow one tool-free request as streamed props become a trusted two-step plan preview.
Recorded in the real Angular workbench with OpenAI and the actual Hashbrown SDK. The standalone Quickstart and workbench share PlanCard and its registration. No browser tools, acceptance action or application writes. Unchanged provider events are paced at 20 ms for filming; the normal host adds no delay. Footage slowed to half speed for readability. Replay makes no requests. No narration. Read the text walkthrough.
Use Azure OpenAI when your application calls a deployment managed in Azure. The Hashbrown adapter keeps the browser's AG-UI contract the same while the server supplies the Azure endpoint, authentication, and deployment name. It uses the Responses API, so endpoint and API-version configuration matter before we write the route.
The teaser demonstrates the OpenAI-backed client flow. It does not demonstrate an Azure deployment or Microsoft Entra authentication.
Keep provider access on your server
Scroll horizontally to see the full diagram, or expand it.
Read the diagram
The browser sends messages to an application endpoint. The endpoint checks access and calls the provider. The provider response returns through the endpoint as events for the client to render. Credentials stay on the server. Solid arrows show requests; dashed arrows show returned data.
Install the server adapter
Install the Azure adapter, the Azure OpenAI SDK, and the AG-UI SSE encoder:
npm install @hashbrownai/azure openai @ag-ui/core @ag-ui/encoder
Client Configuration
Pass the official SDK's AzureClientOptions directly as clientOptions. This supports API keys, Microsoft Entra token providers, Azure endpoints, retries, and custom fetch implementations without Hashbrown wrapping those options. The model remains server configuration and is not read from the client run input.
Set endpoint and an apiVersion that supports the Responses API (for example '2025-04-01-preview'). Requests go to {endpoint}/openai/responses?api-version=….
Do not set clientOptions.deployment. The Responses API selects the deployment through the model option, so pass your deployment name as model. Setting deployment fails the run with a RUN_ERROR that tells you to remove it.
API key:
HashbrownAzure.stream.text({
clientOptions: {
apiKey: process.env.AZURE_API_KEY!,
endpoint: process.env.AZURE_ENDPOINT!,
apiVersion: process.env.AZURE_API_VERSION ?? '2025-04-01-preview',
},
model: process.env.AZURE_MODEL!,
input,
});
Microsoft Entra token provider:
HashbrownAzure.stream.text({
clientOptions: {
azureADTokenProvider,
endpoint: process.env.AZURE_ENDPOINT!,
apiVersion: process.env.AZURE_API_VERSION ?? '2025-04-01-preview',
},
model: process.env.AZURE_MODEL!,
input,
});
Streaming Text Responses
HashbrownAzure.stream.text(options) accepts an AG-UI RunAgentInput and returns an AsyncIterable<AGUIEvent>. Encode those events as AG-UI SSE at your HTTP boundary.
API Reference
| Name | Type | Description |
|---|---|---|
clientOptions | AzureClientOptions | Official Azure OpenAI SDK configuration, passed through unchanged. |
model | string | Azure deployment name, sent as the Responses request model. |
input | AzureHashbrownRunAgentInput | AG-UI run input, including messages and tools. |
signal | AbortSignal | (Optional) Cancels the Azure OpenAI request when the HTTP client disconnects. |
activities | ActivityCallback | (Optional) Sends activities alongside the model's output. See Sending Activities. |
reasoning | boolean | { effort?, summary? } | (Optional) Controls the reasoning request parameter. See Reasoning. |
builtInTools | AzureBuiltInTools | (Optional) Turns on provider-run tools. See Built-in Tools. |
transformRequestOptions | (params) => params | Promise<params> | (Optional) Transforms the final streaming Responses request (ResponseCreateParamsStreaming). |
The adapter maps system and developer instructions, message history, tool definitions, tool results, and native structured output. Provider and mapping failures are emitted as RUN_ERROR events.
Responses API
The adapter streams from the Responses API on your Azure OpenAI resource. Every request sends store: false, and Hashbrown replays earlier turns, including earlier reasoning, from the history your client sends.
Reasoning
Hashbrown decides whether to request reasoning from the model option, which is your deployment name. If the name starts with o and a digit, gpt-5, or gpt- followed by a major version of 5 or later, and is not a -chat variant such as gpt-5-chat-latest, Hashbrown sends reasoning: { summary: 'auto' } and include: ['reasoning.encrypted_content'], and leaves effort to the model.
A deployment name often does not reveal the model behind it. Set reasoning explicitly in that case, to true or to an object:
const stream = HashbrownAzure.stream.text({
clientOptions: {
apiKey: process.env.AZURE_API_KEY!,
endpoint: process.env.AZURE_ENDPOINT!,
apiVersion: process.env.AZURE_API_VERSION ?? '2025-04-01-preview',
},
model: 'support-assistant',
input,
reasoning: { effort: 'low' },
});
reasoning: truetreats the deployment as a reasoning model whatever its name, and sendsreasoning: { summary: 'auto' }andinclude: ['reasoning.encrypted_content'].reasoning: { effort, summary }is sent as given. A missingsummarydefaults to'auto'.effortis sent only when you set it.reasoning: falsestops Hashbrown from requesting reasoning summaries. Use it when a non-reasoning deployment happens to have a name that matches. It does not turn reasoning off: a reasoning model may still return encrypted reasoning, which Hashbrown still replays on the next turn.
The client receives AG-UI REASONING_MESSAGE_START, REASONING_MESSAGE_CONTENT, and REASONING_MESSAGE_END events for summary text and REASONING_ENCRYPTED_VALUE events for encrypted content. Assistant messages expose them as reasoning and reasoningDetails.
Azure Differences
- Azure does not stream partial images.
- Reasoning summaries are not guaranteed on every request.
- The models and API versions available differ from OpenAI's and vary by region and resource.
This Azure route was verified against a mock server. Check it against your own resource before you depend on it in production.
Structured Output
Set input.forwardedProps.hashbrown.responseSchema to use Azure OpenAI native JSON schema output:
const input = {
...runInput,
forwardedProps: {
hashbrown: {
responseSchema: {
type: 'object',
properties: {
answer: { type: 'string' },
},
required: ['answer'],
},
},
},
};
Node.js Server Integration
One browser contract, a provider-specific server
Scroll horizontally to see the full diagram, or expand it.
Read the diagram
The browser posts AG-UI run input to an application route. The route passes input and server configuration to a provider adapter. The adapter calls the native model API, maps its stream to AG-UI events, and the route encodes those events as SSE for the browser.
The examples below host /run in an ordinary application. Configure your Angular client to call that route, using the Quickstart for the framework setup. They show provider mapping, SSE encoding, and disconnect cancellation. Add your application's validation, identity, authorization, and request limits before exposing the route; see Securing a public endpoint. A TypeScript assertion on the request body does not validate it.
import type { RunAgentInput } from '@ag-ui/core';
import { EventEncoder } from '@ag-ui/encoder';
import { HashbrownAzure } from '@hashbrownai/azure';
import express from 'express';
const app = express();
app.use(express.json());
app.post('/run', async (req, res) => {
const abortController = new AbortController();
req.once('aborted', () => abortController.abort());
res.once('close', () => abortController.abort());
const stream = HashbrownAzure.stream.text({
clientOptions: {
apiKey: process.env.AZURE_API_KEY!,
endpoint: process.env.AZURE_ENDPOINT!,
apiVersion: process.env.AZURE_API_VERSION ?? '2025-04-01-preview',
},
model: process.env.AZURE_MODEL!,
input: req.body as RunAgentInput,
signal: abortController.signal,
});
const encoder = new EventEncoder();
res.header('Cache-Control', 'no-cache, no-store, must-revalidate');
res.header('Content-Type', encoder.getContentType());
res.header('Connection', 'keep-alive');
res.flushHeaders();
for await (const event of stream) {
res.write(encoder.encodeSSE(event));
}
if (!res.writableEnded) {
res.end();
}
});
app.listen(3000);
import type { RunAgentInput } from '@ag-ui/core';
import { EventEncoder } from '@ag-ui/encoder';
import { HashbrownAzure } from '@hashbrownai/azure';
import Fastify from 'fastify';
const fastify = Fastify();
fastify.post('/run', async (request, reply) => {
const abortController = new AbortController();
request.raw.once('aborted', () => abortController.abort());
reply.raw.once('close', () => abortController.abort());
const stream = HashbrownAzure.stream.text({
clientOptions: {
apiKey: process.env.AZURE_API_KEY!,
endpoint: process.env.AZURE_ENDPOINT!,
apiVersion: process.env.AZURE_API_VERSION ?? '2025-04-01-preview',
},
model: process.env.AZURE_MODEL!,
input: request.body as RunAgentInput,
signal: abortController.signal,
});
const encoder = new EventEncoder();
reply.header('Cache-Control', 'no-cache, no-store, must-revalidate');
reply.header('Content-Type', encoder.getContentType());
reply.header('Connection', 'keep-alive');
for await (const event of stream) {
reply.raw.write(encoder.encodeSSE(event));
}
if (!reply.raw.writableEnded) {
reply.raw.end();
}
});
fastify.listen({ port: 3000 });
import type { RunAgentInput } from '@ag-ui/core';
import { EventEncoder } from '@ag-ui/encoder';
import { Body, Controller, Post, Req, Res } from '@nestjs/common';
import { HashbrownAzure } from '@hashbrownai/azure';
import type { Request, Response } from 'express';
@Controller()
export class RunController {
@Post('run')
async run(
@Body() input: RunAgentInput,
@Req() req: Request,
@Res() res: Response,
) {
const abortController = new AbortController();
req.once('aborted', () => abortController.abort());
res.once('close', () => abortController.abort());
const stream = HashbrownAzure.stream.text({
clientOptions: {
apiKey: process.env.AZURE_API_KEY!,
endpoint: process.env.AZURE_ENDPOINT!,
apiVersion: process.env.AZURE_API_VERSION ?? '2025-04-01-preview',
},
model: process.env.AZURE_MODEL!,
input,
signal: abortController.signal,
});
const encoder = new EventEncoder();
res.header('Cache-Control', 'no-cache, no-store, must-revalidate');
res.header('Content-Type', encoder.getContentType());
res.header('Connection', 'keep-alive');
res.flushHeaders();
for await (const event of stream) {
res.write(encoder.encodeSSE(event));
}
if (!res.writableEnded) {
res.end();
}
}
}
import type { RunAgentInput } from '@ag-ui/core';
import { EventEncoder } from '@ag-ui/encoder';
import { HashbrownAzure } from '@hashbrownai/azure';
import { Hono } from 'hono';
const app = new Hono();
app.post('/run', async (c) => {
const input = (await c.req.json()) as RunAgentInput;
const stream = HashbrownAzure.stream.text({
clientOptions: {
apiKey: process.env.AZURE_API_KEY!,
endpoint: process.env.AZURE_ENDPOINT!,
apiVersion: process.env.AZURE_API_VERSION ?? '2025-04-01-preview',
},
model: process.env.AZURE_MODEL!,
input,
signal: c.req.raw.signal,
});
const encoder = new EventEncoder();
const textEncoder = new TextEncoder();
return new Response(
new ReadableStream({
async start(controller) {
for await (const event of stream) {
controller.enqueue(textEncoder.encode(encoder.encodeSSE(event)));
}
controller.close();
},
}),
{
headers: {
'Cache-Control': 'no-cache, no-store, must-revalidate',
'Content-Type': encoder.getContentType(),
},
},
);
});
export default app;
Built-in Tools
Built-in tools run on the model provider instead of in your app or on your server. Turn them on with builtInTools. The keys are the camelCase form of the builtin value a call reports, so a key means the same capability on every Hashbrown provider adapter. The available keys are webSearch and codeExecution.
const stream = HashbrownAzure.stream.text({
clientOptions,
model: process.env.AZURE_OPENAI_DEPLOYMENT!,
input,
signal,
builtInTools: { webSearch: true },
});
Pass true for the provider defaults, or the tool's own configuration (for example search_context_size, user_location or filters), which is sent unchanged: builtInTools: { webSearch: { search_context_size: 'low' } }. Web search works with Azure OpenAI deployments that support the Responses API web_search tool; it ran on a gpt-4.1-mini deployment when we tested it. Availability depends on your Azure resource and region, and a request fails if the deployment does not support it. Sources and citations use the same mapping as the OpenAI adapter.
On the client, each search arrives as an entry in the assistant message's serverToolCalls, with kind: 'provider' and builtin: 'web_search'. Hashbrown never runs it, and a client tool with the same name is never called in its place. The entry carries a ready-to-show label (for example Searched 'hashbrown ai' · 3 sources), the queries it ran, the sources it found, and its outcome. A failed search settles as complete with outcome: 'failure' and an error. See Server-Executed Tool Calls for every field.
The answer's url_citation annotations become citations on the assistant message. Each citation's sourceId is the id of a source, and quote holds the cited text. A citation's source can be on the call or on the message: in the sources of one of the message's serverToolCalls, or, when no search returned it, in the message's own sources. Look in both.
@Component({
selector: 'app-answer',
template: `
@for (call of message().serverToolCalls ?? []; track call.toolCallId) {
<p>{{ call.label }}</p>
}
@for (citation of message().citations ?? []; track $index) {
@if (hrefFor(citation.sourceId); as href) {
<a [href]="href">{{ citation.quote ?? href }}</a>
}
}
`,
})
export class AnswerComponent {
readonly message = input.required<UiAssistantMessage>();
hrefFor(sourceId: string): string | undefined {
const message = this.message();
return [
...(message.serverToolCalls ?? []).flatMap((call) => call.sources ?? []),
...(message.sources ?? []),
].find((source) => source.id === sourceId)?.href;
}
}
Azure OpenAI requires, as OpenAI does, inline citations to be clearly visible and clickable wherever your UI shows the answer. Source links may carry ?utm_source=openai; keep it.
Web search source lists need the builtInTools.webSearch option, because it also requests web_search_call.action.sources. A web_search tool you add through transformRequestOptions instead still streams as a provider tool call, with a label and queries, but without sources.
Code Execution
Enable the provider's Code Interpreter with builtInTools.codeExecution. Pass true for { type: 'code_interpreter', container: { type: 'auto' } }. Hashbrown also requests code_interpreter_call.outputs, alongside any reasoning or web search includes.
const stream = HashbrownAzure.stream.text({
clientOptions,
model: process.env.AZURE_OPENAI_DEPLOYMENT!,
input,
signal,
builtInTools: { codeExecution: true },
});
For native configuration, pass the tool's options without type. The adapter clones the configuration before building the request. For example, an automatic container can receive provider file IDs and a memory limit:
import type { AzureBuiltInTools } from '@hashbrownai/azure';
const builtInTools: AzureBuiltInTools = {
codeExecution: {
container: {
type: 'auto',
file_ids: ['file-input'],
memory_limit: '4g',
},
},
};
To use an existing provider container, pass its ID instead:
const builtInTools: AzureBuiltInTools = {
codeExecution: { container: 'cntr-existing' },
};
The Azure OpenAI resource and deployment must support Code Interpreter; unsupported requests fail through the normal provider error path. You can combine code execution with webSearch, application tools, reasoning and structured output.
Each execution appears in the assistant message's serverToolCalls with name: 'code_interpreter', kind: 'provider', builtin: 'code_execution', an icon of run and a ready-to-show label. A registered app tool with the same name remains separate. While code arguments stream, the call has status: 'inProgress'; once arguments finish, it has status: 'executing' until a native execution result arrives. Arguments ending does not mean execution succeeded.
A completed native execution settles as status: 'complete' with outcome: 'success'. Native failed or incomplete executions settle with outcome: 'failure', a readable error and a rejected public result. Successful result.value contains the serialized native result, including code, container_id, status and outputs (logs or image values). Native code: null means the provider did not supply code. Image outputs with a real URL can also appear in the call's sources.
Generated-file annotations belong to the assistant answer. Find a citation's source by matching citation.sourceId to source.id across the message's own sources and its calls' sources. A file source has kind: 'file', fileId, a title and, when supplied, containerId. Hashbrown does not invent a download URL or attach an answer file to a guessed execution. Character positions and quotes are optional: invalid spans, ambiguous Unicode offsets and noncontiguous text parts retain their source references without fabricated positions.
Your server owns file retrieval and storage. Use the native file/container IDs with the provider's file APIs, applying your app's access checks, and provide your own download route if needed. Containers and files remain provider-owned and ephemeral.
Every request uses store: false. Hashbrown omits provider execution display calls and their synthetic results from later requests, while preserving ordinary application calls and results. The earlier native execution context is therefore absent: automatic container reuse across turns is not promised. When your application needs retained container state, keep the returned container ID and supply it explicitly through codeExecution.container on the next run.
Sending Activities
Pass activities to send AG-UI activities alongside the model's output. Activities are display-only progress, such as a plan or a progress report, and the model never sees them. See Activities for how the client renders them.
import { HashbrownAzure } from '@hashbrownai/azure';
const stream = HashbrownAzure.stream.text({
clientOptions: {
apiKey: process.env.AZURE_API_KEY!,
endpoint: process.env.AZURE_ENDPOINT!,
apiVersion: '2025-04-01-preview',
},
model: process.env.AZURE_MODEL!,
input,
signal,
activities: async ({ activity, model }) => {
const plan = activity.snapshot(`plan-${input.runId}`, 'plan', {
steps: ['Read the question', 'Answer'],
done: 0,
});
await model;
plan.patch([{ op: 'replace', path: '/done', value: 2 }]);
},
});
The callback receives an activity writer, a model promise, and the run's signal:
activity.snapshot(id, activityType, content)sends anACTIVITY_SNAPSHOTand returns a handle. The handle'spatch(operations)sends anACTIVITY_DELTAwith RFC 6902 JSON Patch operations, andreplace(content)sends a new snapshot.- Activity ids must be unique within the thread. Reusing an id from an earlier turn updates that turn's activity in place, so the example builds the id from
input.runIdto give each run its own plan. modelresolves when the model stream ends, before the run finishes, and rejects if the model call fails.- Activity events and model events are sent in the order they happen. The callback starts after
RUN_STARTED, and the terminal event waits until the callback settles. Model text streams as it arrives and is never held back. - If the callback throws while the model is streaming, Hashbrown aborts the model and ends the run with one
RUN_ERROR. If it throws after the model has finished,RUN_ERRORreplacesRUN_FINISHED. If the model fails too, the model's error wins. - When the client disconnects,
signalaborts. No terminal event is sent, and writes become no-ops. - A write after the run has closed throws, as does a second snapshot that reuses an id with a different
activityType.
Transform Request Options
transformRequestOptions receives the final Responses API request (ResponseCreateParamsStreaming) after AG-UI input has been mapped. Use it for server-owned provider settings.
const stream = HashbrownAzure.stream.text({
clientOptions: {
apiKey: process.env.AZURE_API_KEY!,
endpoint: process.env.AZURE_ENDPOINT!,
apiVersion: process.env.AZURE_API_VERSION ?? '2025-04-01-preview',
},
model: process.env.AZURE_MODEL!,
input,
transformRequestOptions: (options) => ({
...options,
max_output_tokens: 2048,
reasoning: { ...options.reasoning, effort: 'low' },
}),
});
Learn more about transformRequestOptions
Explore it in the workbench
Open the workbench below and ask for a two-step plan. In Requests, compare the AG-UI input with the streamed response; in UI, follow the resolved props into the trusted card. State stays unchanged because this lesson previews a plan without accepting it.
The workbench's server route adds bounded lesson policy around an OpenAI adapter. Compare that route with the Azure OpenAI route above: the client contract stays AG-UI, while authentication, native request options, and capability support belong to the selected provider. This exercise does not call Azure OpenAI or verify its provider-specific behavior.