> ## Documentation Index
> Fetch the complete documentation index at: https://narev.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started

> First steps with Azure (AI Foundry) middleware for tracking AI costs.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @ai-billing/azure @ai-billing/core @ai-sdk/azure ai
  ```

  ```bash pnpm theme={null}
  pnpm add @ai-billing/azure @ai-billing/core @ai-sdk/azure ai
  ```

  ```bash yarn theme={null}
  yarn add @ai-billing/azure @ai-billing/core @ai-sdk/azure ai
  ```
</CodeGroup>

## Overview

The `@ai-billing/azure` package provides middleware for tracking token usage and calculating costs when
using Azure-hosted models with the Vercel AI SDK, via `@ai-sdk/azure`.

This package targets **Azure AI Foundry** (`*.services.ai.azure.com`), not classic Azure OpenAI
(`*.openai.azure.com`). The AI SDK routes Foundry deployments through the Responses API
(`provider: "azure.responses"`), whose raw usage payload uses `input_tokens`/`output_tokens` field names
(and `input_tokens_details.{cached_tokens,cache_write_tokens}` / `output_tokens_details.reasoning_tokens`)
rather than classic Chat Completions' `prompt_tokens`/`completion_tokens` naming. The middleware reads
those Responses-API field names when present, and falls back to the AI SDK's normalized usage fields
otherwise, so it also works against classic Azure OpenAI resources.

It captures Foundry-specific metrics, such as `inputCacheReadTokens`, `inputCacheWriteTokens`, and
`internalReasoningTokens`, ensuring that prompt-caching and reasoning costs are accurately reflected.

## Usage

To use the middleware, wrap your Azure model using `wrapLanguageModel` from the `ai` package and pass the
`createAzureMiddleware`.

<Steps>
  <Step title="Initialize the Azure provider">
    Set up the Azure provider against your AI Foundry resource. Foundry resources are reached with a
    `baseURL` + `apiVersion` pair (not the classic `resourceName` option), and models are addressed by
    their account-specific deployment name.

    ```typescript theme={null}
    import { createAzure } from '@ai-sdk/azure';

    const azure = createAzure({
      apiKey: process.env.AZURE_API_KEY,
      baseURL: `${process.env.AZURE_URL!.replace(/\/+$/, '')}/openai/v1`,
      apiVersion: 'preview',
    });

    const deployment = process.env.AZURE_DEPLOYMENT!;
    ```
  </Step>

  <Step title="Define model pricing">
    Set up a price resolver to define the costs for your deployments. Because Foundry deployment names are
    account-specific (not a stable public model id), key the pricing map dynamically off the same deployment
    name rather than a hardcoded literal.

    ```typescript theme={null}
    import { createObjectPriceResolver } from '@ai-billing/core';

    const priceResolver = createObjectPriceResolver({
      [deployment]: {
        promptTokens: 0.14 / 1_000_000,
        completionTokens: 0.28 / 1_000_000,
        internalReasoningTokens: 0.28 / 1_000_000,
      },
    });
    ```
  </Step>

  <Step title="Create the billing middleware">
    Initialize the Azure billing middleware. You need to provide a destination (such as `consoleDestination`)
    where billing events will be sent, along with your `priceResolver`.

    ```typescript theme={null}
    import { createAzureMiddleware } from '@ai-billing/azure';
    import { consoleDestination } from '@ai-billing/core';

    const billingMiddleware = createAzureMiddleware({
      destinations: [consoleDestination()],
      priceResolver: priceResolver,
    });
    ```
  </Step>

  <Step title="Wrap the model">
    Use `wrapLanguageModel` from the `ai` package to apply the billing middleware to your Azure model.

    ```typescript theme={null}
    import { wrapLanguageModel } from 'ai';

    const wrappedModel = wrapLanguageModel({
      model: azure(deployment),
      middleware: billingMiddleware,
    });
    ```
  </Step>

  <Step title="Use the wrapped model">
    Finally, use the wrapped model with AI SDK functions like `generateText` or `streamText`. The billing
    middleware will automatically track tokens, handle caching and reasoning metrics, and calculate costs.

    ```typescript theme={null}
    import { generateText } from 'ai';

    const result = await generateText({
      model: wrappedModel,
      prompt: 'What is the capital of Sweden?',
    });
    ```
  </Step>
</Steps>