Skip to main content

Structured Data

Browser task requests accept output_schema to guide JSON output. For example:

{
  "prompt": "Go to https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html and return the book title and price as JSON",
  "wait": 300,
  "output_schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "price": {
        "type": "string"
      }
    },
    "required": [
      "name",
      "price"
    ],
    "additionalProperties": false
  }
}

output_schema should be a JSON Schema definition.

This field is supported on legacy browser task creation and pending-task updates: /api/v1/tasks/browser-use/ and /api/v1/agents/browser-use/{agentId}/tasks/. It is not a generic field on Agent creation, REST messages, or MCP messages. Use a string prompt and send the object above as the task request body.

The server checks the schema against JSON Schema Draft 2020-12 and rejects schemas deeper than 40 traversal levels or with more than 2,000 counted object keys. An invalid schema returns a 400 field error before task execution. null removes schema guidance on a pending task.

Schema-guided generation does not guarantee successful execution or a non-null result. Browser/model failures can still produce a failed task; a completed task can have no stored result. Read /result/, check status, and validate the returned result against your application's expected schema before storing it. The field can hold a native JSON object, array, scalar, or null; do not unconditionally parse it again as a JSON string.

Persistent application results​

A separately gated application request can include result_schema:

{
  "body": "What is 17 plus 25?",
  "result_schema": {"type": "integer"}
}

Submit this body to POST /api/v1/agents/{agent_id}/requests/ with your API credential and Idempotency-Key. New typed requests require both API_APPLICATION_REQUESTS_ENABLED and API_STRUCTURED_RESULTS_ENABLED (default false). Disabled typed admission returns 503 structured_results_disabled; existing accepted requests, replay and reads remain supported. Validate the feature against your deployment and live model before enabling it.

application-result-v1 is a restricted JSON Schema Draft 2020-12 profile. Every schema node requires one string type: object, array, string, number, integer, boolean or null. Supported keywords are $schema (only https://json-schema.org/draft/2020-12/schema), properties, required, boolean additionalProperties, items (required on arrays), enum, const, minLength, maxLength, minItems, maxItems, minProperties, maxProperties, minimum, maximum, exclusiveMinimum, and exclusiveMaximum. Type-specific constraints must match their node's type. References, regex, formats, type unions, combinators and annotations are rejected; the server does not fetch schemas or silently normalize them.

Canonical UTF-8 schemas are limited to 16 KiB, eight traversal levels and 256 JSON nodes (including object keys). Native result values are limited to 64 KiB, sixteen levels and 4096 nodes. Non-finite numbers, integers above 1024 bits, invalid UTF-8 and non-JSON values are rejected. Canonical SHA-256 and profile identify the accepted contract; changing it under the same live retry key conflicts.

Follow request detail or revision waits, then GET /api/v1/agents/{agent_id}/requests/{request_id}/result/. For a validated integer, its response includes:

{
  "availability": "available",
  "has_value": true,
  "value": 42,
  "result": {
    "state": "validated",
    "error_code": "",
    "profile": "application-result-v1",
    "schema_hash": "opaque SHA-256",
    "artifact_id": "opaque UUID",
    "version": 1,
    "checksum_sha256": "opaque SHA-256",
    "size_bytes": 2
  }
}

Objects, arrays, scalars and null are native JSON. An available null has has_value: true, value: null; absence omits value and has has_value: false. Do not JSON-decode value a second time. availability distinguishes available, unavailable and purged.

Request metadata's result.state is independent of execution and chat response state: not_requested, pending, validated, validation_failed, generation_failed, no_result, or purged. Waiting/approval/input-security states remain authoritative. validation_failed means a candidate was rejected; generation_failed with generation_not_completed includes interrupted/unknown generation and is not proof of external failure. no_result means an eligible turn settled without a typed value. A valid shape is not evidence that a payment, message or other external task succeeded.

The runtime receives the contract with original source-message references matching trusted request/message labels in its input and uses an additive result tool; normal user prompts need no formatting protocol. The model supplies the selected request ID and native result value. Before inference the runtime pins the advertised immutable schema hash and supplies it to server validation, so the model does not have to copy that metadata. Current scope, generation, retention, exact hash pairing and value checks still apply. Public request/result hash metadata is unchanged; upgrade and drain runtime workers before validating this behavior. At most sixteen contracts and two formatting submissions per request are supported per turn. It does not automatically replay tools or perform separate repair inference. A candidate publishes only on current, explicitly consumed input lineage after eligible settlement without pending decisions/continuations. Chat replies cannot substitute for it. Each request has at most one immutable version-1 artifact; artifacts are not shared across requests.

Result/schema content is encrypted at rest and shares original-request privacy/retention. Either content or artifact purge erases result bytes; content purge also erases schema bytes. Retrieval rechecks current principal, scopes, resource grants and original owner, with the same explicit audited human inspection option as request detail. Transfers do not transfer historical access. Responses use private/no-store caching. Automatic request events carry safe result metadata only; retrieve content through this authorized route. Result bytes do not enter filespace or public artifact URLs. Agents still share model context; use separate agents/workspaces for independent context.

Last updated on