# AI

> Deterministic OpenAI Responses, Chat Completions, and Anthropic Messages emulation for local development and CI. Use when the user needs to test an app that calls an LLM without network access, keys, or cost, including text, streaming, structured output, tool loops, reasoning, refusals, retries, timeouts, and stored conversations. Triggers include "mock OpenAI", "emulate OpenAI", "test the OpenAI SDK", "mock Anthropic", "emulate Anthropic", "test the Anthropic SDK", "test the AI SDK", "generateText", "generateObject", "streamText", "Chat Completions", "Responses API", "Messages API", "simulate a 429", "test tool calls", "no API key", or any task requiring a local AI provider.

- Skill: `vercel-labs/ai-2` (Agent Skill)
- Install (CLI): `npx get-skill add vercel-labs/ai-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vercel-labs/ai-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Vercel Labs (https://skillmd.com/u/vercel-labs)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/vercel-labs/ai-2

---


# AI Provider Emulator

Deterministic OpenAI Responses, Chat Completions, and Anthropic Messages emulation. Replies are scripted by rules, not generated by a model, so the same request returns the same answer every run. Use it to test text, streaming, structured output, tool-calling agent loops, reasoning, refusals, stored conversations, errors, mid-stream disconnects, and stalls, offline and without keys.

## Start

```bash
npx emulate start --service ai --port 4014
```

A single selected service otherwise uses the base port, normally 4000. In an all-services run, `ai` listens on port 4014. Startup prints the base URL setup for the service.

| What                 | URL                          |
| -------------------- | ---------------------------- |
| Base URL for clients | `http://localhost:4014/v1`   |
| Inspector            | `http://localhost:4014/`     |
| Control routes       | `http://localhost:4014/_ai/` |

Programmatically:

```typescript
import { createEmulator } from "emulate";

const ai = await createEmulator({
  service: "ai",
  port: 4014,
  seed: {
    ai: {
      rules: [{ id: "hello", match: { textContains: "Hi" }, reply: [{ type: "text", text: "Hello from emulate." }] }],
    },
  },
});
```

## Point Clients at the Emulator

Any path prefix works, such as `/v1` or `/api/v1`. The format is selected from the end of the path, so `.../chat/completions` uses Chat Completions, `.../responses` uses Responses, and `.../messages` uses Anthropic Messages. The Anthropic SDK appends `/v1/messages`, so point it at the origin without `/v1`. API keys are accepted but never required, stored, or logged. Any model id is accepted and echoed back. Every generation response carries a deterministic request id: `x-request-id` on the OpenAI routes and `request-id` on the Anthropic Messages route.

### Official OpenAI SDK

```typescript
import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "http://localhost:4014/v1",
  apiKey: "test",
});

const chat = await openai.chat.completions.create({
  model: "gpt-x",
  messages: [{ role: "user", content: "Hi" }],
});

const response = await openai.responses.create({
  model: "gpt-x",
  input: "Hi",
});
```

The SDK also reads environment variables. Set `OPENAI_BASE_URL=http://localhost:4014/v1` and any `OPENAI_API_KEY`, or pass an explicit `baseURL` as above.

### Vercel AI SDK

Use the standard OpenAI provider. `openai(...)` posts to `/responses`; `openai.chat(...)` posts to `/chat/completions`.

```typescript
import { createOpenAI } from "@ai-sdk/openai";
import { generateText } from "ai";

const openai = createOpenAI({
  baseURL: "http://localhost:4014/v1",
  apiKey: "test",
});

const responses = await generateText({
  model: openai("anthropic/claude-sonnet-5"),
  prompt: "Hi",
});

const chat = await generateText({
  model: openai.chat("gpt-x"),
  prompt: "Hi",
});
```

### Compatible providers and gateways

`@ai-sdk/openai-compatible` works in Chat mode against the same base URL. Vercel AI Gateway's OpenAI-compatible `/v1` surface works through either provider, and any model slug is accepted.

```typescript
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";

const gateway = createOpenAICompatible({
  name: "emulate",
  baseURL: "http://localhost:4014/v1",
  apiKey: "test",
});
```

