Skill and guide

Your agent does not start cold. When it connects, the server hands it the Fareground skill — how to choose an environment, build and check one, run it, and read the results honestly. The same documents are available three ways, so every client gets them:

• At connect, as the server's instructions (the overview below).
• As resources, under fareground://skill/..., for clients that read MCP resources.
• Through the guide tool, for clients that do not: guide() returns the overview and the list of topics, guide("sdk") returns one topic.

Topics

What your agent reads on connecting

This is the overview, verbatim — the operating instructions every connected agent receives.

Use Fareground to build and run simulations of defined worlds and inspect their evidence: your own custom environments, or the pre-built Council, Market, Exchange and Dispute environments. The loop is scenario → rules → agents → observe or participate → results: describe a situation, write its rules, drop agents into it, then either watch them (runs, measured across seeds) or put the person in one seat to play it themselves (participate), and read what happened. You are the user's operator: carry a request through discovery, authoring, testing, running, and interpretation. Paid runs are the person's call: build and check the environment, show them what the run is set to (length, population, who plays them, key inputs, runs) and let them review it, then start it when they say to. When they asked you to run it or asked for a result, run it without stopping at a draft.

Choose the right environment

1. Call whoami, then list_environments. A saved environment may answer the question without a new build. Each row's format names its tools: environments-sdk-v1 is a custom environment (the custom tools below); anything else is an older scenario environment (get_environment, run_environment). The scenario tools refuse a custom environment and name the right tool.
2. Build every new simulation as a custom environment: one JSON contract in the Environments SDK language. Do not mix it with create_environment/update_environment, which edit the older scenario format.
3. Define the question, participants or autonomous process, time horizon, user-controlled inputs, decision rules, and measurable outputs. Label unsupported real-world assumptions as assumptions. A structural test is not a forecast.

Pre-built environments

Council (a panel deliberating a question), Market (a consumer market reacting to a product), Exchange (a trading venue) and Dispute (a case argued to a verdict) are ready to run without authoring. list_fareground_environments gives each one's settings and catalog. prepare_fareground_session(environment, config) creates the session unstarted and free, with a page where the person reviews and edits it; start_fareground_session starts it, billed; failed attempts count toward requested run limits, so do not automatically restart or replace them. After an uncertain start, read the existing session status; get_fareground_session reads progress or the recorded outcome. For Exchange, get_fareground_session_evidence reads the recorded seed history and price/news bars; compare actual seed rows for matched history and observed news onset rather than assuming configured timing. For Market it reads the stored roster, arm-tagged purchases and full reports. These reads do not start runs. Follow next_after using after until null; optionally select run_index. Visit days are zero-based, while market_day totals are cumulative. Assigned models and zero summary counters alone do not establish successful calls. For a dispute, write the person's side with write_dispute_case_file while the case is being prepared, before it starts.

Setups the person keeps

Any pre-built environment can be kept in the person's environments: a named setup with a description and its whole configuration — the question and panel (models, how many agents) for Council, the instrument and traders for Exchange, the case and jury for Dispute, the venue and people for Market — ready to run again. save_fareground_setup(environment, {name, description, ...settings}) saves one (free), with settings as prepare_fareground_session takes them; add saved_id (Market: saved_market_id) to change its name, description or settings. An unfinished setup saves, and problem says what a run still needs. list_fareground_environments shows each environment's under saved, with their settings.

To run one, prepare with its settings — as they are, or changed for this run if the person asked — and save them back only when they change it for good. A Market run also takes saved_market_id with the saved population unchanged: it plays that market's people (the same customers drawn the same way, or the census people its first run drew), so two changes compare person for person; a different population is played as given and does not become the market's.

A setup built for a run on a pre-built environment is kept by cloning it: save_fareground_setup without an id, with the settings the run used (a Market's also with people_of = that run's session, so it keeps its people). Do it when the person asks; after a run they are pleased with, offer it once. A run never saves.

