Build an environment

Write each test case as one sentence, let the platform turn it into a simulated person, add checks, and save the result.

Endpoints

All paths start with /api/v1/diagnostics and need X-Space-Slug.

• An export carries the cases and the checks, not the documents: attach the files again after an import.
• A clone keeps the checks and documents.
• A clone keeps the simulated people only for the same agent or one promoted from it; otherwise PATCH its dataset.

Scenario request fields

Without cases, conversation_ids or a window, scenarios are written from the agent's configuration alone.

Scenario fields

A scenario can also be written by hand, with no billed call, and saved directly as a simulated_user.

Build and save an environment

1. Upload each document a case needs with POST /api/v1/agents-v2/files/upload/ (Attach files); its id is the file_id.

2. Draft the simulated people:

   curl -X POST "$CENTRAL_HUB_URL/api/v1/diagnostics/agents/42/suggest-scenarios/" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -H "Content-Type: application/json" \
     -d '{
       "cases": [{"id": "deadline", "description": "A bid manager wants the exact deadline of the tender.", "file_ids": ["<file id>"]}],
       "bucket": [{"file_id": "<file id>", "description": "The tender rules, 28 pages"}],
       "diagnostic_effort": "low"
     }'

   The response is {scenarios, abstained, note, …}. Each scenario holds id, persona, goal, opening and the facts the platform filled in. abstained: true means nothing could be built from what was sent; note says why.

3. Pick checks: from GET /check-catalog/, from POST /agents/42/suggest-checks/ with {"diagnostic_effort": "low"} (the response is {assertions, abstained, note}), or write them. A check is {id, type, label, description, params}; a check in your own words is "type": "llm_judge" with "params": {"prompt": "PASS if … FAIL if …"}.

4. Save the environment. Each dataset row wraps one scenario from step 2, unchanged, as simulated_user:

   curl -X POST "$CENTRAL_HUB_URL/api/v1/diagnostics/kits/" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Tender questions",
       "agent_id": 42,
       "dataset": [{"simulated_user": {"id": "deadline", "persona": "A bid manager at a construction firm", "context": "Preparing a bid for a public tender", "goal": "Learn the exact submission deadline", "opening": "When is the deadline for this tender?"}}],
       "file_bucket": [{"file_id": "<file id>", "description": "The tender rules, 28 pages"}],
       "assertions": [{"id": "cites-deadline", "type": "llm_judge", "label": "Cites the deadline", "description": "", "params": {"prompt": "PASS if the answer gives the deadline stated in the tender rules. FAIL otherwise."}}]
     }'

   The response holds the environment's id, used as kit_id by the gym and diagnoses.

Troubleshooting