Workflows

The paths your agent takes from a question to an answer. Each step names the tools it uses; the tool reference has their full signatures.

Choose the right environment

1. Orient. whoami for the account and scopes, then list_environments — a saved environment may already answer the question.
2. Ready or custom. Market, Exchange, Council and Dispute run without authoring. Anything else is built as a custom environment: one JSON contract in the Environments SDK language.
3. Define the question. Participants or process, time horizon, the inputs you control, decision rules and the outputs to measure. Real-world assumptions that are not supported by data are labelled as assumptions.

Run a ready environment

For Market (a consumer market reacting to a product), Exchange (a trading venue), Council (a panel deliberating a question) and Dispute (a case argued to a verdict).

1. list_fareground_environments — each environment's settings with types and defaults, and its catalog: presets, products, instruments.
2. prepare_fareground_session(environment, config) — creates the session unstarted and free, with a page where you review and edit it.
3. For a dispute, write_dispute_case_file records your side of the case while it is being prepared, before it starts.
4. start_fareground_session — starts it, billed. Failed attempts count toward the run limits you asked for, so your agent does not restart or replace them on its own.
5. get_fareground_session — progress, or the recorded outcome.
6. get_fareground_session_evidence — the evidence behind it: for Exchange the seed history and price and news bars, for Market the roster, purchases and full reports. Page with after until next_after is null.

Answer a question in one call

When you asked for a result, your agent can run a whole custom study in a single call.

1. Read environment_authoring_guide() and the closest engine (list_environment_engines, get_environment_engine).
2. Write the contract for the question: rules, actions, information, outputs.
3. Work out known-answer cases — expected outputs at the actual inputs and horizon.
4. simulate_custom_environment(contract, request_id, cases, question, input_values, agent_bindings, n_runs, max_rounds, datasets, comparison, fit_patterns):
5. agent_bindings — who plays each role: a model with instructions, or a coded policy.
6. datasets — CSV, JSON or JSONL data for table and list inputs.
7. comparison — 2 to 8 labelled conditions run side by side, each with a known-answer case.
8. It saves the environment, verifies the cases and runs the agents. If a check fails, no runs are queued and nothing is billed for runs.
9. Follow the returned operation_id with get_custom_study (or stop it before admission with stop_custom_study), then get_custom_run or wait_for_custom_run for the results.

Build a custom environment step by step

The loop is write → check → save → preview → probe and verify → run → report.

1. Write. environment_authoring_guide() opens on a worked contract; core maps every other part (cookbook, expressions, actions, events, inputs, patterns …). environment_contract_schema(path) gives exact fields. Or start from an engine: list_environment_engines, then get_environment_engine for an executable starter. Every number in the brief becomes an input whose default is that number.
2. People. sample_personas creates a reproducible cohort with its sampling provenance. A role with a coded policy plays without model calls — right for crowds and baselines; a role without one takes a model seat in paid runs.
3. Check. check_environment_contract(contract, input_values) returns each issue with a path, message and fix, plus presentation issues — what people will read on the environment and run pages. A pass means the contract loads, not that it is right.
4. Save. create_custom_environment returns an id and revision. get_environment_page shows it as people will see it.
5. Preview. preview_custom_environment resolves real entity IDs and stages, and shows exactly what one participant reads and which actions it has.
6. Probe and verify. probe_custom_environment runs a free structural play, random or scripted. verify_custom_environment runs up to eight known-answer cases against one saved revision. analyze_custom_environment samples input boundaries for rule failures. fit_custom_environment fits declared patterns to supplied data, and import_custom_dataset loads a table input from CSV, JSON or JSONL.
7. Edit. get_custom_environment for the current contract and revision. patch_custom_environment replaces chosen top-level sections; update_custom_environment replaces the whole contract. Both need expected_revision, and both invalidate earlier checks — preview and verify again.

None of these checks establishes real-world accuracy; they establish that the environment does what its contract says.

Run and read results

1. Before a paid run, the current revision needs a passing probe or verification with the exact inputs, through at least the requested number of rounds. Your agent checks get_balance and get_cost_estimates and starts small.
2. Start. start_custom_run(environment_id, request_id, n_runs, max_rounds, input_values). Run i uses seed i. On an uncertain start it retries with the same request ID.
3. Follow. wait_for_custom_run (returns within 30 seconds; a timeout does not cancel) or get_custom_run — each run's outcomes and execution quality, and the report across completed seeds once all runs finish.
4. Read. get_custom_run_data pages through one run's inputs, outputs, series, diagnostics, agent_bindings, contract or decisions. set_environment_metrics chooses which results the report leads with. list_custom_runs recovers earlier sessions; stop_custom_run cancels.
5. Report honestly. The modeled rules, inputs and their sources, run count, spread, failed runs and limits. Simulated outcomes are kept apart from observed data; one run, a passing probe or a valid contract is not proof of predictive accuracy.

Scenario-format environments

The older format, still supported for environments saved in it. New work is built as custom environments.

1. get_environment — the full definition; list_mechanisms, list_outcome_options and list_patterns show the building blocks; autofill_environment grounds inputs where research is available.
2. run_environment with a UUID request_id starts an ensemble — independent simulations differing only by seed. use_llm=False is a free structure check, not evidence.
3. get_run or wait_for_run, then get_run_report and get_run_events. extend_run adds runs; cancel_run stops them; list_runs finds earlier ones. The spread across the ensemble is the result.