Simulation

Reference for client.simulation in the Future AGI Python and TypeScript SDKs: simulation.executions.analytics, simulation.executions.get, simulation.executions.list, simulation.scenarios.create, simulation.scenarios.get, simulation.scenarios.list and 5 more.

client.simulation on fi.Client (Python) and client.simulation on Client from @future-agi/sdk (TypeScript), with the nested resources client.simulation.executions, client.simulation.scenarios, client.simulation.tests. The models these methods return are on Simulation response models; how arguments, pagination, errors and strict mode work is in the overview.

Methods

MethodDescription
simulation.executions.analyticsReturn aggregated analytics for a simulation test execution.
simulation.executions.getReturn a simulation test execution by its identifier.
simulation.executions.listList simulation test executions.
simulation.scenarios.createCreate an agent or prompt simulation scenario of kind dataset, script or graph.
simulation.scenarios.getReturn a simulation scenario by its identifier.
simulation.scenarios.listList simulation scenarios in the current workspace.
simulation.scenarios.updateEdit supported scenario fields such as name, description, graph or prompt.
simulation.tests.createSave a simulation test using name, agent_definition_id and scenario_ids, optionally agent_version and evaluations_config.
simulation.tests.getRead a saved simulation test configuration, its agent/version and scenarios.
simulation.tests.listList saved simulation test configurations.
simulation.tests.runStart a saved simulation test asynchronously.

client.simulation

client.simulation.executions

TypeScript: client.simulation.executions.

simulation.executions.analytics

Return aggregated analytics for a simulation test execution.

GET /simulate/test-executions/{test_execution_id}/analytics/

MCP tool: get_test_execution_analytics

