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
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:
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
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.
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.
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.
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:
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:
- 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.
- 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
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.
curl -X DELETE http://localhost:4014/_ai/calls
Returns { "deleted": <count> }.
Rules
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:
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
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:
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.
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.
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." }]
}
]
}'
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.
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:
- 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.
- 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.
- 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.
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_filewith inline data, a URL, or a file id, plusinput_image. - Chat accepts
fileparts with inline data or a file id, andimage_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 (
nabove 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:
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.