curl --request POST \
--url https://api.eqho.ai/v1/simulation/scenarios \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '
{
"name": "<string>",
"lead_scenario": {
"instructions": {
"task_instructions": "<string>",
"language": "en",
"reason_for_call": "<string>",
"known_info": "<string>",
"unknown_info": "<string>"
},
"persona": "<string>",
"actions": {
"terminate_call": {
"name": "<string>",
"slug": "<string>",
"instructions": "<string>",
"type": "call_transfer",
"settings": {},
"messages": {
"start": "<string>",
"completed": "<string>",
"failed": "<string>",
"delayed": "<string>"
},
"minimum_execution_time_milliseconds": 123,
"delayed_timing_milliseconds": 123,
"is_async": false,
"non_live_llm_settings": {
"model": "gpt-4o-mini",
"temperature": 0,
"reasoning": "none",
"text_verbosity": "low"
},
"execution_type": "live",
"response_mode": "interactive",
"execution_order": 123
}
}
},
"scenario_set_id": "<string>",
"folder": "Flight cancellation",
"description": {
"purpose": "Test that agent refuses cancellation with refund if criteria are not met"
},
"environment_setup": {
"dynamic_variables": {
"lead.custom_fields.membership_status": "gold"
},
"conversation_direction": "inbound",
"conversation_medium": "chatbot",
"action_mocks": {},
"message_history": [
{
"role": "system",
"content": "<string>"
}
]
},
"evaluation_criteria": {
"actions": [
{
"tool_call_id": "<string>",
"name": "<string>",
"arguments": {},
"requestor": "assistant",
"info": "<string>",
"compare_args": [
"<string>"
]
}
],
"nl_assertions": [
"<string>"
]
}
}
'{
"_id": "<string>",
"account_id": "<string>",
"name": "<string>",
"lead_scenario": {
"instructions": {
"task_instructions": "<string>",
"language": "en",
"reason_for_call": "<string>",
"known_info": "<string>",
"unknown_info": "<string>"
},
"persona": "<string>",
"actions": {
"terminate_call": {
"name": "<string>",
"slug": "<string>",
"instructions": "<string>",
"type": "call_transfer",
"settings": {},
"messages": {
"start": "<string>",
"completed": "<string>",
"failed": "<string>",
"delayed": "<string>"
},
"minimum_execution_time_milliseconds": 123,
"delayed_timing_milliseconds": 123,
"is_async": false,
"non_live_llm_settings": {
"model": "gpt-4o-mini",
"temperature": 0,
"reasoning": "none",
"text_verbosity": "low"
},
"execution_type": "live",
"response_mode": "interactive",
"execution_order": 123
}
}
},
"history": {
"last_modified_at": "2023-11-07T05:31:56Z",
"revision": 0,
"created_at": "2023-11-07T05:31:56Z",
"created_by": "unknown",
"last_modified_by": "unknown"
},
"scenario_set_id": "<string>",
"folder": "<string>",
"description": {
"purpose": "<string>",
"notes": "<string>"
},
"environment_setup": {
"dynamic_variables": {
"lead.custom_fields.membership_status": "gold"
},
"conversation_direction": "inbound",
"conversation_medium": "chatbot",
"action_mocks": {},
"message_history": [
{
"content": "<string>",
"role": "system",
"turn_idx": 123,
"timestamp": "2023-11-07T05:31:56Z"
}
]
},
"evaluation_criteria": {
"actions": [
{
"tool_call_id": "<string>",
"name": "<string>",
"arguments": {},
"requestor": "assistant",
"info": "<string>",
"compare_args": [
"<string>"
]
}
],
"nl_assertions": [
"<string>"
]
}
}Create Scenario
Create a new simulation scenario
curl --request POST \
--url https://api.eqho.ai/v1/simulation/scenarios \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '
{
"name": "<string>",
"lead_scenario": {
"instructions": {
"task_instructions": "<string>",
"language": "en",
"reason_for_call": "<string>",
"known_info": "<string>",
"unknown_info": "<string>"
},
"persona": "<string>",
"actions": {
"terminate_call": {
"name": "<string>",
"slug": "<string>",
"instructions": "<string>",
"type": "call_transfer",
"settings": {},
"messages": {
"start": "<string>",
"completed": "<string>",
"failed": "<string>",
"delayed": "<string>"
},
"minimum_execution_time_milliseconds": 123,
"delayed_timing_milliseconds": 123,
"is_async": false,
"non_live_llm_settings": {
"model": "gpt-4o-mini",
"temperature": 0,
"reasoning": "none",
"text_verbosity": "low"
},
"execution_type": "live",
"response_mode": "interactive",
"execution_order": 123
}
}
},
"scenario_set_id": "<string>",
"folder": "Flight cancellation",
"description": {
"purpose": "Test that agent refuses cancellation with refund if criteria are not met"
},
"environment_setup": {
"dynamic_variables": {
"lead.custom_fields.membership_status": "gold"
},
"conversation_direction": "inbound",
"conversation_medium": "chatbot",
"action_mocks": {},
"message_history": [
{
"role": "system",
"content": "<string>"
}
]
},
"evaluation_criteria": {
"actions": [
{
"tool_call_id": "<string>",
"name": "<string>",
"arguments": {},
"requestor": "assistant",
"info": "<string>",
"compare_args": [
"<string>"
]
}
],
"nl_assertions": [
"<string>"
]
}
}
'{
"_id": "<string>",
"account_id": "<string>",
"name": "<string>",
"lead_scenario": {
"instructions": {
"task_instructions": "<string>",
"language": "en",
"reason_for_call": "<string>",
"known_info": "<string>",
"unknown_info": "<string>"
},
"persona": "<string>",
"actions": {
"terminate_call": {
"name": "<string>",
"slug": "<string>",
"instructions": "<string>",
"type": "call_transfer",
"settings": {},
"messages": {
"start": "<string>",
"completed": "<string>",
"failed": "<string>",
"delayed": "<string>"
},
"minimum_execution_time_milliseconds": 123,
"delayed_timing_milliseconds": 123,
"is_async": false,
"non_live_llm_settings": {
"model": "gpt-4o-mini",
"temperature": 0,
"reasoning": "none",
"text_verbosity": "low"
},
"execution_type": "live",
"response_mode": "interactive",
"execution_order": 123
}
}
},
"history": {
"last_modified_at": "2023-11-07T05:31:56Z",
"revision": 0,
"created_at": "2023-11-07T05:31:56Z",
"created_by": "unknown",
"last_modified_by": "unknown"
},
"scenario_set_id": "<string>",
"folder": "<string>",
"description": {
"purpose": "<string>",
"notes": "<string>"
},
"environment_setup": {
"dynamic_variables": {
"lead.custom_fields.membership_status": "gold"
},
"conversation_direction": "inbound",
"conversation_medium": "chatbot",
"action_mocks": {},
"message_history": [
{
"content": "<string>",
"role": "system",
"turn_idx": 123,
"timestamp": "2023-11-07T05:31:56Z"
}
]
},
"evaluation_criteria": {
"actions": [
{
"tool_call_id": "<string>",
"name": "<string>",
"arguments": {},
"requestor": "assistant",
"info": "<string>",
"compare_args": [
"<string>"
]
}
],
"nl_assertions": [
"<string>"
]
}
}Authorizations
Body
Name of the simulation scenario
User scenario. This information will be sent to the user simulator.
Show child attributes
Show child attributes
Instructions for the User. This information defines the specific situation the user is in and the tasks they are trying to complete.
Show child attributes
Show child attributes
Primary instructions for what the simulated user should do during the conversation.
Language that the simulated user will answer in (ISO 639-1 code, e.g., 'en', 'es', 'fr')
Why the user is initiating contact. Helps provide context to the simulated user.
Information the simulated user knows and can share (e.g., account details, order numbers). The user will volunteer this information when relevant.
Information the simulated user doesn't know and shouldn't be able to provide. Useful for testing how the agent handles missing information.
User's persona. This information defines the user in general, not the specific situation they are in.
Built-in actions for the simulated lead. Currently, only terminate_call is supported.
Show child attributes
Show child attributes
Use this action to tell the lead when to end the call
Show child attributes
Show child attributes
call_transfer, terminate_call, email, text, webhook, custom_call_transfer, http_request, gcal_appointment_schedule, gcal_check_busy_time, gcal_get_free_slots, gcal_fetch_appointments, gcal_cancel_appointment, gcal_update_appointment, data_extraction, set_lead_email, set_lead_names, set_lead_timezone Show child attributes
Show child attributes
o1-mini, o1-preview, o1, o3-mini, gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-4-turbo-preview, gpt-4-0125-preview, gpt-4-1106-preview, gpt-4, gpt-4-0613, gpt-3.5-turbo, gpt-3.5-turbo-16k, gpt-3.5-turbo-1106, gpt-3.5-turbo-0125, claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022, claude-3-opus-20240229, claude-3-sonnet-20240229, claude-3-haiku-20240307, gpt-4.5-preview, gpt-4.1-mini, gpt-4.1, gpt-4.1-nano, o3, gpt-5, gpt-5-mini, gpt-5-nano, gpt-5-chat-latest none, low, medium, high low, medium, high live, postcall, on_call_start interactive, silent ID of the scenario set this scenario belongs to
24Folder to organize scenarios
"Flight cancellation"
Description of the task. This can be sent to the evaluator.
{
"purpose": "Test that agent refuses cancellation with refund if criteria are not met"
}Initial state of the simulation. Also, used to define action mocks and mention mocks.
Show child attributes
Show child attributes
Variables to inject into the Agent prompt. Defined as set of dotted strings
{
"lead.custom_fields.membership_status": "gold"
}Determines who initiates the conversation. - 'inbound': User contacts agent (agent speaks first with greeting) - 'outbound': Agent contacts user (agent speaks first with introduction). Only used if message_history is empty.
outbound, inbound Conversation medium of the simulation.
chatbot, sms Defines simulated responses for agent actions.Maps action slugs to mock results. Use to avoid executing real actions during simulation.
Show child attributes
Show child attributes
Defines a mocked action behavior during simulation.
Pre-loaded conversation history to start the simulation mid-conversation. The simulation continues from where this history ends. If last message is from user, agent responds next; if from agent, user responds next.
Evaluation criteria for the scenario. This will be sent to the evaluator.
Show child attributes
Show child attributes
The actions that the agent should take to complete the task.
Show child attributes
Show child attributes
The unique identifier for the gold tool call within a scenario.
The action/tool name (must match an action slug configured in the agent).
Expected arguments for the tool call. Used for validation against actual calls.
Who should make this call (usually 'assistant' for agent actions).
user, assistant Human-readable explanation of why this tool call is expected. Not used in validation.
List of argument keys to validate. If None, validates ALL arguments match exactly. Use this to ignore arguments that may vary (like timestamps or auto-generated IDs).
Natural language success criteria evaluated by an LLM. Each assertion should be a statement that can be evaluated as true or false based on the conversation. For example, 'Agent successfully processed the refund.'
Response
Successful Response
A simulation scenario template that defines how to simulate a conversation
See Also:
- SimulationRunModel: Individual execution of this scenario
- ScenarioSetModel: Grouping multiple scenarios together
- SimulationResultsModel: Aggregated results from running scenarios
Account ID that owns this simulation scenario
Human-readable scenario name
User scenario. This information will be sent to the user simulator.
Show child attributes
Show child attributes
Instructions for the User. This information defines the specific situation the user is in and the tasks they are trying to complete.
Show child attributes
Show child attributes
Primary instructions for what the simulated user should do during the conversation.
Language that the simulated user will answer in (ISO 639-1 code, e.g., 'en', 'es', 'fr')
Why the user is initiating contact. Helps provide context to the simulated user.
Information the simulated user knows and can share (e.g., account details, order numbers). The user will volunteer this information when relevant.
Information the simulated user doesn't know and shouldn't be able to provide. Useful for testing how the agent handles missing information.
User's persona. This information defines the user in general, not the specific situation they are in.
Built-in actions for the simulated lead. Currently, only terminate_call is supported.
Show child attributes
Show child attributes
Use this action to tell the lead when to end the call
Show child attributes
Show child attributes
call_transfer, terminate_call, email, text, webhook, custom_call_transfer, http_request, gcal_appointment_schedule, gcal_check_busy_time, gcal_get_free_slots, gcal_fetch_appointments, gcal_cancel_appointment, gcal_update_appointment, data_extraction, set_lead_email, set_lead_names, set_lead_timezone Show child attributes
Show child attributes
o1-mini, o1-preview, o1, o3-mini, gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-4-turbo-preview, gpt-4-0125-preview, gpt-4-1106-preview, gpt-4, gpt-4-0613, gpt-3.5-turbo, gpt-3.5-turbo-16k, gpt-3.5-turbo-1106, gpt-3.5-turbo-0125, claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022, claude-3-opus-20240229, claude-3-sonnet-20240229, claude-3-haiku-20240307, gpt-4.5-preview, gpt-4.1-mini, gpt-4.1, gpt-4.1-nano, o3, gpt-5, gpt-5-mini, gpt-5-nano, gpt-5-chat-latest none, low, medium, high low, medium, high live, postcall, on_call_start interactive, silent ID of the scenario set this scenario belongs to
Optional folder path for organizing scenarios in the UI
Initial state of the simulation. Also, used to define action mocks and mention mocks.
Show child attributes
Show child attributes
Variables to inject into the Agent prompt. Defined as set of dotted strings
{
"lead.custom_fields.membership_status": "gold"
}Determines who initiates the conversation. - 'inbound': User contacts agent (agent speaks first with greeting) - 'outbound': Agent contacts user (agent speaks first with introduction). Only used if message_history is empty.
outbound, inbound Conversation medium of the simulation.
chatbot, sms Defines simulated responses for agent actions.Maps action slugs to mock results. Use to avoid executing real actions during simulation.
Show child attributes
Show child attributes
Defines a mocked action behavior during simulation.
Pre-loaded conversation history to start the simulation mid-conversation. The simulation continues from where this history ends. If last message is from user, agent responds next; if from agent, user responds next.
A system message.
- SystemMessage
- AssistantMessage
- UserMessage
- ToolMessage
Show child attributes
Show child attributes
The content of the message.
The role of the message sender.
"system"The index of the turn in the conversation.
The timestamp of the message.
Evaluation criteria for the scenario. This will be sent to the evaluator.
Show child attributes
Show child attributes
The actions that the agent should take to complete the task.
Show child attributes
Show child attributes
The unique identifier for the gold tool call within a scenario.
The action/tool name (must match an action slug configured in the agent).
Expected arguments for the tool call. Used for validation against actual calls.
Who should make this call (usually 'assistant' for agent actions).
user, assistant Human-readable explanation of why this tool call is expected. Not used in validation.
List of argument keys to validate. If None, validates ALL arguments match exactly. Use this to ignore arguments that may vary (like timestamps or auto-generated IDs).
Natural language success criteria evaluated by an LLM. Each assertion should be a statement that can be evaluated as true or false based on the conversation. For example, 'Agent successfully processed the refund.'
Was this page helpful?