### Quick Start Docker Example

Source: https://github.com/copilotkit/aimock/blob/main/docs/record-replay/index.html

Run aimock with record mode enabled using Docker. This setup proxies, saves, and caches responses for unmatched requests.

```shell
docker run -d -p 4010:4010 \
  -v $(pwd)/fixtures:/fixtures \
  ghcr.io/copilotkit/aimock \
  -f /fixtures -h 0.0.0.0 \
  --record \
  --provider-openai https://api.openai.com \
  --provider-anthropic https://api.anthropic.com
```

--------------------------------

### Manual aimock Setup (Without Plugins)

Source: https://github.com/copilotkit/aimock/blob/main/docs/test-plugins/index.html

This example demonstrates the manual setup required for `LLMock` without using the test framework plugins. It includes starting the server, registering fixtures, and managing environment variables.

```typescript
import { LLMock } from "@copilotkit/aimock";

let mock: LLMock;

beforeAll(async () => {
  mock = new LLMock();
  mock.onMessage("hello", { content: "Hi!" });
  await mock.start();
  process.env.OPENAI_BASE_URL = `${mock.url}/v1`;
});

afterAll(async () => {
  await mock.stop();
  delete process.env.OPENAI_BASE_URL;
});
```

--------------------------------

### Install and Run Next.js Dev Server

Source: https://github.com/copilotkit/aimock/blob/main/examples/no-user-message-repro/README.md

Install dependencies and start the Next.js development server in the example directory.

```sh
pnpm install
pnpm dev
```

--------------------------------

### Quick Start CLI Example

Source: https://github.com/copilotkit/aimock/blob/main/docs/record-replay/index.html

Enable record mode to proxy, save, and cache responses on miss. This example configures upstream providers for OpenAI and Anthropic.

```shell
npx -p @copilotkit/aimock llmock -f ./fixtures \
  --record \
  --provider-openai https://api.openai.com 
  --provider-anthropic https://api.anthropic.com
```

--------------------------------

### Vertex AI Quick Start with aimock

Source: https://github.com/copilotkit/aimock/blob/main/docs/vertex-ai/index.html

A quick start example demonstrating how to initialize LLMock, set up a message handler, start the mock server, and make a fetch request to a Vertex AI endpoint.

```typescript
import { LLMock } from "@copilotkit/aimock";

const mock = new LLMock();
mock.onMessage("hello", { content: "Hi from Vertex AI!" });
await mock.start();

// Vertex AI SDK configuration
const res = await fetch(
  `${mock.url}/v1/projects/my-project/locations/us-central1/publishers/google/models/gemini-pro:generateContent`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      contents: [
        { role: "user", parts: [{ text: "hello" }] },
      ],
    }),
  },
);
```

--------------------------------

### LLMock Setup and Usage

Source: https://github.com/copilotkit/aimock/blob/main/skills/write-fixtures/SKILL.md

Demonstrates how to initialize LLMock, load fixtures, start the server, and manage test cleanup. It also shows the static factory shorthand for creating and starting a mock server.

```APIDOC
## LLMock Initialization and Lifecycle

### Description
This section details the basic setup and lifecycle management of the `LLMock` instance for end-to-end testing.

### Setup
```typescript
import { LLMock } from "@copilotkit/aimock";

// Setup — port: 0 picks a random available port
const mock = new LLMock({ port: 0 });
mock.loadFixtureDir("./fixtures");
await mock.start();
process.env.OPENAI_BASE_URL = `${mock.url}/v1`;
```

### Static Factory Shorthand
```typescript
const mock = await LLMock.create({ port: 0 }); // creates + starts in one call
```

### Per-Test Cleanup
```typescript
afterEach(() => mock.reset()); // clears fixtures AND journal
```

### Teardown
```typescript
afterAll(async () => await mock.stop());
```
```

--------------------------------

### Quick Start GitHub Action

Source: https://github.com/copilotkit/aimock/blob/main/docs/github-action/index.html

Start an aimock server in GitHub Actions with a single `uses:` step. This example sets up fixtures and then runs tests using the mock server's URL.

```yaml
- uses: CopilotKit/aimock@v1
  id: mock
  with:
    fixtures: ./test/fixtures

- run: pnpm test
  env:
    OPENAI_BASE_URL: ${{ steps.mock.outputs.url }}/v1
```

--------------------------------

### Start aimock Server in C#

Source: https://github.com/copilotkit/aimock/blob/main/docs/integrate-maf/index.html

Starts the aimock process as a server to mock LLM API calls. Ensure aimock is installed and fixtures are available.