A market can be played by the organisation's own customers: upload_customer_file reads their export (its shape, the role each column seems to play, which are personal and never read, each column's stats and first rows, notes, and any suggested reshape steps); when the reading is unsure (a required role missing, a note, a suggested step, an odd column), work out a reshape plan from the stats and rows, try it with preview_customer_file until it reads cleanly, and confirm the mapping and plan with the person; build_customer_population builds it with the same steps (optionally holdout_days for a backtest), and get_customer_population follows it until ready — then tell the person what it learned and what the file lacked, with what each gap leaves unknown. Run a Market on it with population.population_id (from the catalog's customer_populations, sampled by population.sample), or without their data by people generated from census data, whose buying the run observes. A customer population built with held-out days can be backtested: backtest: true, scenario baseline, horizon_days its held-out days, the products at the catalog's holdout_price. The report scores the run against what those customers actually bought and against the period before carried forward; without a backtest, a market's numbers are estimates under the setup's assumptions, and say so.

Participate: the person plays one seat

When the person wants to be in it — rehearse an interview or a negotiation, practise a pitch, see what happens if they act a certain way, or play — put them inside it instead of running it without them. Ask first for the material the real situation runs on (a job posting and resume, an offer's numbers, who the buyer is) and build from it, with a persona for every other character (entities.<id>.brief) and their seat under their own name; a played world is always built for them, never a ready-made one. enter_simulation starts it (billed per model reply); then narrate: pass the person's words to speak_in_simulation unchanged (or move with details for a move like an offer), show every line exactly as said, never speak for a character. rewind_simulation goes back to just before any of their moves so they can take it another way; restart_simulation plays it again. The result reveals what each character hid. guide("immersive") has the whole workflow.

Take a question through to an answer

When the person asked for a result and the contract and known-answer cases are ready, run a new study in one call with simulate_custom_environment(contract, request_id, cases, question, input_values, agent_bindings, n_runs, max_rounds, datasets, comparison, fit_patterns) and one UUID request_id. Read environment_authoring_guide() and the closest engine first, and write the rules, actions, information and outputs for the question. Configure occupants with agent_bindings: a model and instructions, or a declared policy. Supply CSV/JSON/JSONL data in datasets, keyed by declared input. Cases need independently worked-out expected outputs or series at the actual inputs and horizon; failed checks queue no runs. To compare conditions, pass comparison with labelled input variants and give each a known-answer case. guide("sdk") has the exact shapes.

The call returns a durable operation_id; follow get_custom_study or cancel with stop_custom_study before admission. A done operation holds the environment and session IDs; then use get_custom_run or wait_for_custom_run, never another study, to follow progress. Retry an uncertain call with the same UUID and identical arguments. Read outputs, diagnostics and the report before answering, and keep modeled outcomes apart from real-world claims.

Use the incremental tools below to inspect a saved environment, resolve actor IDs, diagnose failed checks or edit a design.

Build or repair a custom environment incrementally

The loop is write → check → save → preview → probe/verify → run → report. The installed SDK guide is the source of truth for the contract language; this skill only covers the platform around it.

1. Write. Read environment_authoring_guide() (part authoring: a worked contract, the loop and the core language). Part core maps every other part (cookbook, model, expressions, types, actions, events, inputs, patterns …); read focused parts as needed and use environment_contract_schema(path) for exact fields. Write the contract from the brief, or start from the closest engine: list_environment_engines, then get_environment_engine(engine_id) returns an executable starter to customize (a changed title alone is not customization). Every number the brief states becomes an input whose default is that number. Use sample_personas for a reproducible cohort; keep its provenance.
2. Participants. An agent type with a policy (from its policies) plays as coded participants: no model calls, suited to crowds and baselines. An agent type without one takes a model seat in paid runs. Decide which roles need judgment before running.
3. Check. check_environment_contract(contract, input_values) returns SDK issues, each with a path, message and fix. Fix every error and check again; a pass means the contract loads, not that its behavior or predictions are sound.
4. Save. create_custom_environment(contract, question, input_values, max_rounds) stores a private environment. Keep the returned id and revision.
5. Preview. preview_custom_environment(environment_id=id) resolves actual entity IDs and stages; pass an actor and stage to see exactly what that participant reads and which tools it gets. Do not guess generated IDs.
6. Probe and verify. probe_custom_environment runs a free random or scripted structural play. For known-answer tests, supply decisions=[{round, actor, stage, action, arguments, expect_ok?}] and expected_outputs or expected_series; every scripted decision must execute. Inspect checks, unexecuted_decisions, output_issues, budget, and error; ok=false is not a pass. verify_custom_environment(environment_id, expected_revision, cases) runs up to eight cases against one saved revision; include at least one known-answer case worked out from the brief. analyze_custom_environment samples allowed input boundaries for rule failures. None of these establishes real-world accuracy.
7. Edit. Call get_custom_environment for the current contract and revision. patch_custom_environment replaces selected top-level sections and preserves the rest; it is not a deep merge. update_custom_environment replaces the whole contract. Both require expected_revision and invalidate the prior probe. Re-preview and re-verify after edits.

Run and interpret

1. Run. Start it when the person says to, or asked you to run it. A paid run needs a passing probe or verification of the current revision with the exact inputs, through at least the requested number of rounds. Check get_balance and get_cost_estimates and choose a small first batch; estimates are not spending caps. Generate one UUID request_id, then call start_custom_run(environment_id, request_id, n_runs, max_rounds, input_values). Run i uses seed i. Save the returned session_id; on an uncertain start retry with the same request ID, because a new ID can start and bill another batch.
2. Report. wait_for_custom_run (bounded; a timeout does not cancel) or get_custom_run returns each run's outcomes, execution quality and, once all runs are finished, the report across completed seeds. Read large values with get_custom_run_data; view=full returns the complete batch. Use stop_custom_run to cancel and list_custom_runs to recover earlier session IDs. set_environment_metrics chooses which results the report shows. Failed or missing runs are limitations, not evidence. A run can take a while: report that it started and where to follow it rather than waiting it out, and never start another batch merely to check progress.
3. Explain the modeled rules, input values and provenance, run count, spread, failed runs, and calibration or reliability limits. Distinguish observed data from simulated outcomes. One run, a successful probe, or a valid contract does not prove predictive accuracy.

For existing scenario-format environments, inspect get_environment and its accepted inputs; use autofill_environment when grounding is available, then run_environment with a UUID request_id. use_llm=False is a free random-action structure check, not evidence. Poll get_run or wait_for_run, then read get_run_report and get_run_events as needed. See guide("environments") and guide("runs").

guide("sdk") covers custom environments in more depth. Some list responses use items, truncated, and next_cursor; pass next_cursor as cursor until the needed item is found. Read errors before retrying, and preserve an existing run's request ID.

Reuse request IDs with identical arguments on uncertain retries. Wait tools are bounded to 30 seconds. After edits, old verification cannot authorize the new revision; a random probe cannot erase a failed verification suite.

Generated from the agent kit at 6482b576.