|
| 1 | +--- |
| 2 | +title: "MockChatGenerator" |
| 3 | +id: mockchatgenerator |
| 4 | +slug: "/mockchatgenerator" |
| 5 | +description: "A Chat Generator that returns predefined responses without calling any API, for tests and quick prototypes." |
| 6 | +--- |
| 7 | + |
| 8 | +# MockChatGenerator |
| 9 | + |
| 10 | +A Chat Generator that returns predefined responses without calling any API, for tests and quick prototypes. |
| 11 | + |
| 12 | +<div className="key-value-table"> |
| 13 | + |
| 14 | +| | | |
| 15 | +| --- | --- | |
| 16 | +| **Most common position in a pipeline** | In place of a real Chat Generator, in tests and prototypes | |
| 17 | +| **Mandatory init variables** | None | |
| 18 | +| **Mandatory run variables** | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects | |
| 19 | +| **Output variables** | `replies`: A list of generated `ChatMessage` objects | |
| 20 | +| **API reference** | [Generators](/reference/generators-api) | |
| 21 | +| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/chat/mock.py | |
| 22 | +| **Package name** | `haystack-ai` | |
| 23 | + |
| 24 | +</div> |
| 25 | + |
| 26 | +## Overview |
| 27 | + |
| 28 | +`MockChatGenerator` is a deterministic, zero-cost drop-in replacement for real Chat Generators such as `OpenAIChatGenerator`. It implements `run`, `run_async`, streaming callbacks, and serialization but never contacts an external service, which makes it ideal for unit tests, smoke tests, and quick prototypes. |
| 29 | + |
| 30 | +The response is selected based on how the component is configured: |
| 31 | + |
| 32 | +- **Fixed response**: Pass a single string or `ChatMessage` via `responses`. The same reply is returned on every call. A `ChatMessage` passed as a response must have the `assistant` role. |
| 33 | +- **Cycling responses**: Pass a list of strings and/or `ChatMessage` objects via `responses`. Each call returns the next item, wrapping around to the start once the list is exhausted. This is useful to drive multi-step flows such as Agents, where the first call returns a tool call and a later call returns the final answer. |
| 34 | +- **Dynamic response**: Pass a `response_fn` callable that receives the input messages and returns the reply as a string or an assistant `ChatMessage`. Use this when the reply should depend on the input. To support serialization, pass a named function. |
| 35 | +- **Echo (default)**: With no configuration, the component echoes back the text of the last message that has text content, so it is usable out of the box. |
| 36 | + |
| 37 | +`responses` and `response_fn` are mutually exclusive. |
| 38 | + |
| 39 | +Further optional parameters: |
| 40 | + |
| 41 | +- `model`: The model name reported in the response metadata. Defaults to `"mock-model"`. |
| 42 | +- `meta`: Additional metadata merged into the `meta` of every returned `ChatMessage`. A per-response `ChatMessage`'s own metadata takes precedence. |
| 43 | +- `streaming_callback`: An optional callback invoked with `StreamingChunk` objects reconstructed from the predefined response. It lets the mock exercise streaming code paths without a real model. |
| 44 | + |
| 45 | +## Usage |
| 46 | + |
| 47 | +### On its own |
| 48 | + |
| 49 | +```python |
| 50 | +from haystack.components.generators.chat import MockChatGenerator |
| 51 | +from haystack.dataclasses import ChatMessage |
| 52 | + |
| 53 | +# Fixed response |
| 54 | +generator = MockChatGenerator(responses="Hello, this is a mock response.") |
| 55 | +result = generator.run([ChatMessage.from_user("Hi!")]) |
| 56 | +print(result["replies"][0].text) # "Hello, this is a mock response." |
| 57 | + |
| 58 | +# Echo mode (default): returns the last message with text content |
| 59 | +generator = MockChatGenerator() |
| 60 | +result = generator.run([ChatMessage.from_user("Repeat after me")]) |
| 61 | +print(result["replies"][0].text) # "Repeat after me" |
| 62 | +``` |
| 63 | + |
| 64 | +### Driving an Agent |
| 65 | + |
| 66 | +Pass `ChatMessage` objects (rather than plain strings) to return tool calls or reasoning content. With cycling responses, you can script a full agent loop without a real model: |
| 67 | + |
| 68 | +```python |
| 69 | +from haystack.components.agents import Agent |
| 70 | +from haystack.components.generators.chat import MockChatGenerator |
| 71 | +from haystack.dataclasses import ChatMessage, ToolCall |
| 72 | +from haystack.tools import tool |
| 73 | + |
| 74 | + |
| 75 | +@tool |
| 76 | +def search(query: str) -> str: |
| 77 | + """Search for information.""" |
| 78 | + return f"Results for: {query}" |
| 79 | + |
| 80 | + |
| 81 | +generator = MockChatGenerator( |
| 82 | + responses=[ |
| 83 | + ChatMessage.from_assistant( |
| 84 | + tool_calls=[ToolCall(tool_name="search", arguments={"query": "Haystack"})], |
| 85 | + ), |
| 86 | + "Here is the final answer.", |
| 87 | + ], |
| 88 | +) |
| 89 | + |
| 90 | +agent = Agent(chat_generator=generator, tools=[search]) |
| 91 | +result = agent.run(messages=[ChatMessage.from_user("Tell me about Haystack")]) |
| 92 | +print(result["last_message"].text) # "Here is the final answer." |
| 93 | +``` |
| 94 | + |
| 95 | +### Input-dependent responses |
| 96 | + |
| 97 | +```python |
| 98 | +from haystack.components.generators.chat import MockChatGenerator |
| 99 | +from haystack.dataclasses import ChatMessage |
| 100 | + |
| 101 | + |
| 102 | +def shout_back(messages: list[ChatMessage]) -> str: |
| 103 | + return messages[-1].text.upper() |
| 104 | + |
| 105 | + |
| 106 | +generator = MockChatGenerator(response_fn=shout_back) |
| 107 | +result = generator.run([ChatMessage.from_user("hello")]) |
| 108 | +print(result["replies"][0].text) # "HELLO" |
| 109 | +``` |
0 commit comments