```csharp
using Microsoft.Extensions.AI;
using OpenAI;
using Xunit;

public class AgentTests : IAsyncLifetime
{
    private Process? _aimock;

    public Task InitializeAsync()
    {
        _aimock = Process.Start(new ProcessStartInfo
        {
            FileName = "npx",
            Arguments = "@copilotkit/aimock --fixtures ./fixtures",
            RedirectStandardOutput = true,
        });
        return Task.Delay(1000); // wait for server startup
    }

    public Task DisposeAsync()
    {
        _aimock?.Kill();
        return Task.CompletedTask;
    }

    [Fact]
    public async Task ResearcherAgent_ReturnsFixtureResponse()
    {
        var openaiClient = new OpenAIClient(
            new ApiKeyCredential("test"),
            new OpenAIClientOptions
            {
                Endpoint = new Uri("http://localhost:4010/v1")
            }
        );

        var agent = openaiClient
            .GetChatClient("gpt-4o")
            .AsIChatClient();

        var response = await agent.GetResponseAsync(
            "Summarize recent AI breakthroughs"
        );

        Assert.Contains("AI", response.Text);
    }
}
```

--------------------------------

### Start aimock with Docker for JUnit 5 tests

Source: https://github.com/copilotkit/aimock/blob/main/docs/migrate-from-mokksy/index.html

Use this setup in your JUnit 5 tests to start the aimock Docker container before tests run and stop it afterwards. Ensure Docker is installed and running.

```kotlin
// JUnit 5 — start aimock before tests
    @BeforeAll
    fun setup() {
        ProcessBuilder("docker", "run", "-d", "--name", "aimock",
            "-p", "4010:4010", "-v", "./fixtures:/fixtures",
            "ghcr.io/copilotkit/aimock", "-f", "/fixtures", "-h", "0.0.0.0")
            .start().waitFor()
        // Wait for server to be ready — fail loudly if it never comes up
        var lastError: Exception? = null
        repeat(30) {
            try {
                java.net.URL("http://localhost:4010/health")
                    .readText()
                return
            } catch (e: Exception) {
                lastError = e
                Thread.sleep(200)
            }
        }
        throw IllegalStateException("aimock did not become healthy after 30 attempts", lastError)
    }
    
    @AfterAll
    fun teardown() {
        ProcessBuilder("docker", "stop", "aimock").start().waitFor()
        ProcessBuilder("docker", "rm", "aimock").start().waitFor()
    }
    
    // Point OpenAI Java SDK at aimock
    val client = OpenAIClient.builder()
        .baseUrl("http://localhost:4010/v1")
        .apiKey("mock")
        .build()
```

--------------------------------

### CLI Quick Start for aimock

Source: https://github.com/copilotkit/aimock/blob/main/docs/migrate-from-msw/index.html

Launch aimock using npx for a quick local setup. Specify the port and fixture file path.

```bash
npx -p @copilotkit/aimock llmock -p 4010 -f ./fixtures
```

--------------------------------

### Quick Start: Initialize and Start aimock

Source: https://github.com/copilotkit/aimock/blob/main/docs/ollama/index.html

Initialize LLMock and start the mock server. This is the first step to using aimock for testing Ollama SDK interactions.

```typescript
import { LLMock } from "@copilotkit/aimock";

const mock = new LLMock();
mock.onMessage("hello", { content: "Hi from Ollama!" });
await mock.start();

// Point the Ollama SDK at aimock
const res = await fetch(`${mock.url}/api/chat`, {
  method: "POST",
  body: JSON.stringify({
    model: "llama3",
    messages: [{ role: "user", content: "hello" }],
    stream: false,
  }),
});
```

--------------------------------

### Recording Configuration Example

Source: https://github.com/copilotkit/aimock/blob/main/docs/aimock-cli/index.html

Example of the recording configuration within the aimock.json file, specifying providers and fixture paths for recording.

```json
{
  "llm": {
    "fixtures": "./fixtures",
    "record": {
      "providers": {
        "openai": "https://api.openai.com",
        "anthropic": "https://api.anthropic.com"
      },
      "fixturePath": "./fixtures/recorded",
      "recordFullModelVersion": false
    }
  }
}
```

--------------------------------

### Standalone Mode TypeScript Setup

Source: https://github.com/copilotkit/aimock/blob/main/docs/agui-mock/index.html

Initialize AGUIMock, register message and tool call fixtures, and start the mock server. The returned URL is where your frontend should send requests.

```typescript
import { AGUIMock } from "@copilotkit/aimock";

const agui = new AGUIMock();
agui.onMessage("hello", "Hi! How can I help?");
agui.onToolCall(/search/, "web_search", '{"q":"test"}', { result: "[]" });

const url = await agui.start();
// POST to url with RunAgentInput body
```

--------------------------------

### Quick Start with Cohere SDK and aimock

Source: https://github.com/copilotkit/aimock/blob/main/docs/cohere/index.html

Initialize LLMock, define a message response, start the mock server, and point the Cohere SDK to the mock URL.

```typescript
import { LLMock } from "@copilotkit/aimock";
    
    const mock = new LLMock();
    mock.onMessage("hello", { content: "Hi from Cohere!" });
    await mock.start();
    
    // Point the Cohere SDK at aimock
    const res = await fetch(`${mock.url}/v2/chat`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        model: "command-r-plus",
        messages: [{ role: "user", content: "hello" }],
      }),
    });
```

--------------------------------

### Install and Build Local aimock

Source: https://github.com/copilotkit/aimock/blob/main/examples/no-user-message-repro/README.md

Install dependencies and build the local aimock project from the repo root.

```sh
pnpm install
pnpm build
```

--------------------------------

