Skip to main content

​
Operate governed computer-use agents from the console

A computer-use tool lets an agent drive a real web UI one guarded browser action at a time: navigate, click, type, screenshot. The API reference covers the endpoints; this guide covers the operating loop around them: decide the guardrails, prove them with a dry-run before going live, then observe and audit every run from the Computer use tab on the agent page in the Devotel Orbit console. The tab is the observe-and-audit surface for computer use. It lists every session the agent has driven, filters the list by outcome, and replays the ordered action trace of the session you select. Launching and steering a session is owned by the agent runtime; the console reads what happened, it does not drive the browser.

​
1. Configure a computer-use tool

Creating, updating, and deleting tools goes through the API today (POST /api/v1/agents/{agentId}/computer-use-tools); the console tab is where the tool’s runs are observed. Full request bodies live in the API reference. Four knobs are worth deciding deliberately, because they define what you will later audit in the tab: The sandbox_url and sandbox_secret fields point the tool at your own sandbox executor and are validated at write time; the console never shows the secret, only that one is set.

​
2. Validate guardrails with a dry-run before going live

Before you let an agent run the tool live, dry-run one representative proposed action per behavior you care about: one navigate per allowed domain, one action kind you put on require_confirmation, and one you put on blocked_actions. POST /api/v1/agents/{agentId}/computer-use-tools/{toolId}/dry-run with {"dispatch": false} returns the guardrail verdict without touching the sandbox; {"dispatch": true} (the default) also forwards the action once, marked as a test. The reference’s dry-run section has the full request and response shapes. Read decision on each dry-run and expect the verdicts you configured: allow for the in-list navigation, require_confirmation for the gated kind, deny with ACTION_BLOCKED for the blocked kind. Dry-runs never consume a step budget and are safe to run in CI. The console equivalent starts where the dry-run ends: the tab has no dry-run control of its own, because it renders live runs. Once the tool is enabled, watch the first real session in the tab and check that each step’s outcome matches what the dry-runs predicted. A mismatch between the dry-run verdict and the live trace means the tool configuration changed in between; re-read the tool over the API and diff the four knobs above.

​
3. Observe sessions in the Computer use tab

Open the agent page and select the Computer use tab. A filter row sits above the session list: All / Active / Completed / Failed. The filters map one-to-one onto the ?status= parameter of GET /api/v1/agents/{agentId}/computer-use/sessions (active covers runs still in flight), so what you filter in the tab you can also pull over the API. Each row in the list is one session and shows:
  • Goal — the task the agent was working, as supplied at launch.
  • Status — Running or Needs input while in flight; Completed, Failed, or Cancelled once terminal.
  • Steps — how many browser actions the run took, and errors — how many of them failed, shown only when nonzero.
  • Duration — first step to last step; for a running session the value ticks up live.
Select a row to open the detail panel: Steps, Errors, Duration, and Model stats, the start time rendered in your timezone, the last URL the browser landed on, the run’s result summary when the agent wrote one, and the ordered action trace below.

​
4. Replay the per-step audit trail

The trace is the run reconstructed step by step. Each row carries the step number, the action kind (Navigate, Click, Type, Key, Scroll, Screenshot, Extract, Wait, Finish), a success or failure marker, the action’s description and target (a URL for Navigate), and, when the step failed, the error string returned by the sandbox. Steps that captured a screenshot link it inline, so you can see the page exactly as the agent saw it. The trace in the tab is the same record GET /api/v1/agents/{agentId}/computer-use/sessions/{sessionId} returns: each step’s action, guardrail decision, sandbox status, and duration. What you can read in the tab you can export over the API into your own audit pipeline, and the per-step records survive restarts, so a run is always reconstructable after the fact.

​
5. When to require human confirmation, and what read-only means

Put an action kind on require_confirmation when the action is hard to reverse or leaves the scope you can fully audit: submitting a form, confirming a payment, deleting a record. The guardrail then answers require_confirmation for that kind and the step waits for an explicit confirmed flag before it dispatches; nothing happens on the operator’s silence. Keep the list short. Every gated kind is a step that cannot complete unattended, so gate the kinds that are genuinely consequential and let the rest run inside the domain and step-budget containment. Read-only here means the console never launches, steers, or stops a session; that is the agent runtime’s job. The tab observes and audits. The controls that govern a run — allowed domains, blocked actions, confirmation gates, step budget — are yours, set per tool on the agent; the platform enforces them structurally on every step, capped loop, re-pinned sandbox URL, and a written audit record whether the step was allowed, denied, or gated.

​
6. Failure triage

Start with the Failed filter. Open the session and read top down: the Errors stat, the ” of steps failed” note above the trace, then the failed rows, each carrying its sandbox error string. Two failure shapes are worth distinguishing:
  • Sandbox failures — the guardrail allowed the step and the sandbox rejected or errored it. The row shows the error; retrying means fixing your executor, not the tool configuration.
  • Guardrail denies — the step never reached the sandbox. The trace shows the deny (ACTION_BLOCKED, DOMAIN_NOT_ALLOWED, STEP_BUDGET_EXHAUSTED); these surface in the trace, not as HTTP errors. They mean the configuration did its job, or that the agent’s goal needs domains or actions you have not allowed.
Configuration-time failures are a third shape: a create or update whose sandbox_url misses safety validation returns a 422 INVALID_SANDBOX_URL envelope that names the reason. See Failure envelopes in the API reference for the body, and Troubleshooting agent errors for the wider agent failure classes — budget caps, provider errors, run-level faults.