How-to guides

Give the agent a goal

Where: New goal

1. Open New goal and pick the application and the environment (which instance) it should work in. The note under it shows the address and login it will use.
2. Choose the mode. Only a disposable environment allows Supervised or Autonomous; everywhere else the run is Read only.
3. Describe what you want in plain words — for example “Acknowledge the open alert for checkout latency” — and press Start run.
4. If the goal is unclear, the agent asks under “Before I act, please clarify”. Answer each question and press Answer and continue.
5. When planning finishes the run starts and its run page opens. It is also listed under Runs.

Review and adjust a goal’s plan

Where: Plan editor — open /goals/<goal id>/plan; it isn’t linked from the console yet

1. Find the goal’s id in the Goal column of Runs, and open /goals/<goal id>/plan.
2. Go through the tasks in order: each shows its risk level, its skill and the checks that decide when it is done.
3. Reorder with ↑ and ↓, rewrite what a task should do in its text box, or Remove one that is wrong.
4. Press Save draft, or Approve & save to approve it. Each save is a new version of the plan.

💡 New goal starts the run as soon as planning finishes, so an edited plan is for runs started afterwards; a run already going keeps the plan it started with.

Watch a run

Where: Runs → a run

1. Open Runs and pick the run. Its state says whether it is running, waiting for you, succeeded, failed or cancelled.
2. The stage banner says what it is doing now; for a failed run it gives the likely cause. The page updates as the run works.
3. Answer shows the result and the screen it was read from, Timestamp the activity log, and Steps each action with its screenshot and reason.
4. When it finishes, watch its playback, or open Trace explorer & report export for every observation and a downloadable report.

💡 The console doesn’t show a live view of the screen yet: follow the step screenshots, which appear as the agent works.

Step in while it works

Where: Run detail and Approvals

1. Send a hint — type in Send a hint… on the run page; the agent uses it in its next decision (only while the run is running).
2. Approve or reject — high-risk actions wait in Approvals and on the run’s own page. Rejecting blocks only that agent’s work; the rest carries on.
3. Cancel — Cancel run in the run page’s header asks you to confirm. (Stop in its status bar cancels without asking.)
4. Pause and resume (API only for now): POST /v1/executions/{id}/pause and /resume.
5. Take over (API only for now): POST /v1/agent-runs/{id}/takeover pauses the agent after its current action so you can drive the screen yourself; your input is recorded like any other action.

💡 A run sitting BLOCKED usually means an approval is waiting, or one was rejected.

Point an environment at a real instance

Where: Environments

1. Open Environments and pick an environment of your application.
2. Set its address and the login the agent should use. The password is stored encrypted and never shown again.
3. Use a disposable environment when the agent must change data. A shared one is read-only to the agent: writes are refused and logged.
4. For a disposable environment, snapshot it once it is in a good state, and reset it to that snapshot between runs.

Review what the agent knows about an application

Where: Brief review — open /apps/<application id>/brief; it isn’t linked from the sidebar yet

1. Each application has a brief: a description of what it is, its screens and how it is used. The agent plans from it.
2. Press Generate draft: a large vision model drafts the brief from the application’s screens.
3. Read and edit the draft, then press Approve & commit. Only an approved brief becomes trusted context for the agent.
4. On the same page, accept or reject selector-healing proposals: suggested fixes for how the agent finds a control whose screen changed.

Choose which models do which job

Where: Configurator

1. Open Configurator (admins can change it).
2. Under Vision language models, choose a model for Planning (interprets the goal and plans), Executor (decides each step) and Escalation (takes over hard steps, recovery and loops).
3. Under Embedding models, choose the Primary and Fallback models used to search application knowledge.
4. To add a model from Hugging Face, add it by name; it downloads on its server and can be chosen once installed.
5. Press Save. New plans and runs use the new models; runs already going keep theirs.

💡 Prefer the -instruct vision models: the thinking ones can spend minutes on a single step.

Test the agent on a benchmark

Where: Benchmarks and Evaluations

1. Open Benchmarks to see the test cases for each application; create, copy or edit them.
2. Start an evaluation from Evaluations (or a benchmark’s Run evaluation) and choose where it runs: a real instance (an environment with an address and login) or the mock site.
3. On a real instance it checks the instance is healthy and the login works before starting, and before every case.
4. Read the results: what passed, what failed and why. Promote a confirmed failure into the regression suite so it is checked every time.

💡 On a shared instance, cases that would change data are skipped and listed — the evaluation stays read-only.

Compare models before choosing one

Where: Configurator and Documents

1. On the Configurator, pick the model for a role — don’t save yet. If it has been measured, a note appears under the role with a table comparing it with the current executor, what the numbers say and a recommendation.
2. Follow Open the report, raw results and scripts to read the full report on the Documents page.
3. Open a raw JSON report there to check a number: every calibration answer, and each task’s steps, tokens, step times and failure reason.
4. Save the model, or press Undo changes to keep what you had.
5. A model with no results yet has no note. Thalamus publishes new measurements with ThalamusCUA; see New measurements.

💡 Results hold for the hardware they were measured on, which each report names.

Send the agent work from code

Where: API, Python SDK, CLI or triggers

1. From Python: Client(...).login(...), then create_goal, start_execution and wait_execution.
2. From a shell: cua-sdk submit and cua-sdk wait.
3. From another agent or workflow engine: POST /v1/triggers with a service token and an optional webhook for when it finishes.
4. Details in Developers.