### Start aimock Server and Run Agent

Source: https://github.com/copilotkit/aimock/blob/main/docs/integrate-pydanticai/index.html

Two terminal commands to start the aimock server with a fixture file and then run your PydanticAI agent script. This setup enables deterministic testing.

```shell
# Terminal 1 — start aimock
npx -p @copilotkit/aimock llmock --fixtures ./fixtures

# Terminal 2 — run the agent
python agent.py
```

--------------------------------

### Run aimock server with npx

Source: https://github.com/copilotkit/aimock/blob/main/docs/migrate-from-python-mocks/index.html

Starts the aimock server using npx, specifying the port and fixture directory. Ensure Node.js is installed.

```sh
# Run the mock server (requires Node.js, flag-driven llmock bin)
npx -p @copilotkit/aimock llmock -p 4010 -f ./fixtures
```

--------------------------------

### Quick Start: Configure Server-Level Chaos

Source: https://github.com/copilotkit/aimock/blob/main/docs/chaos-testing/index.html

Initialize LLMock, set a 50% drop rate for requests, start the mock server, and later clear the chaos configuration.

```typescript
import { LLMock } from "@copilotkit/aimock";

const mock = new LLMock();
mock.onMessage("hello", { content: "Hi!" });

// 50% of all requests will be dropped with a 500
mock.setChaos({ dropRate: 0.5 });

await mock.start();

// Later, remove chaos
mock.clearChaos();
```

--------------------------------

### Test Setup with MSW and aimock

Source: https://github.com/copilotkit/aimock/blob/main/docs/migrate-from-msw/index.html

Configure MSW for general REST APIs and aimock for AI APIs in your test setup. Ensure to start aimock and set the OPENAI_BASE_URL environment variable.

```typescript
// test setup
import { setupServer } from 'msw/node'
import { http, HttpResponse } from 'msw'
import { LLMock } from '@copilotkit/aimock'

// MSW for REST APIs
const mswServer = setupServer(
  http.get('/api/users', () => HttpResponse.json([...]))
)

// aimock for AI APIs
const aiMock = new LLMock({ port: 0 })
aiMock.onMessage("hello", { content: "Hi!" })

beforeAll(async () => {
  mswServer.listen()
  await aiMock.start()
  process.env.OPENAI_BASE_URL = aiMock.url + "/v1"
})
```

--------------------------------

### Install CopilotKit CLI

Source: https://github.com/copilotkit/aimock/blob/main/docs/index.html

Use this command to install the CopilotKit command-line interface. Ensure you have Node.js and npm installed.

```bash
npm install -g @copilotkit/cli
```

--------------------------------

### Start Aimock Server with Configuration

Source: https://github.com/copilotkit/aimock/blob/main/docs/index.html

Run the aimock server using a specified configuration file to mock multiple AI services.

```bash
$ npx @copilotkit/aimock --config aimock.json
```

--------------------------------

### aimock Pytest Configuration (conftest.py)

Source: https://github.com/copilotkit/aimock/blob/main/docs/integrate-adk/index.html

Example conftest.py file demonstrating the use of the aimock-pytest plugin. Ensure 'aimock-pytest' is installed.

```python
import pytest

# The aimock fixture is provided by aimock-pytest
# pip install aimock-pytest
```

--------------------------------

### Install aimock Package

Source: https://github.com/copilotkit/aimock/blob/main/README.md

Install the aimock package using npm. This command is the first step to setting up the mocking infrastructure for your AI application tests.

```bash
npm install @copilotkit/aimock
```

--------------------------------

### Install aimock Helm Chart

Source: https://github.com/copilotkit/aimock/blob/main/docs/docker/index.html

Install the aimock Helm chart to deploy to Kubernetes. Custom values can be provided during installation.

```shell
helm install aimock ./charts/aimock

# With custom values
helm install aimock ./charts/aimock \
  --set image.tag=1.4.0 \
  --set service.port=5555 \
  --set replicaCount=2
```

--------------------------------

### GitHub Action for aimock in CI

Source: https://github.com/copilotkit/aimock/blob/main/docs/integrate-adk/index.html

Example GitHub Actions workflow step to start aimock with specified fixtures. This allows running ADK tests in a CI environment without real API keys.

```yaml
steps:
  - uses: actions/checkout@v4
  - name: Start aimock
    uses: CopilotKit/aimock@v1
    with:
      fixtures: fixtures/examples/adk/gemini-agent.json

  - name: Run ADK tests
    run: pytest tests/
```

--------------------------------

### Initialize and Start LLMock

Source: https://github.com/copilotkit/aimock/blob/main/docs/fal-ai/index.html

This snippet shows how to initialize and start the LLMock for testing. It's essential to start the mock before running tests and stop it afterwards.

```typescript
import { LLMock } from "@copilotkit/aimock";
import { describe, it, expect, beforeAll, afterAll } from "vitest";

let mock: LLMock;

beforeAll(async () => {
  mock = new LLMock();
  await mock.start();
});

afterAll(async () => {
  await mock.stop();
});
```

--------------------------------

### E2E Test Setup with LLMock