`createOpenAICompatible` sends `json_object` without a schema unless the provider sets `supportsStructuredOutputs: true`, so `generateObject` against the default `{}` reply fails its schema check. Set `supportsStructuredOutputs: true`, or script the object with an `object` reply rule.

The private `@ai-sdk/gateway` protocol is not supported. Use an OpenAI-compatible provider instead.

An unsupported data path such as `/v1/embeddings` returns a native 404 naming the supported data paths.

## Defaults

With no matching rule:

| Request                            | Reply                                                       |
| ---------------------------------- | ----------------------------------------------------------- |
| Plain text                         | Echoes the latest user text                                 |
| Schema inside the supported subset | Deterministic, schema-valid object                          |
| JSON mode without a schema         | `{}`                                                        |
| Forced tool choice                 | A call with arguments generated from the tool schema        |
| Tool result present                | An acknowledgement naming the tool or call                  |
| Attachments with no text           | `Received N files (names or media types, comma-separated).` |

A strict JSON Schema is checked against OpenAI's documented subset first, and a rejected keyword returns OpenAI's own error, for example `Invalid schema for response_format 'trip': In context=('properties', 'trip'), 'allOf' is not permitted.` with `param: "response_format"`, or `param: "text.format"` on the Responses endpoint. Composition keywords `allOf`, `not`, `dependentRequired`, `dependentSchemas`, `if`, `then`, and `else` are rejected. An object that does not set `additionalProperties: false`, or leaves a property out of `required`, is rejected the same way. A function tool marked `strict` gets the same checks on its parameters, worded `Invalid schema for function '<name>'` with code `invalid_function_parameters`. Non-strict schemas are not checked.

The generator handles `type`, `properties`, `required`, `enum`, `const`, `items`, numeric and length bounds, `nullable`, the first `anyOf` branch that yields a valid sample, the first `oneOf` branch whose sample matches exactly one branch (the native 400 when none does), common string `format` values, and local `$ref`, with recursion bounded. Keywords written next to `$ref`, `anyOf`, or `oneOf` shape the sample as well. A schema outside that set returns a native 400 naming the schema path. A string with `pattern` is generated only when it also has a common `format` the generator knows; otherwise the request returns the native 400 asking for an explicit reply rule. A format sample, `enum` value, or `const` that fails the pattern returns the same 400, and pattern checks run under a time limit. Provider rules differ, so the dialect is chosen per request: a model name starting with `claude`, with or without a provider prefix such as `anthropic/`, is checked with Anthropic's rules, anything else with OpenAI's, on Chat Completions and Responses alike. The error envelope stays the one the endpoint speaks, matching Anthropic's OpenAI compatibility layer.

Anthropic requires `response_format` to be `json_schema` with `strict: true`, rejects `json_object` with a 400, and applies its schema limits on top: no `oneOf`, no numeric or string constraints, no array constraints beyond `minItems` 0 or 1, no external references.

## Rules

Rules live under `ai.rules` in seed config or are replaced at runtime over HTTP. They are evaluated in order and the first match wins. Every supplied matcher must hold. `times` is a per-rule budget consumed on every selection, including injected errors, so an exhausted rule is skipped.

```yaml
ai:
  strict: false
  timing:
    ttftMs: 0
    chunkDelayMs: 0
  random:
    seed: 7
  models: [gpt-x]
  rules:
    - id: weather-call
      match:
        textContains: weather
        tool: get_weather
        hasToolResult: false
      times: 1
      reply:
        - type: tool_call
          name: get_weather
          arguments:
            city: Paris

    - id: weather-result
      match:
        hasToolResult: true
      reply:
        - type: text
          text: The temperature in Paris is 20 C.

    - id: rate-limit-once
      match:
        textContains: retry
      times: 1
      error:
        status: 429
        message: Injected rate limit. Retry this request.
        headers:
          retry-after: "1"
```

In a project config with a `services:` map, the seed goes under `services.<name>.seed`, not a top-level `ai:` block, which would start a second service named `ai`:

