​

Computer-Use Browser Tools

​

1. What a computer-use tool is

• Custom tools — named HTTP endpoints you register once and reference from any agent.
• MCP tools — capabilities exposed by an external MCP server.
• A2A — skills another agent exposes through the A2A federation surface.
• Computer-use tools — a bounded browser-operating loop that drives a web UI step by step.

• Bounded step budget — max_steps caps the loop (1–50, default 20). A run that exhausts its budget is forced to stop.
• SSRF-pinned sandbox — the sandbox_url is validated at write time and re-pinned at every dispatch, so a tool can never be pointed at internal infrastructure.
• Envelope-encrypted sandbox secret — sandbox_secret is stored envelope-encrypted and never returned by any read. Responses expose only a sandbox_secret_set flag.
• Audit trail — every proposed action is recorded, whether it was allowed, denied, or gated on confirmation. A run can always be reconstructed later.

​

2. Create a computer-use tool

curl -X POST https://api.orbit.devotel.io/api/v1/agents/agt_7e3b9c1f/computer-use-tools \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "billing_portal",
    "description": "Drive the internal billing portal to look up and export invoices.",
    "sandbox_url": "https://sandbox.example.com/browser/run",
    "sandbox_secret": "your-sandbox-signing-secret",
    "max_steps": 25,
    "allowed_domains": ["billing.example.com"],
    "blocked_actions": ["type"],
    "require_confirmation": ["navigate"]
  }'

const res = await fetch(
  `https://api.orbit.devotel.io/api/v1/agents/${agentId}/computer-use-tools`,
  {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.ORBIT_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'billing_portal',
      description: 'Drive the internal billing portal to look up and export invoices.',
      sandbox_url: 'https://sandbox.example.com/browser/run',
      sandbox_secret: 'your-sandbox-signing-secret',
      max_steps: 25,
      allowed_domains: ['billing.example.com'],
      blocked_actions: ['type'],
      require_confirmation: ['navigate'],
    }),
  },
);
const { data } = await res.json();
console.log(data.tool.id);

​

3. Validate guardrails with a dry-run

curl -X POST https://api.orbit.devotel.io/api/v1/agents/agt_7e3b9c1f/computer-use-tools/tool_abc123/dry-run \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": { "kind": "navigate", "url": "https://billing.example.com/invoices" },
    "confirmed": true,
    "dispatch": true
  }'

• decision — allow, deny, or require_confirmation.
• code — a machine-readable guardrail code on a non-allow verdict (see §5), and done: true from a live run when the step budget is exhausted.
• result — the sandbox round-trip: HTTP status, duration, response body, and the error string when the sandbox rejected the action.

​

4. Audit every run

• GET /api/v1/agents/{agentId}/computer-use/sessions — one row per run: status, first/last step timing, step count, and the operator-supplied task. Filter with ?status=all|active|completed|failed (default all) and ?limit=1–100 (default 25).
• GET /api/v1/agents/{agentId}/computer-use/sessions/{sessionId} — one run’s full ordered action trace: each step’s action kind, guardrail decision, sandbox status, and duration.

curl "https://api.orbit.devotel.io/api/v1/agents/agt_7e3b9c1f/computer-use/sessions?status=completed&limit=10" \
  -H "X-API-Key: dv_live_sk_..."

​

5. Guardrail rules and runtime containment

​

6. Where it fits with other tool kinds

• Reach for a custom tool when the target system has an HTTP endpoint you can call.
• Reach for MCP / A2A when the capability is already exposed by a service or another agent.
• Reach for computer-use when the only interface is a rendered page — and accept the higher per-step cost in exchange for the closed action set, step budget, and full audit trail.