Source: https://github.com/copilotkit/aimock/blob/main/skills/write-fixtures/SKILL.md

Set up LLMock for E2E tests by initializing it, loading fixtures from a directory, starting the server, and setting the base URL for API requests. Use `afterEach` to reset fixtures and journal, and `afterAll` to stop the server.

```typescript
import { LLMock } from "@copilotkit/aimock";

// Setup — port: 0 picks a random available port
const mock = new LLMock({ port: 0 });
mock.loadFixtureDir("./fixtures");
await mock.start();
process.env.OPENAI_BASE_URL = `${mock.url}/v1`;

// Per-test cleanup
afterEach(() => mock.reset()); // clears fixtures AND journal

// Teardown
afterAll(async () => await mock.stop());
```

--------------------------------

### Example Fixture Configuration

Source: https://github.com/copilotkit/aimock/blob/main/docs/index.html

A sample JSON configuration for aimock fixtures, defining request matching and response.

```json
{
  "match": {
    "userMessage": "Hello"
  },
  "response": {
    "content": "Hi there! How can I help?"
  },
  "opts": {
    "chunkSize": 10,
    "latency": 1000
  }
}
```

--------------------------------

### Install aimock-pytest

Source: https://github.com/copilotkit/aimock/blob/main/packages/aimock-pytest/README.md

Install the aimock-pytest package from PyPI or locally from a repository checkout.

```bash
pip install aimock-pytest
```

```bash
pip install ./packages/aimock-pytest
```

--------------------------------

### Start Aimock Server with Docker

Source: https://github.com/copilotkit/aimock/blob/main/docs/migrate-from-python-mocks/index.html

This fixture starts the Aimock server using Docker, mapping ports, mounting fixtures, and waiting for the health endpoint to become available. It also sets environment variables for OpenAI API base URL and key.

```python
import pytest
import subprocess, time, os

@pytest.fixture(scope="session")
def aimock_server():
    # Start aimock via Docker
    proc = subprocess.Popen([
        "docker", "run", "--rm",
        "-p", "4010:4010",
        "-v", f"{os.getcwd()}/fixtures:/fixtures",
        "ghcr.io/copilotkit/aimock:latest",
        "-f", "/fixtures", "-h", "0.0.0.0"
    ])
    # Wait for health endpoint — fail loudly if aimock never comes up
    import requests
    for _ in range(30):
        if proc.poll() is not None:
            raise RuntimeError(f"aimock exited early with code {proc.returncode}")
        try:
            if requests.get("http://localhost:4010/health").ok:
                break
        except requests.ConnectionError:
            pass
        time.sleep(0.2)
    else:
        raise RuntimeError("aimock did not become healthy after 30 attempts")

    # Save originals so we don't clobber real credentials in the test process
    prev_base = os.environ.get("OPENAI_BASE_URL")
    prev_key = os.environ.get("OPENAI_API_KEY")
    os.environ["OPENAI_BASE_URL"] = "http://localhost:4010/v1"
    os.environ["OPENAI_API_KEY"] = "mock-key"

    try:
        yield "http://localhost:4010"
    finally:
        proc.terminate()
        try:
            proc.wait(timeout=10)
        except subprocess.TimeoutExpired:
            proc.kill()
            proc.wait(timeout=5)
        # Restore originals (or remove if there were none)
        for name, val in (("OPENAI_BASE_URL", prev_base), ("OPENAI_API_KEY", prev_key)):
            if val is None:
                os.environ.pop(name, None)
            else:
                os.environ[name] = val
```

--------------------------------

### Run aimock LLM Mock (CLI)

Source: https://github.com/copilotkit/aimock/blob/main/docs/index.html

Start the aimock LLM mock from the command line, specifying a fixtures file.

```bash
npx -p @copilotkit/aimock llmock -f ./fixtures
```

--------------------------------

### Start aimock with LlamaIndex fixtures

Source: https://github.com/copilotkit/aimock/blob/main/docs/integrate-llamaindex/index.html

Run the aimock server with a command that specifies the directory containing your LlamaIndex fixtures.

```shell
npx -p @copilotkit/aimock llmock --fixtures ./fixtures/llamaindex
```

--------------------------------

### Start aimock Shell

Source: https://github.com/copilotkit/aimock/blob/main/docs/integrate-adk/index.html

Command to start the aimock shell with a Gemini-format fixture. This allows testing ADK agents against mock Gemini API responses.

```bash
npx -p @copilotkit/aimock llmock --fixtures fixtures/examples/adk/gemini-agent.json
```

--------------------------------

### mock-llm Configuration (YAML)

Source: https://github.com/copilotkit/aimock/blob/main/docs/migrate-from-mock-llm/index.html

Example of a mock-llm configuration file in YAML format.

```yaml
port: 8080
completions:
  - model: "gpt-4"
    response:
      content: "Hello from mock-llm"
      role: "assistant"
    usage:
      prompt_tokens: 10
      completion_tokens: 5
      total_tokens: 15
```

--------------------------------

### Install aimock .NET Package

Source: https://github.com/copilotkit/aimock/blob/main/docs/integrate-maf/index.html

Add the Microsoft.Extensions.AI package to your C# project for aimock integration.

