> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Computer Use Skill

> Skill file for agents delegating tasks to the StateSet Computer Use Agent — preview, trigger, wait, read the result — over the hosted API or its MCP server.

Use this when an agent needs to run a computer-use task — software operated through its screen —
through the hosted API or the `stateset-computer-use` MCP server: previewing, triggering, polling,
retrieving results, using idempotency keys, or working with `agent_type` templates.

## Environment

* API base: `https://api.computer.stateset.app/api/v1`
* Auth header on every call: `X-API-Key: $STATESET_CUA_API_KEY`
* Never put an API key in a prompt, file, example, log or commit.

## Preferred workflow

1. Discover allowed task types with `GET /templates`, or MCP `stateset_cua_list_templates`.
2. Preview any non-trivial task with `POST /jobs/preview`, or MCP `stateset_cua_preview_task`.
3. Trigger with `POST /trigger`, or MCP `stateset_cua_trigger_task`.
4. Send an `Idempotency-Key` on every trigger. Use a stable key for the same logical task, so a
   retry after a timeout does not run it twice.
5. For a simple client, `POST /jobs/{job_id}/wait` with `{"timeout_seconds": 30}`. For a
   long-running task, poll `GET /jobs/{job_id}` or consume SSE until `status` is `succeeded`,
   `failed` or `cancelled`.
6. Fetch `GET /jobs/{job_id}/result` for the summary and artifact pointers.

## Trigger payload

Minimum:

```json theme={null}
{
  "agent_type": "general",
  "instruction": "Open https://example.com and report the page title.",
  "params": {}
}
```

Useful optional fields:

* `model` — `haiku`, `sonnet`, `opus`, or a canonical model id
* `effort` — `low`, `medium` or `high`
* `max_cost_usd` — a per-job budget ceiling
* `tags` — up to 20 labels, e.g. `["tenant:acme", "flow:approval"]`
* `output_schema` — a JSON Schema the final answer is validated against, caller-side
* `webhook_url` and `webhook_secret` — a one-shot completion callback

## MCP tools

When the `stateset-computer-use` MCP server is available, prefer its tools over raw HTTP:

`stateset_cua_preview_task` · `stateset_cua_trigger_task` · `stateset_cua_trigger_batch` ·
`stateset_cua_get_job` · `stateset_cua_wait_for_result` · `stateset_cua_get_result` ·
`stateset_cua_list_jobs` · `stateset_cua_list_templates` · `stateset_cua_get_template`

## curl

```bash theme={null}
# trigger
curl https://api.computer.stateset.app/api/v1/trigger \
  -H "X-API-Key: $STATESET_CUA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: acme-product-review-001" \
  -d '{
    "agent_type": "general",
    "instruction": "Review the product queue and approve products with valid title, category, color and size mappings.",
    "params": { "max_messages": 12 },
    "tags": ["tenant:acme", "flow:product-approval"]
  }'

# poll
curl https://api.computer.stateset.app/api/v1/jobs/JOB_ID -H "X-API-Key: $STATESET_CUA_API_KEY"

# wait
curl -X POST https://api.computer.stateset.app/api/v1/jobs/JOB_ID/wait \
  -H "X-API-Key: $STATESET_CUA_API_KEY" -H "Content-Type: application/json" \
  -d '{"timeout_seconds": 30}'

# result
curl https://api.computer.stateset.app/api/v1/jobs/JOB_ID/result -H "X-API-Key: $STATESET_CUA_API_KEY"
```

## Safety

* Set `max_cost_usd` on exploratory or large tasks.
* Preview before any batch submission.
* Never retry without an idempotency key.
* Treat artifact storage keys as pointers; use the dashboard or the authenticated artifact
  download endpoints to read them.

## Further reading

* [Computer Use API reference](/api-reference/computer-use/overview) — all 90 v1 endpoints
* [Computer Use MCP servers](/computer-use-mcp) — hosted and local
* [Computer Use Agent](/computer-use-agent) — how a job executes