Quickstart

The first environment is offsite-planning: a 14-person company in Oslo with a mailbox, Slack and calendars. Its task is “Schedule the Q4 offsite”. The examples below were recorded against the engine. Long answers are cut with ....

Create a run

curl -s -X POST $TESTWORLD_URL/v1/runs \
  -H "Authorization: Bearer $TESTWORLD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"environment":"offsite-planning","task":"Schedule the Q4 offsite","idempotency_key":"quickstart-1"}'

{
  "id": "run_5296fdfe-b495-4c5b-8e30-8f767d4c47dc",
  "status": "created",
  "tools_url": "$TESTWORLD_URL/v1/runs/run_5296fdfe-.../tools",
  "mcp_url": "$TESTWORLD_URL/v1/runs/run_5296fdfe-.../tools/mcp",
  "token": "tw_run_6cdb03085eae616dbb91402d469952ef",
  "calls": 0,
  "...": "..."
}

Keep id, tools_url and token. The task title selects the task and its five checks.

Point the agent at tools_url

The agent calls Gmail, Slack and Calendar under tools_url, on the real APIs’ shape, with the run token as its bearer token.

curl -s "$TOOLS_URL/gmail.googleapis.com/gmail/v1/users/me/messages?q=offsite" \
  -H "Authorization: Bearer $RUN_TOKEN"

An MCP client connects to mcp_url instead. See Tools.

Finish the run

curl -s -X POST $TESTWORLD_URL/v1/runs/$RUN_ID/finish \
  -H "Authorization: Bearer $TESTWORLD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"output":"Booked Friday 13 November and told #leadership and #general."}'

The answer has "status": "evaluating". A run you never finish ends after 10 minutes without a call and is scored the same.

Read the result

curl -s $TESTWORLD_URL/v1/runs/$RUN_ID -H "Authorization: Bearer $TESTWORLD_KEY"

Poll until status is done. The run then holds the trace and the evaluation:

{
  "status": "done",
  "ended_by": "finish",
  "calls": 10,
  "trace": { "calls": ["..."] },
  "evaluation": { "score": 1, "passed": true, "checks": ["..."] }
}

Get started

Concepts

More