```shell
dotnet add package Microsoft.Extensions.AI
```

--------------------------------

### Mounted Mode Example

Source: https://github.com/copilotkit/aimock/blob/main/docs/vector-mock/index.html

Illustrates mounting VectorMock onto an LLMock server.

```APIDOC
## Mounted Mode Example

### Description
This example demonstrates how to mount VectorMock onto an LLMock server, allowing it to share a port with other services.

### Method
TypeScript

### Endpoint
N/A (Mounted)

### Code
```typescript
import { LLMock, VectorMock } from "@copilotkit/aimock";

const llm = new LLMock({ port: 5555 });
const vector = new VectorMock();

vector.addCollection("embeddings", { dimension: 768 });
vector.onQuery("embeddings", [{ id: "v1", score: 0.9 }]);

llm.mount("/vector", vector);
await llm.start();
// Vector API at http://127.0.0.1:5555/vector
```
```

--------------------------------

### createMockSuite()

Source: https://github.com/copilotkit/aimock/blob/main/skills/write-fixtures/SKILL.md

Provides a unified lifecycle for LLMock and mounted services, simplifying setup and teardown for testing.

```APIDOC
## createMockSuite()

### Description
Unified lifecycle for LLMock + mounted services.

### Method
```typescript
createMockSuite(options: MockSuiteOptions)
```

### Parameters
#### Request Body
- **port** (number) - The port to run the mock server on. `0` for a random port.
- **fixtures** (string) - Path to the fixtures directory.
- **services** (object) - An object mapping path prefixes to mock services.
  - **"/mcp"** (object) - Mock MCP service.
  - **"/a2a"** (object) - Mock A2A service.

### Example
```typescript
import { createMockSuite } from "@copilotkit/aimock";

const suite = createMockSuite({
  port: 0,
  fixtures: "./fixtures",
  services: { "/mcp": mcpMock, "/a2a": a2aMock },
});

await suite.start();
// suite.llm — the LLMock instance
// suite.url — base URL

afterEach(() => suite.reset()); // resets everything
afterAll(() => suite.stop());
```
```

--------------------------------

### Multi-turn HITL Fixture Example

Source: https://github.com/copilotkit/aimock/blob/main/skills/write-fixtures/SKILL.md

Demonstrates a 2-step Human-in-the-Loop (HITL) interaction using turnIndex for matching.

```jsonc
// 2-step HITL with turnIndex
{"match": {"userMessage": "trip to mars", "turnIndex": 0}, "response": {"toolCalls": [{"id": "call_001", "name": "generate_steps", "arguments": "{}"}]}}
{"match": {"userMessage": "trip to mars", "turnIndex": 1}, "response": {"content": "Great choices! Proceeding."}}
```

--------------------------------

### Tool Call Streaming Example

Source: https://github.com/copilotkit/aimock/blob/main/docs/gemini-interactions/index.html

This example shows the sequence of Server-Sent Events (SSE) for a tool call interaction, including start, content, delta, stop, and completion events.

```text
data: {"event_type":"interaction.start","interaction":{"id":"int_def456","status":"in_progress"},"event_id":"evt_1"}

data: {"event_type":"content.start","index":0,"content":{"type":"function_call"},"event_id":"evt_2"}

data: {"event_type":"content.delta","index":0,"delta":{"type":"function_call","id":"tc_abc123","name":"get_weather","arguments":{"city":"NYC"}},"event_id":"evt_3"}

data: {"event_type":"content.stop","index":0,"event_id":"evt_4"}

data: {"event_type":"interaction.complete","interaction":{"id":"int_def456","status":"requires_action","usage":{"total_input_tokens":8,"total_output_tokens":12,"total_tokens":20}},"event_id":"evt_5"}
```

--------------------------------

### Playwright Test Setup for Snapshot Recording

Source: https://github.com/copilotkit/aimock/blob/main/docs/examples/index.html

Example Playwright test setup using `test.beforeEach` to route LLM traffic through aimock with a test ID header for organizing recorded fixtures.

```typescript
import { test } from "@playwright/test";

test.beforeEach(async ({ page }, testInfo) => {
  // Route all LLM traffic through aimock with a test ID header
  await page.setExtraHTTPHeaders({
    "X-Test-Id": testInfo.title,
  });
});
```

--------------------------------

### GitHub Action with Full Suite and Config

Source: https://github.com/copilotkit/aimock/blob/main/docs/github-action/index.html

This example shows how to use a specific configuration file for aimock and pass additional arguments like `--strict`. It also includes checking out the code and running tests.

```yaml
steps:
  - uses: actions/checkout@v4
  - uses: CopilotKit/aimock@v1
    id: mock
    with:
      config: ./aimock.json
      args: --strict
  - run: npm test
    env:
      OPENAI_BASE_URL: ${{ steps.mock.outputs.url }}/v1
```

--------------------------------

### Start aimock with configuration file

Source: https://github.com/copilotkit/aimock/blob/main/docs/integrate-llamaindex/index.html

Launch aimock using a configuration file that specifies both LLM and vector database settings, enabling comprehensive RAG pipeline mocking.