```yaml
services:
  llm:
    emulator: ai
    seed: { rules: [{ id: weather, match: { textContains: weather }, reply: [{ type: text, text: Sunny }] }] }
```

### Matchers

| Key             | Matches                                                                                                              |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| `model`         | Model id, with `*` wildcards                                                                                         |
| `format`        | `openai-chat`, `openai-responses`, or `anthropic-messages`                                                           |
| `stream`        | Boolean                                                                                                              |
| `textContains`  | Case-sensitive text in the latest user instruction, excluding tool results                                           |
| `tool`          | A declared tool name, with `*` wildcards                                                                             |
| `hasToolResult` | Whether the current continuation carries a tool result                                                               |
| `file`          | `true` for any attachment, including one returned inside a tool result, or a media-type glob such as `application/*` |

### Replies

A rule has one of `reply`, `variants`, or `error`. Reply events are ordered:

| Event     | Shape                                  | Notes                                                                                                  |
| --------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Text      | `{ type: text, text }`                 | Normal assistant text                                                                                  |
| Object    | `{ type: object, value }`              | Sent as JSON text, for structured output                                                               |
| Tool call | `{ type: tool_call, name, arguments }` | `arguments` must be a JSON object, and a string is rejected at startup and on `PUT`; ids are generated |
| Reasoning | `{ type: reasoning, text }`            | A Responses summary or a Messages `thinking` block; Chat has no field for it                           |
| Refusal   | `{ type: refusal, text }`              | Native refusal shape                                                                                   |

With `reply` or `variants`, a rule may set `finish` to `stop`, `tool_calls`, `length`, `refusal`, or `content_filter`. Without it, a reply with a tool call ends with `tool_calls`, and anything else ends with `stop`. A refusal is recorded as `refusal` in the call record, but the client still sees `stop` on Chat Completions and `completed` on Responses. A `finish: refusal` override is recorded the same way. `length` and `content_filter` reach the client as `finish_reason` on Chat Completions and as `status: "incomplete"` on Responses.

Request limits apply to every reply, scripted or default. A stop sequence (`stop` on Chat Completions) cuts the reply text at the first match; the sequence is not returned, nothing after it is sent, and the reply ends with `stop`. On Messages, `stop_sequences` works the same way, and the reply reports `stop_reason: "stop_sequence"` with the match in `stop_sequence`. A token cap (`max_completion_tokens` or `max_tokens` on Chat Completions, `max_output_tokens` on Responses) counts output at one token per four characters, the same estimate the usage numbers use. A reply over the cap is cut there and ends with `length`, which Responses reports as `status: "incomplete"` with `incomplete_details.reason: "max_output_tokens"`. A tool call that does not fit is dropped whole rather than sent partially. On Messages, `max_tokens` is the cap, and a reply over it ends with `stop_reason: "max_tokens"`. A rule's own `finish` still wins when it is set.

### Errors and faults

An `error` rule returns a native HTTP error with optional `type`, `code`, `param`, and `headers`:

```yaml
- id: server-error
  times: 1
  error:
    status: 500
    message: Injected server error.
    code: server_error
```

A `fault` cuts or pauses a stream after a number of content chunks. The count covers text and argument deltas, not lifecycle events. A fault needs a rule with `match: { stream: true }`, or the rule is rejected at startup or on `PUT`.

```yaml
- id: cut-stream
  match: { stream: true }
  reply:
    - type: text
      text: This answer is about to be cut off.
  fault:
    afterChunks: 2
    kind: disconnect

- id: stall-stream
  match: { stream: true }
  reply:
    - type: text
      text: This answer stalls after two chunks.
  fault:
    afterChunks: 2
    kind: stall
    stallMs: 30000
```

### Timing

Set `timing.ttftMs` and `timing.chunkDelayMs` globally under `ai.timing`, or per rule with a `timing` object. Both default to zero, so replies are instant. `ttftMs` is the wait before the first byte of any reply, streamed or not, and `chunkDelayMs` is the gap between the frames of a stream. Delays are abortable: a client close or reset cancels pending timers.

