How Ancha works - Ancha

Ancha runs your agent against replicas of the tools it uses, many times, from the same starting point.

Objects

Object	What it is
Agent	Your code, how it starts (a command or an HTTP endpoint) and the model provider it uses.
Tool	A stateful replica of a service such as Slack or GitHub. It answers the real API’s endpoints with realistic IDs, and its state changes as the agent acts. CLI output calls a tool a twin.
World	A set of tools with starter data: channels and messages, repositories and issues, monitors, incidents, contacts and deals. See Worlds.
Test	A world plus tasks and how many times to try each one, saved so it runs again against new agent code. See Tests.
Run	One execution of a test.
Attempt	One independent try at one task, on its own fresh copy of the world. See Attempts and runs.
Check	A condition on the final world state or on the agent’s API calls that decides whether an attempt passed. See Checks.

What happens in a run

Ancha creates a fresh copy of the world for each attempt, from the same seed.
It starts your agent with the task and the tool addresses and fake credentials in environment variables.
The agent calls the tools. Every call is recorded, and tool state changes as it would in the real service.
When the agent exits or times out, Ancha captures the final state and the call trace.
Checks run against what was captured. The attempt passes when every required check passes.

Two vocabularies

The hosted console and the CLI’s playground commands use agents, worlds, tests, runs and attempts. ancha run is file-based and uses scenes and trials. They describe the same ideas:

Idea	Hosted console and `ancha playground`	`ancha run`
World	A saved, versioned world	`twins`, `seed` and `world_rules` in a scene file
Task	A task on a test	`task` in a scene file
Checks	A JSON list on each task	`checks` in a scene file
Test	A saved test	`ancha.yaml` plus the scene files it lists
Attempt	Attempt	Trial
Live copy of a world	Playground	Environment (`envId`)

Determinism

The same world and seed always produce the same starting data, including record IDs. Tools run on a simulated clock that starts at a fixed time, so timestamps and time-based behavior repeat across attempts. A difference between two attempts comes from your agent.

Where results live

You run	Results are stored in
`ancha run`	`.ancha/runs/` in your project. See Attempts and runs.
`ancha playground`	`.ancha/playgrounds/` in your project.
Runs in the hosted console	Your hosted workspace’s disk.