```shell
npx @copilotkit/aimock --config aimock.json
```

--------------------------------

### Quick Start: Mocking a Chat Completion

Source: https://github.com/copilotkit/aimock/blob/main/packages/aimock-pytest/README.md

Demonstrates how to use the `aimock` fixture to mock a message and then send a request to the mock server using the requests library.

```python
def test_hello(aimock):
    import requests

    # Set up a fixture
    aimock.on_message("hello", {"content": "Hi there!"})

    # Point your SDK at aimock
    r = requests.post(
        f"{aimock.base_url}/v1/chat/completions",
        json={
            "model": "gpt-4",
            "messages": [{"role": "user", "content": "hello"}],
        },
    )
    assert r.json()["choices"][0]["message"]["content"] == "Hi there!"
```

--------------------------------

### Static Factory Shorthand for LLMock

Source: https://github.com/copilotkit/aimock/blob/main/skills/write-fixtures/SKILL.md

Use the static `LLMock.create()` method as a shorthand to create and start the mock server in a single call. This simplifies the setup process.

```typescript
const mock = await LLMock.create({ port: 0 }); // creates + starts in one call
```

--------------------------------

### Run Aimock Mock Server with Config File

Source: https://github.com/copilotkit/aimock/blob/main/docs/migrate-from-piyook/index.html

Starts the aimock mock server using a configuration file, specifying the config path and port.

```shell
npx @copilotkit/aimock --config aimock.json --port 4010
```

--------------------------------

### Basic GitHub Action with Fixtures

Source: https://github.com/copilotkit/aimock/blob/main/docs/github-action/index.html

A basic GitHub Actions workflow demonstrating how to check out code, start an aimock server with specified fixtures, and then run tests using the mock server's URL.

```yaml
steps:
  - uses: actions/checkout@v4
  - uses: CopilotKit/aimock@v1
    id: mock
    with:
      fixtures: ./fixtures
  - run: npm test
    env:
      OPENAI_BASE_URL: ${{ steps.mock.outputs.url }}/v1
```

--------------------------------

### CLI: Full Suite from Config File

Source: https://github.com/copilotkit/aimock/blob/main/README.md

Execute aimock using a configuration file for comprehensive setup. This enables advanced features like the `convert` subcommand.

```bash
# Full suite from config
npx @copilotkit/aimock --config aimock.json
```

--------------------------------

### CLI: Basic LLM Mocking

Source: https://github.com/copilotkit/aimock/blob/main/README.md

Run this command to start an LLM mock server using local fixtures. Useful for local development and testing.

```bash
# LLM mocking only
npx -p @copilotkit/aimock llmock -p 4010 -f ./fixtures
```

--------------------------------

### Run aimock server with flags

Source: https://github.com/copilotkit/aimock/blob/main/docs/migrate-from-vidaimock/index.html

Installs and runs the aimock server using the llmock binary with specified port and fixtures directory. Point your application to the mock server by setting environment variables.

```shell
npx -p @copilotkit/aimock llmock -p 4010 -f ./fixtures

export OPENAI_BASE_URL=http://localhost:4010/v1
export OPENAI_API_KEY=mock-key
```

--------------------------------

### Run aimock LLM Mock (Docker)

Source: https://github.com/copilotkit/aimock/blob/main/docs/index.html

Run aimock using Docker, mounting a local fixtures directory and exposing the default port.

```bash
docker run -v $(pwd)/fixtures:/fixtures -p 4010:4010 ghcr.io/copilotkit/aimock -h 0.0.0.0 -f /fixtures
```

--------------------------------

### Install aimock-pytest plugin

Source: https://github.com/copilotkit/aimock/blob/main/docs/integrate-crewai/index.html

Install the `aimock-pytest` package to automatically manage the aimock server for your tests.

```bash
pip install aimock-pytest
```

--------------------------------

### aimock JSON fixture example

Source: https://github.com/copilotkit/aimock/blob/main/docs/migrate-from-vidaimock/index.html

Example of a declarative JSON fixture for aimock, specifying a match condition and a response.

```json
{
  "match": { "userMessage": "hello" },
  "response": { "content": "Hello from aimock" }
}
```

--------------------------------

### VidaiMock Tera template example

Source: https://github.com/copilotkit/aimock/blob/main/docs/migrate-from-vidaimock/index.html

Example of a dynamic response template using VidaiMock's Tera syntax.

```html
{% verbatim %}{
  "model": "{{ model }}",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Hello from VidaiMock"
    }
  }]
}{% endverbatim %}
```

--------------------------------

### Example Prometheus Metrics Output

Source: https://github.com/copilotkit/aimock/blob/main/docs/metrics/index.html

This is an example of the output format from the /metrics endpoint, showing counters, histograms, and gauges.

