Simulate Conversation

Returns

It returns a result object from the Conversation Simulator containing the complete conversation history, status, and metadata. This is used to analyze how your agent performed in the test scenario.

Agent Options

Simple
Chat History
Structured

The quickest way to get started. Your function receives just the latest user message as a string.

def my_agent(user_message: str) -> str:
    # In a real scenario, call your model here
    return f"Your model output to: {user_message}"

Use this when your agent needs the full conversation context. Your function receives the message list in the OpenAI format ({"role": "...", "content": "..."}).

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}"

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).

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},
    )

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.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.For the full list of fields available on AgentInput (including structured input access via message metadata), see the AgentInput reference.

AgentInput Fields

With the Structured signature ((input_data: AgentInput) -> AgentResponse), your function receives an AgentInput. That page lists every field and helper method, including input_files for reading attached files.

Example

# 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

str

required

The session identifier for this simulation.

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.

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=...).

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, the copied turns do not count against it: 4 predefined turns with max_turns=1 call your agent once.

bool

Deprecated — Traces are now automatically tracked by the API. The parameter keeps its old name and no longer has any effect.

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.

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.

bool

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

bool

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

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. The opening turn is recorded before the predefined conversation can be placed in front of it, so the simulation is refused.

bool

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

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.

Introduction

SDK

CLI

Concepts

Simulate Conversation

Returns

Agent Options

AgentInput Fields

Example

Parameters

​Returns

​Agent Options

​AgentInput Fields

​Example

​Parameters

Returns

Agent Options

AgentInput Fields

Example

Parameters