Yutori Python SDK & CLI

The official Python SDK and CLI for the Yutori API — build agents that monitor, research, and browse the web, and operate computers with Yutori.

The SDK offers sync and async clients with full type annotations, plus a yutori CLI for authentication and managing resources from the terminal.

AI agent install (recommended)

Paste this into Claude Code, Codex, Cursor, Windsurf, or another coding agent:

Use https://yutori.com/api/llms.txt and set up Yutori for me.

Manual install

On macOS or Linux, the recommended setup is the one-line installer:

curl -fsSL https://yutori.com/install.sh | bash

Installs the global yutori CLI via uv tool install and prompts to add the SDK to your project, run yutori auth login, register the MCP server, install workflow skills, and verify with a browsing task.

Python 3.9+ is required for the SDK.

curl -fsSL https://yutori.com/uninstall.sh | bash

pip install yutori

uv add yutori

yutori auth login

from yutori import YutoriClient

client = YutoriClient()                  # Uses saved credentials or YUTORI_API_KEY
client = YutoriClient(api_key="yt-...")  # Or pass explicitly

npx add-mcp "uvx yutori-mcp"
npx skills add yutori-ai/yutori-mcp -g

API Overview

The Yutori API provides four main capabilities:

Navigator API

The Navigator API serves Yutori's models: Navigator n1.5 operates a webpage in a browser and Navigator n2 operates a complete desktop. Both take a task and a screenshot and return the next actions as tool_calls; your code executes them, sends the results back, and calls the model again until it indicates stop. The endpoint follows the OpenAI Chat Completions interface, so client.chat is a drop-in OpenAI-compatible client.

Navigator n1.5 (browser use)

Capture a screenshot of the page and send it with the task:

from yutori import AsyncYutoriClient
from yutori.navigator import aplaywright_screenshot_to_data_url
from playwright.async_api import async_playwright

async with AsyncYutoriClient() as client, async_playwright() as p:
    browser = await p.chromium.launch()
    page = await browser.new_page()
    await page.goto("https://www.yutori.com")

    image_url = await aplaywright_screenshot_to_data_url(page)

    response = await client.chat.completions.create(
        messages=[
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": "List the team member names."},
                    {"type": "image_url", "image_url": {"url": image_url}},
                ],
            }
        ],
    )

    message = response.choices[0].message
    print(message.content)  # Model's thoughts
    for tool_call in message.tool_calls or []:
        # Execute the requested browser action on `page`, append the tool
        # result to the conversation, capture a fresh screenshot, and call
        # the model again...
        ...

This snippet shows a single model call. In practice, you'll run an agent loop: execute the returned actions on the page, capture a fresh screenshot, and call the model again until it returns text with no tool_calls. Complete agent loops live in examples/.

The SDK defaults to Navigator n1.5 (n1.5-latest). Navigator n1.5 requests support selectable tool sets, disable_tools, and structured JSON output via json_schema (returned as response.parsed_json). See the Navigator reference for model IDs, parameters, and the full action space.

Navigator n2 (computer use)

Navigator n2 operates a full desktop. It answers with computer_batch calls — an ordered sequence of GUI actions, answered with one screenshot taken after the last one — and bash calls, answered with the command's output. Use model="n2" and pin the tool set:

from yutori import AsyncYutoriClient
from yutori.navigator import TOOL_SET_COMPUTER_USE_LATEST, screenshot_to_data_url

async with AsyncYutoriClient() as client:
    # A full-screen capture, kept at the display's own size (the default resize_to is a browser viewport).
    image_url = screenshot_to_data_url(screenshot_bytes, resize_to=(screen_width, screen_height))

    response = await client.chat.completions.create(
        model="n2",
        tool_set=TOOL_SET_COMPUTER_USE_LATEST,
        messages=[
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": "Open Calculator and compute 17 * 23."},
                    {"type": "image_url", "image_url": {"url": image_url}},
                ],
            }
        ],
    )

    message = response.choices[0].message
    print(message.content)  # Model's thoughts
    for tool_call in message.tool_calls or []:
        # Run the batch's actions in order on the desktop (or run the bash
        # command), append one tool result per call, and call the model again...
        ...

N2ComputerAgent runs this loop for you against any desktop you can screenshot and drive. examples/navigator_n2_daytona.py is a complete agent on a sandbox Daytona Linux desktop, with everything Daytona-specific in one small adapter class; Building agents with n2 walks through it.

uvx yutori-mcp computer-use setup
uvx yutori-mcp computer-use run "In Calculator, compute 17 * 23 and report the result." --app Calculator

See the Navigator n2 reference for the tools, actions, coordinate system, and request fields.

The SDK also accepts the immutable computer_use_tools-20260818 browser set for replay. It is not a desktop set: its extra goto_url call requires a computer handler that implements async goto_url(url: str). The bundled desktop and public Cua sandbox adapters deliberately return a recoverable unsupported-environment result for that browser-only call.