```text
# TYPE aimock_requests_total counter
aimock_requests_total{method="POST",path="/v1/chat/completions",status="200"} 42
aimock_requests_total{method="POST",path="/v1/messages",status="200"} 15

# TYPE aimock_request_duration_seconds histogram
aimock_request_duration_seconds_bucket{method="POST",path="/v1/chat/completions",le="0.005"} 0
aimock_request_duration_seconds_bucket{method="POST",path="/v1/chat/completions",le="0.01"} 5
aimock_request_duration_seconds_bucket{method="POST",path="/v1/chat/completions",le="0.025"} 20
aimock_request_duration_seconds_bucket{method="POST",path="/v1/chat/completions",le="0.05"} 35
aimock_request_duration_seconds_bucket{method="POST",path="/v1/chat/completions",le="0.1"} 40
aimock_request_duration_seconds_bucket{method="POST",path="/v1/chat/completions",le="0.25"} 42
aimock_request_duration_seconds_bucket{method="POST",path="/v1/chat/completions",le="0.5"} 42
aimock_request_duration_seconds_bucket{method="POST",path="/v1/chat/completions",le="1"} 42
aimock_request_duration_seconds_bucket{method="POST",path="/v1/chat/completions",le="2.5"} 42
aimock_request_duration_seconds_bucket{method="POST",path="/v1/chat/completions",le="5"} 42
aimock_request_duration_seconds_bucket{method="POST",path="/v1/chat/completions",le="10"} 42
aimock_request_duration_seconds_bucket{method="POST",path="/v1/chat/completions",le="+Inf"} 42
aimock_request_duration_seconds_sum{method="POST",path="/v1/chat/completions"} 1.234
aimock_request_duration_seconds_count{method="POST",path="/v1/chat/completions"} 42

# TYPE aimock_fixtures_loaded gauge
aimock_fixtures_loaded{} 12

# TYPE aimock_chaos_triggered_total counter
aimock_chaos_triggered_total{action="drop"} 3
aimock_chaos_triggered_total{action="malformed"} 1
```

--------------------------------

### Create and Manage Mock Suite

Source: https://github.com/copilotkit/aimock/blob/main/docs/mount/index.html

Initialize a unified mock server suite, mount various services, and manage their lifecycle with start, stop, and reset methods. Use `afterEach` and `afterAll` for test cleanup.

```typescript
import { createMockSuite } from "@copilotkit/aimock";

const suite = await createMockSuite({
  llm: { port: 0 },
  mcp: {},    // enables MCPMock, mounted at /mcp
  a2a: {},    // enables A2AMock, mounted at /a2a
  vector: {}, // enables VectorMock, mounted at /vector
});

await suite.start();
// suite.llm — the underlying LLMock instance
// suite.mcp — MCPMock instance (if configured)
// suite.a2a — A2AMock instance (if configured)
// suite.vector — VectorMock instance (if configured)

// In tests:
afterEach(() => suite.reset());     // resets LLM fixtures + all service state
afterAll(() => suite.stop());       // stops everything
```

--------------------------------

### Docker Quick Start for aimock

Source: https://github.com/copilotkit/aimock/blob/main/docs/migrate-from-msw/index.html

Run aimock in a Docker container for isolated testing. Mount your fixtures directory and expose the specified port.

```bash
docker run -d -p 4010:4010 \
  -v $(pwd)/fixtures:/fixtures \
  ghcr.io/copilotkit/aimock:latest \
  -p 4010 -f /fixtures -h 0.0.0.0
```

--------------------------------

### Development: Running Tests Locally (Installed Package)

Source: https://github.com/copilotkit/aimock/blob/main/packages/aimock-pytest/README.md

Instructions for installing the aimock-pytest package with test dependencies and running pytest from the package directory.

```bash
pip install ./packages/aimock-pytest[test]
cd packages/aimock-pytest
pytest tests/ -v
```

--------------------------------

### Run Aimock CLI

Source: https://github.com/copilotkit/aimock/blob/main/docs/migrate-from-mokksy/index.html

This command starts the Aimock mock LLM server using npx, exposing it on port 4010 and configuring it to use local fixtures.

```sh
    npx -p @copilotkit/aimock llmock -p 4010 -f ./fixtures
```

--------------------------------

### Bedrock Text Response JSON Example

Source: https://github.com/copilotkit/aimock/blob/main/docs/aws-bedrock/index.html

This is an example of a Bedrock Claude non-streaming response, which is identical to the Anthropic Messages API response format.

```json
{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "content": [{ "type": "text", "text": "Hello!" }],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": { "input_tokens": 10, "output_tokens": 5 }
}
```

--------------------------------

### Cohere v2 Chat Non-Streaming Response Example

Source: https://github.com/copilotkit/aimock/blob/main/docs/cohere/index.html

Example of a typical JSON response from the Cohere v2 Chat API when not using streaming.

```json
{
  "id": "msg_abc123",
  "finish_reason": "COMPLETE",
  "message": {
    "role": "assistant",
    "content": [{ "type": "text", "text": "Hi from Cohere!" }],
    "tool_calls": [],
    "tool_plan": "",
    "citations": []
  },
  "usage": {
    "billed_units": {
      "input_tokens": 0,
      "output_tokens": 0,
      "search_units": 0,
      "classifications": 0
    },
    "tokens": { "input_tokens": 0, "output_tokens": 0 }
  }
}
```

--------------------------------

### Programmatically Configure Groq SDK with aimock

