zuplo 7.8.8 → 7.8.10

package/docs/ai-gateway/integrations/ai-sdk.mdx

@@ -53,7 +53,8 @@ configure.
 Each provider package appends its own operation path to `baseURL`, so pick the
 model factory that targets an endpoint the gateway serves:
 `/v1/chat/completions` for OpenAI-compatible requests, `/v1/messages` for
-Anthropic, `/v1/embeddings`, and `/v1/responses` for OpenAI only. The examples
+Anthropic, `/v1/embeddings` for every provider with embedding models, and
+`/v1/responses` for OpenAI and Azure OpenAI-compatible deployments. The examples
 below use the right factory for each provider.
 
 ### OpenAI
@@ -161,6 +162,131 @@ const { text } = await generateText({
 });
 ```
 
+### Azure AI
+
+Use `@ai-sdk/azure`. Set `baseURL` to your app's URL plus `/v1`, and pass the
+app's API key through `tokenProvider`—not `apiKey`. The provider sends `apiKey`
+as the `api-key` header, which the gateway doesn't read, so the request fails
+with a `401`; `tokenProvider` puts the same key on `Authorization: Bearer`,
+which the gateway does read. Leave `useDeploymentBasedUrls` off—it moves the
+deployment into the path as `/deployments/{id}/chat/completions`, which isn't a
+gateway endpoint and returns a `404`. To keep `useDeploymentBasedUrls: true`—or
+to authenticate with `apiKey` rather than `tokenProvider`—install the
+[SDK path shim](../cookbooks/sdk-path-shim.mdx), a custom policy that rewrites
+the deployment path and maps the `api-key` header.
+
+Reference models by deployment name, as `providerName/deploymentName`—see
+[Azure serves deployments, not model names](../azure-ai.mdx#azure-serves-deployments-not-model-names).
+
+```typescript
+import { createAzure } from "@ai-sdk/azure";
+import { generateText } from "ai";
+
+const appKey = process.env.ZUPLO_AI_GATEWAY_API_KEY;
+if (!appKey) {
+  throw new Error("Set ZUPLO_AI_GATEWAY_API_KEY to the app's API key");
+}
+
+const azure = createAzure({
+  baseURL:
+    "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1",
+  tokenProvider: async () => appKey,
+});
+
+const { text } = await generateText({
+  model: azure.chat("azureai/my-gpt"),
+  prompt: "Write a one-sentence bedtime story about a unicorn.",
+});
+```
+
+Call `azure.chat(id)` for chat completions and `azure.textEmbeddingModel(id)`
+for embeddings. The bare `azure(id)` callable targets the Responses API, which
+Azure serves for its OpenAI-compatible deployments, so that form works too.
+
+For a Claude deployment on a Foundry resource, either call
+`azure.chat("azureai/my-claude")`—the gateway translates the chat completion to
+the Messages API—or use `@ai-sdk/anthropic` with `authToken` for the native
+Messages API:
+
+```typescript
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { generateText } from "ai";
+
+const anthropic = createAnthropic({
+  authToken: process.env.ZUPLO_AI_GATEWAY_API_KEY,
+  baseURL:
+    "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1",
+});
+
+const { text } = await generateText({
+  model: anthropic("azureai/my-claude"),
+  prompt: "Write a one-sentence bedtime story about a unicorn.",
+});
+```
+
+### Vertex AI
+
+The `@ai-sdk/google-vertex` provider posts to Vertex's own publisher paths—
+`{model}:generateContent` for Gemini, and `{model}:rawPredict` for Claude on its
+`/anthropic` entry—neither of which the AI Gateway serves, so both return a
+`404`. Use the
+[OpenAI-compatible provider](https://ai-sdk.dev/providers/openai-compatible-providers)
+for Gemini and Model Garden models, and `@ai-sdk/anthropic` for Claude. For
+Claude, the [SDK path shim](../cookbooks/sdk-path-shim.mdx) can instead repoint
+`@ai-sdk/google-vertex/anthropic` onto `/v1/messages`; the Gemini entry can't be
+repointed.
+
+Every Vertex model reference has two slashes, `providerName/publisher/model`—see
+[Model references include the publisher prefix](../vertex-ai.mdx#model-references-include-the-publisher-prefix).
+
+```typescript
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import { generateText } from "ai";
+
+const gateway = createOpenAICompatible({
+  name: "zuplo-ai-gateway",
+  apiKey: process.env.ZUPLO_AI_GATEWAY_API_KEY,
+  baseURL:
+    "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1",
+});
+
+const { text } = await generateText({
+  model: gateway("vertexai/google/gemini-3.7-flash"),
+  prompt: "Write a one-sentence bedtime story about a unicorn.",
+});
+```
+
+The same provider embeds through `textEmbeddingModel`, which the gateway
+translates onto Vertex's embedding API:
+
+```typescript
+import { embedMany } from "ai";
+
+const { embeddings } = await embedMany({
+  model: gateway.textEmbeddingModel("vertexai/google/gemini-embedding-2"),
+  values: ["first document", "second document"],
+});
+```
+
+Claude models serve the native Messages API on Vertex, so use
+`@ai-sdk/anthropic` with `authToken`:
+
+```typescript
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { generateText } from "ai";
+
+const anthropic = createAnthropic({
+  authToken: process.env.ZUPLO_AI_GATEWAY_API_KEY,
+  baseURL:
+    "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1",
+});
+
+const { text } = await generateText({
+  model: anthropic("vertexai/anthropic/claude-haiku-4-5@20251001"),
+  prompt: "Write a one-sentence bedtime story about a unicorn.",
+});
+```
+
 ## Provider options the gateway doesn't forward
 
 On the OpenAI-shaped endpoints (`/v1/chat/completions`, `/v1/embeddings`, and

package/docs/ai-gateway/integrations/claude-code.mdx

@@ -2,92 +2,70 @@
 title: Claude Code
 sidebar_label: Claude Code
 description:
-  Point Claude Code at an AI Gateway app so every Claude Code request is
-  authenticated, metered, and routed by the gateway.
+  Route Claude Code requests through a Zuplo AI Gateway app, with a provider key
+  or your Claude subscription.
 ---
 
-You can configure [Claude Code](https://www.claude.com/product/claude-code) to
-send its model requests through the Zuplo AI Gateway, so the gateway
-authenticates, meters, and routes every Claude Code session.
+Route [Claude Code](https://www.claude.com/product/claude-code) through the
+Zuplo AI Gateway. The gateway authenticates, meters, and routes every session.
 
-The gateway can authenticate to Anthropic in two ways. Pick one before you
-configure Claude Code:
+The gateway authenticates to Anthropic in one of two ways:
 
-| Approach                                                  | The gateway sends Anthropic                                           | Claude Code sends the gateway                                             |
-| --------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| [Configured provider key](#use-a-configured-provider-key) | The Anthropic API key saved on your provider                          | The app's API key as `ANTHROPIC_AUTH_TOKEN`                               |
-| [Your Claude subscription](#use-your-claude-subscription) | The credential from your `claude.ai` login, such as a Claude Max plan | The app's API key in a `zp-gateway-api-key` header, plus your login as-is |
+| Approach                                             | The gateway sends Anthropic                       | Claude Code sends the gateway                                       |
+| ---------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------- |
+| [Provider key](#use-a-provider-key)                  | The Anthropic API key saved on your provider      | The app's API key as `ANTHROPIC_AUTH_TOKEN`                         |
+| [Claude subscription](#use-your-claude-subscription) | Your `claude.ai` login, such as a Claude Max plan | The app's API key in a `zp-gateway-api-key` header, plus your login |
 
-Both approaches share the same provider, team, and app setup, and the same model
-configuration.
-
-## Claude Code Setup
+## Prerequisites
 
 <Stepper>
 
-1. Create a [new provider](../managing-providers.mdx) in the AI Gateway for
-   Anthropic
-
-2. [Set up a new team](../managing-teams.mdx)
-
-3. If you plan to use your Claude subscription, configure the team's
-   [API Key Authentication policy](#configure-the-api-key-authentication-policy)
-   for passthrough before you create the app
+1. Create an Anthropic [provider](../managing-providers.mdx) in the AI Gateway.
 
-4. Create a [new app](../managing-apps.mdx) to use with Claude Code and assign
-   it to the team you created
+2. [Create a team](../managing-teams.mdx). For the subscription approach,
+   [configure its API Key Authentication policy](#configure-the-api-key-authentication-policy)
+   now.
 
-5. Copy the **API URL** and **API Key** shown at the top of the app page
+3. [Create an app](../managing-apps.mdx) for Claude Code and assign it to the
+   team.
 
-6. Add the gateway URL, the app's API key, and model mappings to
-   `.claude/settings.json`, following the section below for the approach you
-   chose
+4. Copy the **API URL** and **API Key** from the app page.
 
 </Stepper>
 
-### Before copying: replace the provider name
+## Configure Claude Code
 
-:::warning
+:::warning{title="Replace the provider name"}
 
-The examples below assume your provider is named `anthropic`. Replace that
-prefix with the name of **your** provider before copying the configuration. For
-example, a provider named `my-anthropic` routes `my-anthropic/claude-sonnet-5`,
-while a Bedrock provider named `bedrock` routes
-`bedrock/anthropic.claude-sonnet-5`. The model part must be an id that provider
-understands.
+The examples assume your provider is named `anthropic`. Replace that prefix with
+the name of **your** provider before copying anything. A provider named
+`my-anthropic` routes `my-anthropic/claude-sonnet-5`; a Bedrock provider named
+`bedrock` routes `bedrock/anthropic.claude-sonnet-5`. The model part must be an
+ID that provider serves. Check [your provider's page](../managing-providers.mdx)
+in the Portal.
 
 :::
 
-The gateway routes every request using `providerName/model`. The provider prefix
-picks which of your providers handles the request — a gateway can contain
-several providers that serve Anthropic models.
-
-### Where Claude Code reads its settings
-
-You can configure Claude Code either globally or per project by editing the
-settings file:
+Claude Code reads `~/.claude/settings.json`, or `.claude/settings.json` in a
+project. Add the block for your approach, then restart Claude Code.
 
-- **Global:** `~/.claude/settings.json`
-- **Project-specific:** `.claude/settings.json` in your project directory
-
-Each approach below shows the `env` and `modelOverrides` blocks to add to that
-file. Restart Claude Code after saving it, and all your Claude Code LLM requests
-route through the AI Gateway.
-
-:::note
-
-Claude Code appends `/v1/messages` to the base URL itself, so
-`ANTHROPIC_BASE_URL` is the app's URL _without_ the `/v1` suffix.
-
-:::
+### Rules
 
-## Use a configured provider key
+- `ANTHROPIC_BASE_URL` is the app's API URL _without_ `/v1`. Claude Code appends
+  `/v1/messages`.
+- Set every `ANTHROPIC_*_MODEL` variable and every `modelOverrides` entry.
+  Claude Code's built-in model names have no prefix. The variables map the
+  `opus`, `sonnet`, `haiku`, and `fable` aliases;
+  [`modelOverrides`](https://code.claude.com/docs/en/model-config#override-model-ids-per-version)
+  maps exact IDs; the `/model` picker can select either.
+- The app's
+  [Model Filtering](../../policies/ai-gateway-model-filtering-v2-inbound.mdx)
+  policy controls which models the app can use.
 
-With this approach the gateway calls Anthropic with the API key you saved on the
-[provider](../managing-providers.mdx). Claude Code presents only the app's API
-key, and Anthropic bills the account that owns the provider key.
+## Use a provider key
 
-Add the following configuration to the settings file:
+The gateway calls Anthropic with the key saved on your provider. Anthropic bills
+that key's account. Your Claude subscription is not used.
 
 ```json
 {
@@ -111,58 +89,37 @@ Add the following configuration to the settings file:
 }
 ```
 
-`ANTHROPIC_AUTH_TOKEN` replaces whatever login Claude Code would otherwise use,
-so this approach doesn't consume your Claude subscription.
+`ANTHROPIC_AUTH_TOKEN` replaces your `claude.ai` login.
 
 ## Use your Claude subscription
 
-With this approach Claude Code stays signed in to `claude.ai` — for example with
-a Claude Max plan — and the gateway forwards that login credential to Anthropic
-as the request's provider credential. The app's API key travels in a separate
-`zp-gateway-api-key` header, so the gateway still authenticates the app, applies
-its policy chain, and meters its usage.
-
-Two pieces of configuration make this work: the app's **API Key Authentication**
-policy accepts the app key from the `zp-gateway-api-key` header and passes the
-`Authorization` header through, and Claude Code sends both headers.
+Claude Code stays signed in to `claude.ai`. The gateway forwards that login to
+Anthropic and reads the app's API key from a separate `zp-gateway-api-key`
+header, so it still authenticates the app, runs its policies, and meters usage.
 
 ### Configure the API Key Authentication policy
 
-The [API Key Authentication](../../policies/ai-gateway-auth-v2-inbound.mdx)
-policy needs three options for passthrough:
-
-| Option                  | Value                | Effect                                                   |
-| ----------------------- | -------------------- | -------------------------------------------------------- |
-| `credentialPassthrough` | On                   | Forward the caller's `Authorization` header to Anthropic |
-| `authHeader`            | `zp-gateway-api-key` | Read the app's API key from this header instead          |
-| `authScheme`            | Empty value          | The header holds the bare key, with no `Bearer` prefix   |
-
-You can set these options on the team's
-[policy template](../policy-templates.mdx), so every app created in the team
-starts with passthrough enabled, or on a single app's **Policies** tab. The
-steps below use the team template; the app's policy editor works the same way.
+On the team's [policy template](../policy-templates.mdx), or on one app's
+**Policies** tab, edit **API Key Authentication**:
 
 <Stepper>
 
-1. Open the team in the Zuplo Portal and select its **Policy Template** tab.
-
-2. Click the edit (pencil) icon on the **API Key Authentication** entry.
-
-3. Turn on **credentialPassthrough**.
+1. Turn on **credentialPassthrough**.
 
-4. Set **authHeader** to `zp-gateway-api-key`.
+2. Set **authHeader** to `zp-gateway-api-key`.
 
-5. Leave **authScheme** blank and click **Use an empty value for authScheme**.
-   The field then reports "Empty value set. The default (Bearer) is not
-   applied." Clearing the field alone isn't enough: a blank field omits the
-   option, so the `Bearer` default still applies and every request fails with
-   `401 Invalid Authorization Scheme`.
+3. Leave **authScheme** blank and click **Use an empty value for authScheme**.
+   The field reports "Empty value set. The default (Bearer) is not applied."
 
-6. Click **Apply**, then **Save changes**.
+4. Click **Apply**, then **Save changes**.
 
 </Stepper>
 
-The **JSON** editor mode shows the equivalent options:
+A blank **authScheme** field is not an empty value. It omits the option, the
+`Bearer` default still applies, and every request fails with
+`401 Invalid Authorization Scheme`.
+
+In the **JSON** editor:
 
 ```json
 {
@@ -172,29 +129,20 @@ The **JSON** editor mode shows the equivalent options:
 }
 ```
 
-### The provider still needs an API key
-
-The Portal requires an API key to save an Anthropic provider, and passthrough
-requests never send it: the request to Anthropic carries the caller's credential
-instead. Anything else that uses this provider's configured credential still
-needs a real key. That includes apps on this gateway that don't use passthrough
-and any
-[Fallback Model](../../policies/ai-gateway-fallback-model-v2-inbound.mdx)
-target, because fallback requests use the provider's configured credential
-rather than the caller's. If nothing on the gateway uses the configured
-credential, a placeholder value works.
+### Rules
 
-The app's playground in the Portal sends the app key as a bearer token in
-`Authorization`, so it can't call an app that uses passthrough. Test the app
-from Claude Code instead, as described below.
+- The provider still needs an API key to save. Passthrough requests never use
+  it. Apps without passthrough and every
+  [Fallback Model](../../policies/ai-gateway-fallback-model-v2-inbound.mdx)
+  target do. If nothing uses it, a placeholder value works.
+- The Portal playground sends the app key as `Authorization: Bearer`, so it
+  can't call a passthrough app. Test from Claude Code.
+- Do not set `ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY`, in the settings file
+  or in your shell. Either one replaces your login, and the gateway forwards it
+  to Anthropic instead.
 
 ### Configure Claude Code
 
-Add the following configuration to the settings file. Don't set
-`ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY` here or in your shell: either one
-replaces your `claude.ai` login, and the gateway would then forward that value
-to Anthropic as the credential.
-
 ```json
 {
   "env": {
@@ -217,73 +165,27 @@ to Anthropic as the credential.
 }
 ```
 
-`ANTHROPIC_CUSTOM_HEADERS` adds the `zp-gateway-api-key` header to every request
-Claude Code makes, while Claude Code keeps sending its own `Authorization`
-header from your login. The gateway consumes those incoming headers, uses the
-login credential to authenticate the Anthropic request, and never sends your app
-key to Anthropic.
+`ANTHROPIC_CUSTOM_HEADERS` adds the `zp-gateway-api-key` header. Claude Code
+keeps sending its own `Authorization` header from your login. The gateway never
+sends your app key to Anthropic.
 
-### Verify the subscription setup
-
-Restart Claude Code, then confirm which credential it's using and send one
-request through the gateway:
+## Verify
 
 ```bash
 claude auth status --text
 claude -p "Reply with the single word OK"
 ```
 
-The first command should report that you're signed in with your `claude.ai`
-account rather than an API key or auth token. The second returns a short reply,
-and the request appears in the app's usage in the Zuplo Portal. In an
-interactive session, `/status` shows the same login information.
-
-If the request fails:
-
-- `401` with `Invalid Authorization Scheme` — `authScheme` still has its
-  `Bearer` default. Set it to an explicit empty value in the policy.
-- `401` with `Header configured by options.authHeader is missing` — Claude Code
-  didn't send `zp-gateway-api-key`. Check `ANTHROPIC_CUSTOM_HEADERS`.
-- `401` with `credentialPassthrough requires a non-empty Authorization header` —
-  Claude Code isn't signed in. Run `claude` and use `/login`.
-- An authentication error from Anthropic — Anthropic rejected the forwarded
-  login credential. Sign in to Claude Code again.
-
-## Configure every Claude Code model variable
-
-The model ids in these examples reflect what was current when this page was
-written, and ids differ across providers — a Bedrock provider serves different
-ids than Anthropic directly, and availability can vary by region. Check
-[your provider's page](../managing-providers.mdx) in the portal for the models
-it currently serves, and use those ids.
-
-None of Claude Code's built-in model names carry a provider prefix, so each of
-the model variables above must be set to a prefixed reference:
-
-- `ANTHROPIC_MODEL` — the startup model. Set it to a prefixed reference so the
-  gateway can route the first request.
-- `ANTHROPIC_SMALL_FAST_MODEL` — the model for background tasks.
-- `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`,
-  `ANTHROPIC_DEFAULT_HAIKU_MODEL`, `ANTHROPIC_DEFAULT_FABLE_MODEL` — what the
-  `opus`/`sonnet`/`haiku`/`fable` aliases resolve to, so `claude --model opus`
-  and `/model sonnet` keep working. In these examples,
-  `ANTHROPIC_DEFAULT_FABLE_MODEL` maps `fable` to `anthropic/claude-fable-5-1`.
-
-Claude Code's `/model` picker can select either an alias or an exact model ID.
-`ANTHROPIC_DEFAULT_*_MODEL` maps aliases to gateway model names;
-[`modelOverrides`](https://code.claude.com/docs/en/model-config#override-model-ids-per-version)
-maps exact IDs. The examples configure both so either selection works through
-the gateway.
-
-:::caution{title='HTTP 400: model must use "providerName/model"'}
-
-This error means the selected model lacks its provider prefix. At startup, check
-`ANTHROPIC_MODEL`. After choosing a picker entry, check its `modelOverrides`
-entry, or type `/model fable` to use the configured alias. Restart Claude Code
-after editing the settings file.
+With the subscription approach, the first command reports a `claude.ai` login,
+not an API key or auth token. The request appears in the app's usage in the
+Zuplo Portal.
 
-:::
+## Troubleshooting
 
-The app's
-[Model Filtering](../../policies/ai-gateway-model-filtering-v2-inbound.mdx)
-policy controls which models the app may use.
+| Error                                                                   | Fix                                                                                                                                        |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `400` `model must use "providerName/model"`                             | The selected model has no provider prefix. Check `ANTHROPIC_MODEL`, or the picker entry's `modelOverrides` mapping. Restart after editing. |
+| `401` `Invalid Authorization Scheme`                                    | `authScheme` still has its `Bearer` default. Set an explicit empty value.                                                                  |
+| `401` `Header configured by options.authHeader is missing`              | Claude Code didn't send `zp-gateway-api-key`. Check `ANTHROPIC_CUSTOM_HEADERS`.                                                            |
+| `401` `credentialPassthrough requires a non-empty Authorization header` | Claude Code isn't signed in. Run `claude` and use `/login`.                                                                                |
+| An authentication error from Anthropic                                  | Anthropic rejected the forwarded login. Sign in to Claude Code again.                                                                      |