Agent-loop helpers

The yutori.navigator subpackage exposes optional helpers for typical agent loops:

Full helper reference: api.md.

If you'd rather not manage browser infrastructure, use the Browsing API below, which runs the Navigator on Yutori's cloud browser.

Browsing API

Run one-time browser automation tasks on Yutori's cloud browser (or on Yutori Local with the user's logged-in desktop sessions):

task = client.browsing.create(
    task="Give me a list of all employees (names and titles) of Yutori.",
    start_url="https://yutori.com",
)

# Poll for completion
import time
while True:
    result = client.browsing.get(task["task_id"])
    if result["status"] in ("succeeded", "failed"):
        break
    time.sleep(5)

print(result)

Common options: require_auth=True for login flows, browser="local" for Yutori Local, webhook_url=... for async completion notifications. Failed tasks may include a rejection_reason.

client.browsing.list() enumerates your browsing tasks — omit limit to get them all, or pass status (running/succeeded/failed) and cursor to filter and paginate.

Structured output

Define the output structure with a JSON Schema dict or a Pydantic model:

from pydantic import BaseModel  # optional dependency

class Employee(BaseModel):
    name: str
    title: str

task = client.browsing.create(
    task="Give me a list of all employees (names and titles) of Yutori.",
    start_url="https://yutori.com",
    output_schema=Employee,  # Auto-converted to JSON Schema
    webhook_url="https://example.com/webhook",
)

The same output_schema pattern applies to client.research.create and client.scouts.create.

Research API

Perform deep web research using 100+ MCP tools (search engines, APIs, data sources):

task = client.research.create(
    query="What are the latest developments in quantum computing from the past week?",
    user_timezone="America/Los_Angeles",
)

# Poll for results
while True:
    result = client.research.get(task["task_id"])
    if result["status"] in ("succeeded", "failed"):
        break
    time.sleep(5)

Failed tasks may include a rejection_reason.

client.research.list() enumerates your research tasks — handy for exporting or recovering task IDs from a large batch. Omit limit to get them all, or pass status / cursor to filter and paginate:

completed = client.research.list(status="succeeded")
for t in completed["tasks"]:
    print(t["task_id"], t["created_at"])

Scouting API

Scouts run on a schedule to monitor the web and notify you when relevant updates occur:

scout = client.scouts.create(
    query="News, product updates, and announcements about Yutori AI",
    output_interval=86400,  # Daily (seconds, min 1800)
    webhook_url="https://example.com/webhook",
)

# Manage scouts
scouts = client.scouts.list(status="active")
client.scouts.update(scout["id"], status="paused")
client.scouts.update(scout["id"], status="active")
updates = client.scouts.get_updates(scout["id"], limit=20)
client.scouts.delete(scout["id"])

Async Usage

AsyncYutoriClient mirrors YutoriClient with async methods:

import asyncio
from yutori import AsyncYutoriClient

async def main():
    async with AsyncYutoriClient() as client:
        usage = await client.get_usage()
        scouts = await client.scouts.list()
        print(usage, scouts)

asyncio.run(main())

Error Handling

from yutori import YutoriClient, APIError, APIConnectionError, AuthenticationError

try:
    client.get_usage()
except AuthenticationError as e:
    print(f"Invalid API key: {e}")
except APIConnectionError as e:
    print(f"Connection failed: {e}")
except APIError as e:
    print(f"API error (status {e.status_code}): {e.message}")

CLI

# Authentication
yutori auth login      # Log in via browser
yutori auth status     # Show current auth status
yutori auth logout     # Remove saved credentials

# Scouts
yutori scouts list
yutori scouts create -q "monitor for news"
yutori scouts create -q "monitor for news" -i daily -tz America/New_York
yutori scouts get SCOUT_ID
yutori scouts delete SCOUT_ID

# Browsing
yutori browse list
yutori browse list --limit 20 --status succeeded
yutori browse run "extract all prices" https://example.com/products
yutori browse run "log in and continue" https://example.com/login --require-auth
yutori browse run "export dashboard data" https://example.com/dashboard --browser local
yutori browse get TASK_ID

# Research
yutori research list
yutori research list --limit 10 --status running
yutori research run "latest developments in quantum computing" -tz America/Los_Angeles
yutori research get TASK_ID

# Usage
yutori usage

Run yutori --help or yutori <command> --help for full options.

Examples

See examples/ for complete working examples: Navigator n1.5 browser loops, custom tools, and a Navigator n2 computer-use agent on a Daytona desktop.

Contributing

See CONTRIBUTING.md for development setup.

Documentation

• docs.yutori.com — API reference, model versions, and parameter details
• platform.yutori.com — usage monitoring, billing, and API keys
• api.md — SDK and CLI surface reference

License

Apache 2.0 — see LICENSE.