Source: https://github.com/copilotkit/aimock/blob/main/docs/compatible-providers/index.html

Instantiate the Groq client with the baseURL pointing to aimock, including the /openai/v1 prefix. The API key can be any value.

```typescript
import Groq from "groq-sdk";

const client = new Groq({
  apiKey: "mock-key",
  baseURL: "http://localhost:5555/openai/v1",
});
```

--------------------------------

### GitHub Action Setup

Source: https://github.com/copilotkit/aimock/blob/main/README.md

Use this snippet to set up aimock as a GitHub Action in your CI/CD pipeline. It specifies the action to use and provides a fixture path.

```yaml
- uses: CopilotKit/aimock@v1
  with:
    fixtures: ./test/fixtures

- run: npm test
  env:
    OPENAI_BASE_URL: http://127.0.0.1:4010/v1
```

--------------------------------

### Minimal C# Setup with aimock

Source: https://github.com/copilotkit/aimock/blob/main/docs/integrate-maf/index.html

Configure a C# agent to use aimock for LLM interactions. This requires setting up the OpenAI client with aimock's local endpoint.

```csharp
using Microsoft.Extensions.AI;
using OpenAI;

// Start aimock first: npx -p @copilotkit/aimock llmock --fixtures ./fixtures
var openaiClient = new OpenAIClient(
    new ApiKeyCredential("test"),
    new OpenAIClientOptions
    {
        Endpoint = new Uri("http://localhost:4010/v1")
    }
);

var agent = openaiClient
    .GetChatClient("gpt-4o")
    .AsIChatClient();

var response = await agent.GetResponseAsync("What are the latest AI testing frameworks?");
Console.WriteLine(response.Text);
```

--------------------------------

### Text Response Fixture Example

Source: https://github.com/copilotkit/aimock/blob/main/docs/aws-bedrock/index.html

Example fixture configuration for handling text responses and tool calls. Fixtures are provider-agnostic and aimock translates requests internally.

```json
{
  "fixtures": [
    {
      "match": { "userMessage": "hello" },
      "response": { "content": "Hi there!" }
    },
    {
      "match": { "userMessage": "weather" },
      "response": {
        "toolCalls": [{
          "name": "get_weather",
          "arguments": { "city": "SF" }
        }]
      }
    }
  ]
}
```

--------------------------------

### Run CopilotKit Mock Server

Source: https://github.com/copilotkit/aimock/blob/main/docs/index.html

Starts the CopilotKit mock server. This is useful for local development and testing without connecting to actual AI services.

```bash
copilotkit mock
```

--------------------------------

### Mock LLM APIs with LLMock

Source: https://github.com/copilotkit/aimock/blob/main/docs/docs/index.html

Use LLMock to programmatically start a mock LLM API and define message responses. Ensure the mock is started before defining responses.

```typescript
import { LLMock } from "@copilotkit/aimock";

const mock = new LLMock();
await mock.start();

mock.onMessage("hello", { content: "Hi there!" });
```

--------------------------------

### Bedrock Request Body JSON Example

Source: https://github.com/copilotkit/aimock/blob/main/docs/aws-bedrock/index.html

This is an example of a Bedrock Claude request body using the Anthropic Messages format. The model ID is specified in the URL, not the body.

```json
{
  "anthropic_version": "bedrock-2023-05-31",
  "max_tokens": 512,
  "messages": [
    { "role": "user", "content": "Hello" }
  ],
  "system": "You are helpful"
}
```

--------------------------------

### Example Recorded Fixture with Metadata

Source: https://github.com/copilotkit/aimock/blob/main/docs/record-replay/index.html

A JSON example of a recorded fixture including a metadata block. The metadata contains hashes of the system prompt and tool definitions at recording time.

```json
{
  "match": { "userMessage": "hello", "model": "claude-opus-4" },
  "metadata": { "systemHash": "a7f3c291", "toolsHash": "e4b12d08" },
  "response": { "content": "Hi there!" }
}
```

--------------------------------

### GitHub Actions CI Setup

Source: https://github.com/copilotkit/aimock/blob/main/docs/migrate-from-openai-responses/index.html

Integrates Aimock into your CI pipeline using the CopilotKit/aimock GitHub Action. Specify fixture paths for mock data.

```yaml
name: Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Start aimock
        uses: CopilotKit/aimock@v1
        with:
          fixtures: ./fixtures

      - run: pip install -r requirements.txt
      - run: pytest
        env:
          OPENAI_BASE_URL: http://127.0.0.1:4010/v1
          OPENAI_API_KEY: mock-key
```

--------------------------------

### Start aimock and run CrewAI script

Source: https://github.com/copilotkit/aimock/blob/main/docs/integrate-crewai/index.html

Start the aimock server in one terminal and run your CrewAI Python script in another. Ensure the `OPENAI_BASE_URL` and `OPENAI_API_KEY` environment variables are set.

```bash
# Terminal 1 — start the mock server
npx -p @copilotkit/aimock llmock --fixtures ./fixtures

# Terminal 2 — run your CrewAI script
export OPENAI_BASE_URL=http://localhost:4010/v1
export OPENAI_API_KEY=test
python crew.py
```