result = client.simulation.executions.analytics("your-test-execution-id")
const result = await client.simulation.executions.analytics("your-test-execution-id");
Signature
client.simulation.executions.analytics(
    test_execution_id: str,
    *,
    extra_query: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> models.TestExecutionAnalytics
client.simulation.executions.analytics(testExecutionId: string, options?: RequestOptions): Promise<models.TestExecutionAnalytics>

Parameters

test_execution_id string Required

Positional argument test_execution_id.

Returns

TestExecutionAnalytics.

simulation.executions.get

Return a simulation test execution by its identifier.

GET /simulate/test-executions/{test_execution_id}/

Paginated: returns a pager (how pagination works) · MCP tool: get_test_execution

for item in client.simulation.executions.get("your-test-execution-id"):
    print(item)
for await (const item of client.simulation.executions.get("your-test-execution-id")) {
  console.log(item);
}
Signature
client.simulation.executions.get(
    test_execution_id: str,
    *,
    search: str | None | NotGiven = NOT_GIVEN,
    filters: str | None | NotGiven = NOT_GIVEN,
    row_groups: str | None | NotGiven = NOT_GIVEN,
    group_keys: str | None | NotGiven = NOT_GIVEN,
    limit: int | None | NotGiven = NOT_GIVEN,
    extra_query: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> SyncPager[Any]
client.simulation.executions.get(testExecutionId: string, params: SimulationExecutionsGetParams = {}, options?: RequestOptions): Pager<unknown>

export interface SimulationExecutionsGetParams {
  search?: string | null;
  filters?: string | null;
  row_groups?: string | null;
  group_keys?: string | null;
  limit?: number | null;
}

Parameters

test_execution_id string Required

Positional argument test_execution_id.

search string Optional
filters string Optional
row_groups string Optional
group_keys string Optional
limit integer Optional

The pager sends page itself; pass limit to change the page size.

Returns

A pager of any items: iterate it, or call to_list() (Python) / toArray() (TypeScript).

simulation.executions.list

List simulation test executions.

GET /simulate/api/test-executions/

Paginated: returns a pager (how pagination works) · MCP tool: list_test_executions

for item in client.simulation.executions.list():
    print(item)
for await (const item of client.simulation.executions.list()) {
  console.log(item);
}
Signature
client.simulation.executions.list(
    *,
    search: str | None | NotGiven = NOT_GIVEN,
    status: str | None | NotGiven = NOT_GIVEN,
    limit: int | None | NotGiven = NOT_GIVEN,
    extra_query: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> SyncPager[models.TestExecution]
client.simulation.executions.list(params: SimulationExecutionsListParams = {}, options?: RequestOptions): Pager<models.TestExecution>

export interface SimulationExecutionsListParams {
  search?: string | null;
  status?: string | null;
  limit?: number | null;
}

Parameters

search string Optional
status string Optional
limit integer Optional

The pager sends page itself; pass limit to change the page size.

Returns

A pager of TestExecution items: iterate it, or call to_list() (Python) / toArray() (TypeScript).

client.simulation.scenarios

TypeScript: client.simulation.scenarios.

simulation.scenarios.create

Create an agent or prompt simulation scenario of kind dataset, script or graph. Generation is asynchronous and may incur usage charges; poll get_scenario until ready before running tests. Requires the applicable plan entitlement.

POST /simulate/scenarios/create/

MCP tool: create_scenario

result = client.simulation.scenarios.create(name="your-name")
const result = await client.simulation.scenarios.create({ name: "your-name" });
Signature
client.simulation.scenarios.create(
    *,
    name: str,
    description: str | None | NotGiven = NOT_GIVEN,
    dataset_id: str | None | NotGiven = NOT_GIVEN,
    kind: Literal['graph', 'script', 'dataset'] | None | NotGiven = NOT_GIVEN,
    script_url: str | None | NotGiven = NOT_GIVEN,
    agent_definition_id: str | None | NotGiven = NOT_GIVEN,
    agent_definition_version_id: str | None | NotGiven = NOT_GIVEN,
    custom_instruction: str | None | NotGiven = NOT_GIVEN,
    no_of_rows: int | None | NotGiven = NOT_GIVEN,
    generate_graph: bool | None | NotGiven = NOT_GIVEN,
    graph: dict[str, Any] | None | NotGiven = NOT_GIVEN,
    source_type: Literal['agent_definition', 'prompt'] | None | NotGiven = NOT_GIVEN,
    prompt_template_id: str | None | NotGiven = NOT_GIVEN,
    prompt_version_id: str | None | NotGiven = NOT_GIVEN,
    add_persona_automatically: bool | None | NotGiven = NOT_GIVEN,
    personas: list[str] | None | NotGiven = NOT_GIVEN,
    custom_columns: list[dict[str, Any]] | None | NotGiven = NOT_GIVEN,
    agent_name: str | None | NotGiven = NOT_GIVEN,
    agent_prompt: str | None | NotGiven = NOT_GIVEN,
    voice_provider: str | None | NotGiven = NOT_GIVEN,
    voice_name: str | None | NotGiven = NOT_GIVEN,
    model: str | None | NotGiven = NOT_GIVEN,
    llm_temperature: float | None | NotGiven = NOT_GIVEN,
    initial_message: str | None | NotGiven = NOT_GIVEN,
    max_call_duration_in_minutes: int | None | NotGiven = NOT_GIVEN,
    interrupt_sensitivity: float | None | NotGiven = NOT_GIVEN,
    conversation_speed: float | None | NotGiven = NOT_GIVEN,
    finished_speaking_sensitivity: float | None | NotGiven = NOT_GIVEN,
    initial_message_delay: int | None | NotGiven = NOT_GIVEN,
    extra_query: dict[str, Any] | None = None,
    extra_body: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> Any
client.simulation.scenarios.create(params: SimulationScenariosCreateParams, options?: RequestOptions): Promise<unknown>

export interface SimulationScenariosCreateParams {
  name: string;
  description?: string | null;
  dataset_id?: string | null;
  kind?: "graph" | "script" | "dataset" | null;
  script_url?: string | null;
  agent_definition_id?: string | null;
  agent_definition_version_id?: string | null;
  custom_instruction?: string | null;
  no_of_rows?: number | null;
  generate_graph?: boolean | null;
  graph?: Record<string, unknown> | null;
  source_type?: "agent_definition" | "prompt" | null;
  prompt_template_id?: string | null;
  prompt_version_id?: string | null;
  add_persona_automatically?: boolean | null;
  personas?: Array<string> | null;
  custom_columns?: Array<Record<string, unknown>> | null;
  agent_name?: string | null;
  agent_prompt?: string | null;
  voice_provider?: string | null;
  voice_name?: string | null;
  model?: string | null;
  llm_temperature?: number | null;
  initial_message?: string | null;
  max_call_duration_in_minutes?: number | null;
  interrupt_sensitivity?: number | null;
  conversation_speed?: number | null;
  finished_speaking_sensitivity?: number | null;
  initial_message_delay?: number | null;
}

Parameters

name string Required
description string Optional
dataset_id string Optional
kind string Optional
Allowed values:
graphscriptdataset
script_url string Optional
agent_definition_id string Optional
agent_definition_version_id string Optional
custom_instruction string Optional
no_of_rows integer Optional
generate_graph boolean Optional
graph object Optional
source_type string Optional
Allowed values:
agent_definitionprompt
prompt_template_id string Optional
prompt_version_id string Optional
add_persona_automatically boolean Optional
personas string[] Optional
custom_columns object[] Optional
agent_name string Optional
agent_prompt string Optional
voice_provider string Optional
voice_name string Optional
model string Optional
llm_temperature number Optional
initial_message string Optional
max_call_duration_in_minutes integer Optional
interrupt_sensitivity number Optional
conversation_speed number Optional
finished_speaking_sensitivity number Optional
initial_message_delay integer Optional

Returns

The decoded response. The contract does not describe its shape, so it is untyped.

simulation.scenarios.get

Return a simulation scenario by its identifier.

GET /simulate/scenarios/{scenario_id}/

MCP tool: get_scenario

result = client.simulation.scenarios.get("your-scenario-id")
const result = await client.simulation.scenarios.get("your-scenario-id");
Signature
client.simulation.scenarios.get(
    scenario_id: str,
    *,
    extra_query: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> models.ScenarioDetailResponse
client.simulation.scenarios.get(scenarioId: string, options?: RequestOptions): Promise<models.ScenarioDetailResponse>

Parameters

scenario_id string Required

Positional argument scenario_id.

Returns

ScenarioDetailResponse.

simulation.scenarios.list

List simulation scenarios in the current workspace.

GET /simulate/scenarios/

Paginated: returns a pager (how pagination works) · MCP tool: list_scenarios

for item in client.simulation.scenarios.list():
    print(item)
for await (const item of client.simulation.scenarios.list()) {
  console.log(item);
}
Signature
client.simulation.scenarios.list(
    *,
    search: str | None | NotGiven = NOT_GIVEN,
    agent_definition_id: str | None | NotGiven = NOT_GIVEN,
    agent_type: str | None | NotGiven = NOT_GIVEN,
    limit: int | None | NotGiven = NOT_GIVEN,
    extra_query: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> SyncPager[models.ScenarioResponse]
client.simulation.scenarios.list(params: SimulationScenariosListParams = {}, options?: RequestOptions): Pager<models.ScenarioResponse>

export interface SimulationScenariosListParams {
  search?: string | null;
  agent_definition_id?: string | null;
  agent_type?: string | null;
  limit?: number | null;
}

Parameters

search string Optional
agent_definition_id string Optional
agent_type string Optional
limit integer Optional

The pager sends page itself; pass limit to change the page size.

Returns

A pager of ScenarioResponse items: iterate it, or call to_list() (Python) / toArray() (TypeScript).

simulation.scenarios.update

Edit supported scenario fields such as name, description, graph or prompt. This is not a dataset-row editor or a simulation execution.

PUT /simulate/scenarios/{scenario_id}/edit/

MCP tool: update_scenario

result = client.simulation.scenarios.update("your-scenario-id")
const result = await client.simulation.scenarios.update("your-scenario-id");
Signature
client.simulation.scenarios.update(
    scenario_id: str,
    *,
    name: str | None | NotGiven = NOT_GIVEN,
    description: str | None | NotGiven = NOT_GIVEN,
    graph: dict[str, Any] | None | NotGiven = NOT_GIVEN,
    prompt: str | None | NotGiven = NOT_GIVEN,
    extra_query: dict[str, Any] | None = None,
    extra_body: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> models.ScenarioEditResponse
client.simulation.scenarios.update(scenarioId: string, params: SimulationScenariosUpdateParams = {}, options?: RequestOptions): Promise<models.ScenarioEditResponse>

export interface SimulationScenariosUpdateParams {
  name?: string | null;
  description?: string | null;
  graph?: Record<string, unknown> | null;
  prompt?: string | null;
}

Parameters

scenario_id string Required

Positional argument scenario_id.

name string Optional
description string Optional
graph object Optional
prompt string Optional

Returns

ScenarioEditResponse.

client.simulation.tests

TypeScript: client.simulation.tests.

simulation.tests.create

Save a simulation test using name, agent_definition_id and scenario_ids, optionally agent_version and evaluations_config. Does not execute it; pass the returned test ID to run_simulation.

POST /simulate/run-tests/create/

MCP tool: create_simulation_test

result = client.simulation.tests.create(
    name="your-name",
    agent_definition_id="your-agent-definition-id",
    scenario_ids=[],
)
const result = await client.simulation.tests.create({
  name: "your-name",
  agent_definition_id: "your-agent-definition-id",
  scenario_ids: [],
});
Signature
client.simulation.tests.create(
    *,
    name: str,
    agent_definition_id: str,
    scenario_ids: list[str],
    description: str | None | NotGiven = NOT_GIVEN,
    dataset_row_ids: list[str] | None | NotGiven = NOT_GIVEN,
    eval_config_ids: list[str] | None | NotGiven = NOT_GIVEN,
    evaluations_config: list[dict[str, Any]] | None | NotGiven = NOT_GIVEN,
    enable_tool_evaluation: bool | None | NotGiven = NOT_GIVEN,
    replay_session_id: str | None | NotGiven = NOT_GIVEN,
    agent_version: str | None | NotGiven = NOT_GIVEN,
    extra_query: dict[str, Any] | None = None,
    extra_body: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> models.RunTestResponse
client.simulation.tests.create(params: SimulationTestsCreateParams, options?: RequestOptions): Promise<models.RunTestResponse>

export interface SimulationTestsCreateParams {
  name: string;
  agent_definition_id: string;
  scenario_ids: Array<string>;
  description?: string | null;
  dataset_row_ids?: Array<string> | null;
  eval_config_ids?: Array<string> | null;
  evaluations_config?: Array<Record<string, unknown>> | null;
  enable_tool_evaluation?: boolean | null;
  replay_session_id?: string | null;
  agent_version?: string | null;
}

Parameters

name string Required
agent_definition_id string Required
scenario_ids string[] Required
description string Optional
dataset_row_ids string[] Optional
eval_config_ids string[] Optional
evaluations_config object[] Optional
enable_tool_evaluation boolean Optional
replay_session_id string Optional
agent_version string Optional

Returns

RunTestResponse.

simulation.tests.get

Read a saved simulation test configuration, its agent/version and scenarios.

GET /simulate/run-tests/{run_test_id}/

MCP tool: get_simulation_test

result = client.simulation.tests.get("your-run-test-id")
const result = await client.simulation.tests.get("your-run-test-id");
Signature
client.simulation.tests.get(
    run_test_id: str,
    *,
    extra_query: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> models.RunTestResponse
client.simulation.tests.get(runTestId: string, options?: RequestOptions): Promise<models.RunTestResponse>

Parameters

run_test_id string Required

Positional argument run_test_id.

Returns

RunTestResponse.

simulation.tests.list

List saved simulation test configurations. A test configuration is distinct from its executions; use list_test_executions to inspect runs.

GET /simulate/run-tests/

Paginated: returns a pager (how pagination works) · MCP tool: list_simulation_tests

for item in client.simulation.tests.list():
    print(item)
for await (const item of client.simulation.tests.list()) {
  console.log(item);
}
Signature
client.simulation.tests.list(
    *,
    search: str | None | NotGiven = NOT_GIVEN,
    simulation_type: Literal['agent_definition', 'prompt'] | None | NotGiven = NOT_GIVEN,
    prompt_template_id: str | None | NotGiven = NOT_GIVEN,
    limit: int | None | NotGiven = NOT_GIVEN,
    summary: bool | None | NotGiven = NOT_GIVEN,
    extra_query: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> SyncPager[models.RunTestResponse]
client.simulation.tests.list(params: SimulationTestsListParams = {}, options?: RequestOptions): Pager<models.RunTestResponse>

export interface SimulationTestsListParams {
  search?: string | null;
  simulation_type?: "agent_definition" | "prompt" | null;
  prompt_template_id?: string | null;
  limit?: number | null;
  /** Return the bounded list-card representation instead of the full nested run-test detail payload. */
  summary?: boolean | null;
}

Parameters

search string Optional
simulation_type string Optional
Allowed values:
agent_definitionprompt
prompt_template_id string Optional
limit integer Optional
summary boolean Optional

Return the bounded list-card representation instead of the full nested run-test detail payload.

The pager sends page itself; pass limit to change the page size.

Returns

A pager of RunTestResponse items: iterate it, or call to_list() (Python) / toArray() (TypeScript).

simulation.tests.run

Start a saved simulation test asynchronously. Omit scenario_ids to run all configured scenarios. Uses existing provider/worker infrastructure and can incur usage charges. Poll get_test_execution with the returned execution_id, then read get_test_execution_analytics.

POST /simulate/run-tests/{run_test_id}/execute/

MCP tool: run_simulation

result = client.simulation.tests.run("your-run-test-id")
const result = await client.simulation.tests.run("your-run-test-id");
Signature
client.simulation.tests.run(
    run_test_id: str,
    *,
    scenario_ids: list[str] | None | NotGiven = NOT_GIVEN,
    simulator_id: str | None | NotGiven = NOT_GIVEN,
    select_all: bool | None | NotGiven = NOT_GIVEN,
    extra_query: dict[str, Any] | None = None,
    extra_body: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> models.RunTestExecutionResponse
client.simulation.tests.run(runTestId: string, params: SimulationTestsRunParams = {}, options?: RequestOptions): Promise<models.RunTestExecutionResponse>

export interface SimulationTestsRunParams {
  scenario_ids?: Array<string> | null;
  simulator_id?: string | null;
  select_all?: boolean | null;
}

Parameters

run_test_id string Required

Positional argument run_test_id.

scenario_ids string[] Optional
simulator_id string Optional
select_all boolean Optional

Returns

RunTestExecutionResponse.

Was this page helpful?

Questions & Discussion