> ## Documentation Index
> Fetch the complete documentation index at: https://docs.galtea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Simulate Conversation

> Run a full conversation simulation between your agent and a simulated user using the Galtea SDK.

> [!WARNING]
>
> You are reading the docs of Galtea 5.10. [Read this page in the latest version](https://docs.galtea.ai/sdk/api/simulator/simulate.md).

## Returns

It returns a result object from the [Conversation Simulator](https://docs.galtea.ai/v5.10/concepts/product/dataset/test-case/conversation-simulator.md#simulation-result-structure) containing the complete conversation history, status, and metadata. This is used to analyze how your agent performed in the test scenario.

## Agent Options

> [tab] Simple
>
> The quickest way to get started. Your function receives just the latest user message as a string.
>
> ```python theme={"system"}
> def my_agent(user_message: str) -> str:
>     # In a real scenario, call your model here
>     return f"Your model output to: {user_message}"
> ```

> [tab] Chat History
>
> Use this when your agent needs the full conversation context. Your function receives the message list in the OpenAI format (`{"role": "...", "content": "..."}`).
>
> ```python theme={"system"}
> def my_agent(messages: list[dict]) -> str:
>     # messages follows the standard chat format:
>     # [{"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}, ...]
>     user_message = messages[-1]["content"]
>     return f"Your model output to: {user_message}"
> ```

> [tab] Structured
>
> For full control over input and output — including optional usage tracking, cost tracking, retrieval context for RAG evaluations, and answering with files through `output_file_paths` (not in a simulated conversation).
>
> ```python theme={"system"}
> def my_agent(input_data: AgentInput) -> AgentResponse:
>     user_message = input_data.last_user_message_str()
>
>     # Access structured input fields from the first user message's metadata
>     # (e.g. when test case input is {"user_message": "hello", "chat_type": "support"})
>     first_msg = input_data.messages[0] if input_data.messages else None
>     chat_type = first_msg.metadata.get("chat_type") if first_msg and first_msg.metadata else None
>
>     # In a real scenario, call your model here
>     model_output = f"Your model output to: {user_message}"
>     # Return AgentResponse with optional usage/cost tracking
>     return AgentResponse(
>         content=model_output,
>         usage_info={"input_tokens": 100, "output_tokens": 50},
>     )
> ```

> [!NOTE]
>
> All three signatures work with `evaluations.run()`, `traces.generate()`, and `simulator.simulate()`. Both sync and async functions are supported. The SDK auto-detects which signature you're using from the type hint on the first parameter.
>
> Only the **Structured** signature receives the files a test case attaches, as `input_data.input_files`. The other two receive the text alone and fail the trace for a file-only test case. See [Reading attached files](https://docs.galtea.ai/v5.10/sdk/api/agent/input.md#reading-attached-files).
>
> Only the **Structured** signature can answer with files, through `AgentResponse.output_file_paths`. A response carrying files but no text is a real answer, not an empty one. `simulator.simulate()` is the exception: it raises a `ValueError` on a response carrying files, because a simulated conversation carries none yet. See [Output Files](https://docs.galtea.ai/v5.10/concepts/product/version/session/trace.md#trace-properties).
>
> For the full list of fields available on `AgentInput` (including structured input access via message metadata), see the [AgentInput reference](https://docs.galtea.ai/v5.10/sdk/api/agent/input.md).

## AgentInput Fields

With the **Structured** signature (`(input_data: AgentInput) -> AgentResponse`), your function receives an [`AgentInput`](https://docs.galtea.ai/v5.10/sdk/api/agent/input). That page lists every field and helper method, including `input_files` for [reading attached files](https://docs.galtea.ai/v5.10/sdk/api/agent/input.md#reading-attached-files).

## Example

```python theme={"system"}
# Define your agent function
def my_agent(user_message: str) -> str:
    return f"Response to: {user_message}"


simulation_result = galtea.simulator.simulate(
    session_id=behavior_session.id,
    agent=my_agent,
    max_turns=3,
)
```

## Parameters

**session\_id** `str` *required*

The session identifier for this simulation.

**agent** `AgentType` *required*

The agent function that generates responses. Supported signatures:

* **Simple:** `(user_message: str) -> str` — receives last user message
* **Chat History:** `(messages: list[dict]) -> str` — receives full chat history (OpenAI format)
* **Structured:** `(input_data: AgentInput) -> AgentResponse` — structured input/output

Both sync and async functions are supported. Use the structured signature when you need `usage_info`, `cost_info`, or `retrieval_context`. Only the structured signature receives the files a test case attaches; the other two fail the trace for a file-only test case.

> [!WARNING]
>
> An agent called from `simulate()` cannot answer with files. `output_file_paths` on the
> returned `AgentResponse` raises a `ValueError`, whether or not the response also carries
> text. A simulated conversation carries no files yet, on either side, so they would be
> dropped and the turn stored without them. Log a turn that answers with a document outside a
> simulation, with `traces.create(output_file_paths=...)`.

**max\_turns** `int`

Number of conversation turns this simulation may add. Defaults to the Test Case's max turns if not provided. When the test case [starts from a predefined conversation](https://docs.galtea.ai/v5.10/concepts/product/dataset/test-case.md#starting-a-scenario-from-a-conversation), the copied turns do not count against it: 4 predefined turns with `max_turns=1` call your agent once.

**log\_inference\_results** `bool`

> [!WARNING]
>
> **Deprecated** — Traces are now automatically tracked by the API. The parameter keeps its old name and no longer has any effect.

**enable\_last\_inference** `bool`

Whether to call your agent one final time after the simulated user sends their last message. Default: True.
When enabled, your agent will have the opportunity to respond to the conversation's final user message, ensuring complete dialogue coverage for evaluation purposes.

> [!WARNING]
>
> Setting this to `False` needs Galtea SDK 5.2.0 or later. A turn stays pending until something answers it, and the platform skips every evaluation on a session that holds a pending turn. From 5.2.0 the SDK closes that unanswered last turn for you. An earlier release leaves it pending, so the session gets no scores.
>
> Closing it is best effort. If that call fails, the simulation still returns normally and the session stays unscored, so check `result.metadata["last_turn_finalize_error"]` in any script or CI job.

**include\_metadata** `bool`

Whether to include metadata in the simulation result. Default: False

**agent\_goes\_first** `bool`

If True, the agent will generate the first message before any user messages are generated. Default: False

> [!NOTE]
>
> When `agent_goes_first` is set to `True`:
>
> * Any `input` (first user message) defined on the associated `TestCase` will be ignored.
> * The first call to your agent will have an empty `messages` list in the `AgentInput`. Ensure your agent function can handle cases where `input_data.last_user_message_str()` returns `None` (or the messages list is empty).
> * The opening turn is recorded as pending and only your agent's reply completes it. If the run stops during that first call, the turn stays pending, and the session's evaluations are skipped until something completes it.
> * It cannot be combined with a test case that [starts from a predefined conversation](https://docs.galtea.ai/v5.10/concepts/product/dataset/test-case.md#starting-a-scenario-from-a-conversation). The opening turn is recorded before the predefined conversation can be placed in front of it, so the simulation is refused.

**stop\_when\_agent\_returns\_empty\_response** `bool`

If True, the simulation will stop when the agent returns an empty (`""` / `None`) response. Default: True

> [!NOTE]
>
> When `stop_when_agent_returns_empty_response` is set to `False`:
>
> * The simulation will continue even if the agent returns a response that is empty (`""`) or `None`.
> * This allows for more flexible conversation flows where you want to capture all agent interactions regardless of content.
> * Be careful when using this option, as it may lead to further credit consumption if the agent keeps returning empty responses. To mitigate this, you can also make use of the `max_turns` parameter to set an upper limit on the number of turns.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.