Structured output

Pass a JSON Schema and read the V4 result as parsed JSON.

Pass a JSON Schema as output_schema / outputSchema. When the run completes, run.output holds the parsed JSON value and run.result still holds the text answer.

SDK support for output_schema / outputSchema and run.output ships in the first browser-use-sdk release after 3.11.3. On 3.11.3, use the REST API.

Python

from browser_use_sdk.v4 import BrowserUse
from pydantic import BaseModel

client = BrowserUse()

class Story(BaseModel):
    title: str
    points: int

run = client.runs.create(
    "Find the top Hacker News story and its points.",
    output_schema=Story.model_json_schema(),
)
run = client.runs.wait_for_completion(run.id)
if run.status.value != "completed":
    raise RuntimeError(run.error or run.status.value)
story = Story.model_validate(run.output)

Browser Use checks the agent’s final answer against the schema. If the agent cannot produce a matching answer, the run fails with Could not produce output matching outputSchema. Validate run.output in your application as well, as the examples do.

Limits

• API-key runs only. Runs started from the dashboard return 422.
• JSON Schema 2020-12 unless the schema sets another $schema.
• At most 64 KiB, 64 nesting levels, and about 4,000 values (every key’s value and array item counts).
• $ref must point inside the schema (#/...).