`chunkDelayMs` also accepts a list, used in frame order and repeating the last entry, which gives a reply an uneven rhythm. Streamed structured output is split between JSON structural characters, never inside a string, so partial values parse as they arrive.

### Variants

Give a rule `variants` instead of `reply`, and set `ai.random.seed`, to vary the answer per call. A variant can carry `error` instead of `reply`, so a test meets a 429 on some calls and a normal reply on others; SDK retries spend the next variant. A variant may also override `finish`, `timing`, and `fault`, taking the rule-level values as defaults, so one rule can send the same content truncated, paced differently, or cut mid-stream.

The seed shuffles the variants per rule and calls walk that order in a cycle, so every variant appears once before any repeat. The same seed and call order always produce the same sequence; a different seed changes the order. Each rule counts its own matches, so requests answered by other rules do not shift its order.

## Control Endpoints

Read and edit the live state without restarting. All control routes are same-origin only, reads included. curl and tests without an `Origin` header work; a browser page served from another origin gets 403. Data routes accept SDK and server calls, which send no `Origin`, and browser pages served on this machine (`localhost`, `*.localhost`, `127.0.0.1`, `[::1]`); a page on any other website gets 403. The AI service also checks the request's own host, so a website whose name is rebound to this machine cannot read it: it answers only on loopback names, IP addresses, and the host of its base URL, and any other name gets 403. To allow another name, such as a Docker service name, start with `--base-url http://<host>:<port>`. When embedded through `createEmulateHandler`, set `publicUrl` to the public origin.

### Calls

```bash
curl -s http://localhost:4014/_ai/calls | jq
```

Returns a bare JSON array of recorded generation calls, oldest first. Each record includes `seq`, `time`, `format`, `path`, `model`, `stream`, normalized `messages`, declared `tools`, `toolChoice`, `previousResponseId`, `references` with resolved state, `store`, `matched`, a reply summary, `status`, `fault`, `delivery`, and `warnings`. `matched` is `{ "id": "<rule id>", "remaining": <budget left or null>, "rule": <the rule as it was when it answered> }` for a rule, `{ "default": "<kind>" }` when a default answered, and `null` when strict mode rejected the request.

Keys, auth headers, and file bytes never appear. The last 500 calls are kept. Stored responses are capped at the most recent 1000; older ones are evicted.

```bash
curl -X DELETE http://localhost:4014/_ai/calls
```

Returns `{ "deleted": <count> }`.

### Rules

```bash
curl -s http://localhost:4014/_ai/rules | jq
```

Returns `{ "rules": [...], "strict": <bool>, "timing": {...}, "random": { "seed": <number> }, "models": [...] }`. Each rule carries its remaining budget as `remaining`; `null` means unlimited. The shape is what `PUT` accepts.

Replace the whole rule set with a `rules` document:

```bash
curl -X PUT http://localhost:4014/_ai/rules \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {
        "id": "hello",
        "match": { "textContains": "Hi" },
        "reply": [{ "type": "text", "text": "Hello from emulate." }]
      }
    ]
  }'
```

`PUT` accepts the config fields of the seed `ai` block (`rules`, plus optional `strict`, `timing`, `random`, and `models`); `port` and `baseUrl` are ignored. It returns the same shape as GET and ignores `remaining` fields, so a GET then PUT keeps `rules`, `strict`, `timing`, `random`, and `models`. A body with only `rules` resets the other fields to their defaults. Every replacement restores each rule's full `times` budget. An invalid replacement returns 400 with the failing path and leaves the previous rules active. Runtime replacements are ephemeral: reset restores the seeded rules.

### Reset

```bash
curl -X POST http://localhost:4014/_ai/reset
```

Returns `{ "reset": true }`. It restores seeded rules and budgets, clears the call record and stored responses, and cancels active streams. Programmatic `reset()` behaves the same way.

### Inspector

Open `http://localhost:4014/` for read-only Calls and Rules tabs. The inspector is same-origin only, like the control routes.

## Recipes

### Two-step tool loop

Install rules that call a tool when it is declared without a result, then answer when a tool result arrives:

```bash
curl -X PUT http://localhost:4014/_ai/rules \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {
        "id": "weather-call",
        "match": { "textContains": "weather", "tool": "get_weather", "hasToolResult": false },
        "reply": [{ "type": "tool_call", "name": "get_weather", "arguments": { "city": "Paris" } }]
      },
      {
        "id": "weather-result",
        "match": { "hasToolResult": true },
        "reply": [{ "type": "text", "text": "The temperature in Paris is 20 C." }]
      }
    ]
  }'
```

Drive it with the AI SDK. Responses mode stores the first turn, and the emulator resolves the second step before matching either way: `@ai-sdk/openai` 3.x sends `item_reference` items for the prior assistant output and tool calls, while 4.x sends a pure tool-call step's history inline and uses item references only for assistant text.

```typescript
import { createOpenAI } from "@ai-sdk/openai";
import { generateText, jsonSchema, stepCountIs, tool } from "ai";

const openai = createOpenAI({
  baseURL: "http://localhost:4014/v1",
  apiKey: "test",
});

const result = await generateText({
  model: openai("gpt-x"),
  prompt: "What is the weather in Paris?",
  tools: {
    get_weather: tool({
      description: "Get the current weather for a city.",
      inputSchema: jsonSchema({
        type: "object",
        properties: { city: { type: "string" } },
        required: ["city"],
      }),
      execute: async ({ city }) => ({ city, temperatureC: 20 }),
    }),
  },
  stopWhen: stepCountIs(2),
});

console.log(result.text);
```

Use `openai.chat('gpt-x')` for Chat mode. The AI SDK then sends the earlier tool call and result inline, and the same second rule answers.

### Retry once after a 429

Put a one-use error rule before the success rule. The official SDK retries `429` by default and honors `retry-after`.

```bash
curl -X PUT http://localhost:4014/_ai/rules \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {
        "id": "rate-limit-once",
        "match": { "textContains": "retry" },
        "times": 1,
        "error": {
          "status": 429,
          "message": "Injected rate limit.",
          "headers": { "retry-after": "1" }
        }
      },
      {
        "id": "success",
        "match": { "textContains": "retry" },
        "reply": [{ "type": "text", "text": "Recovered after the retry." }]
      }
    ]
  }'
```

```typescript
const openai = new OpenAI({
  baseURL: "http://localhost:4014/v1",
  apiKey: "test",
  maxRetries: 2,
});

const result = await openai.chat.completions.create({
  model: "gpt-x",
  messages: [{ role: "user", content: "Please retry this." }],
});
```

Then `GET /_ai/calls` shows two attempts: the injected 429 and the successful retry. The error rule's budget is spent.

### Structured output

With no rules, ask for a schema and the default returns deterministic, schema-valid data. The same schema returns the same object on every run.

```typescript
import { generateObject } from "ai";
import { z } from "zod";

const { object } = await generateObject({
  model: openai("gpt-x"),
  schema: z.object({
    name: z.string(),
    minutes: z.number(),
  }),
  prompt: "Plan a short workout.",
});
```

To script a specific object, add an `object` reply:

```yaml
- id: workout
  match: { textContains: workout }
  reply:
    - type: object
      value: { name: "Squats", minutes: 15 }
```

### Reasoning

Reasoning appears as a reasoning summary in Responses replies and as a signed `thinking` block, before the text or tool call, in Messages replies. Chat Completions replies carry no reasoning text, because the OpenAI API has no field for it; usage reports `reasoning_tokens`.

```yaml
- id: think-first
  match: { textContains: explain }
  reply:
    - type: reasoning
      text: The user wants a short explanation.
    - type: text
      text: Here is the explanation.
```

### Streaming failures and stalls

Use `stream: true` in the matcher and add a fault. A disconnect ends the client stream early; a stall pauses it for `stallMs`, so an app timeout can be tested in seconds. The call record separates `fault` (`none`, `disconnect`, or `stall`) from `delivery` (`completed`, `client_aborted`, or `error`), so a client timeout during a stall records both.

```yaml
- id: slow
  match: { stream: true }
  reply:
    - type: text
      text: Partial answer that stalls.
  timing:
    ttftMs: 200
    chunkDelayMs: 50
  fault:
    afterChunks: 2
    kind: stall
    stallMs: 30000
```

### Strict mode

Set `ai.strict: true` to fail unmatched requests with a native 400. The message names the request's model and tools and includes the missing rule as YAML for a seed file and as a JSON body for `PUT /_ai/rules`. The JSON body keeps strict mode on, but `PUT /_ai/rules` replaces the whole configuration. Read the current rules with `GET /_ai/rules`, add the missing rule to them, send the result back, and retry. Replace the placeholder reply text first: it becomes the live reply if you send it unchanged.

```yaml
ai:
  strict: true
  rules: []
```

## Limitations

### Refusals and the AI SDK

A refusal rule produces OpenAI's native refusal shape only when a rule asks for one. The AI SDK cannot parse it: `@ai-sdk/openai` 3.x and 4.x reject a native Responses refusal part in non-streaming mode with a parse error and drop it when streaming, and Chat parsing omits `refusal`. This matches the real API's client behavior, so it is not hidden.

Test native refusal handling with the official `openai` SDK. For app behavior through the AI SDK, script the same user-visible content as `text` instead.

### Attachments

Attachments are input only. The emulator never reads their contents to produce an answer; rules decide the reply. Inline bytes are hashed, measured, and dropped, so the call record keeps name, media type, size, and sha256 only. URLs and file ids are recorded as references with no size or hash.

- Responses accepts `input_file` with inline data, a URL, or a file id, plus `input_image`.
- Chat accepts `file` parts with inline data or a file id, and `image_url`. Chat files must be PDFs and Chat does not accept file URLs.
- Malformed inline data returns a native 400.

The AI SDK validates attachments before sending. `@ai-sdk/openai` sends image bytes and PDFs; `text/plain` and other media types throw client-side unless `passThroughUnsupportedFiles` is set. A Markdown file therefore fails in the app before any request reaches the emulator.

### Unsupported features

On the OpenAI routes, result-changing features outside this version return a native 400 naming the feature:

- hosted tools
- custom tools
- allowed tool choice
- background mode
- the Conversations API
- multiple candidates (`n` above 1)
- audio input
- audio output
- legacy functions

On the Messages route, tools carry `input_schema`, except Anthropic-defined client tools (bash, text editor, computer use, memory), which are accepted by name without one. Server-side tools (web search, web fetch, code execution, tool search, MCP toolset) return a 400. A base64 image source must be `image/jpeg`, `image/png`, `image/gif`, or `image/webp`, and a base64 document source must be `application/pdf`. Messages errors use Anthropic's envelope, and a validation error starts with the failing field, as in `max_tokens: Expected a number.` Unsupported paths under `/v1/messages`, such as `count_tokens`, and any request with an `anthropic-version` header get a `not_found_error` in the same envelope.

## Privacy

The call record holds prompt text and tool arguments by design. It never holds API keys, auth headers, query credentials, or file bytes. Do not send real credentials; no key is needed.

## Verify

Read the call record after a test to assert what the app sent:

```bash
curl -s http://localhost:4014/_ai/calls | jq 'sort_by(.seq) | last | {format, model, matched, status, delivery}'
```

Open `http://localhost:4014/` to browse calls and rule budgets in the inspector.

## Current Limits

Paths with no route return the native 404 naming the supported paths: Gemini, embeddings, image generation, file uploads, input item listing, token counting, and response cancellation.

Accepted and ignored, with no effect on replies: OpenRouter `reasoning` fields and unknown optional fields. Reply text is sent as written with no templating.

## Custom emulators alongside built-ins

Use `npx emulate init --custom inventory` to scaffold a third-party API emulator and test. Register it in `emulate.config.ts` with `defineConfig` from `emulate`, alongside built-in entries such as `{ emulator: "ai" }`. Run `npx emulate start --watch` to reload imports and inspect custom state at the printed `/_emulate` URL. Successful reloads reset the run to seed. Existing flat seed configs still work; `--config` selects an explicit file. For authoring and testing third-party API emulators, see https://emulate.dev/docs/custom-emulators.

