# Yutori AI Agent Quickstart

You are helping a user set up Yutori from scratch. Yutori provides APIs and agent tools for:

| Capability | Use it for |
| --- | --- |
| Scout | Continuous web monitoring on a schedule |
| Research | One-time deep web research |
| Browsing | One-time browser automation |
| Navigator | A computer-use model API for custom browser agents |

Prioritize the CLI/MCP setup first. Do not ask the user to paste API keys into chat.

## Setup

Drive setup yourself. The user's only action is clicking **Allow** in a browser tab that opens during auth.

1. Install the CLI, MCP server, and skills in one shot (you run this):

    ```bash
    YUTORI_INSTALL_CLIENT=<client> curl -fsSL https://yutori.com/install.sh | bash
    ```

    Substitute `<client>` with your agent's slug — common values: `claude-code`, `codex`, `cursor`, `vscode`, `claude-desktop`, `gemini-cli`, `zed`, `opencode` (run `npx add-mcp list-agents` for the full list). If `YUTORI_INSTALL_CLIENT` is unset the installer registers MCP for the default set (`claude-code`, `codex`, `cursor`, `gemini-cli`).

    In non-TTY mode the installer does the CLI install via `uv tool install yutori`, registers the Yutori MCP server for the chosen client(s), and installs the six workflow skills (`yutori-scout`, `yutori-research`, `yutori-browse`, `yutori-competitor-watch`, `yutori-api-monitor`, `yutori-login`) at user scope. Auth and verification are skipped — they need a browser and an API key (step 2 below).

    If `~/.local/bin` isn't on your PATH yet, invoke `yutori` via `$(uv tool dir --bin)/yutori` or run `export PATH="$(uv tool dir --bin):$PATH"` for the rest of this session.

2. Authenticate (you run this; **user clicks Allow**):

    ```bash
    yutori auth login
    ```

    **Always run this yourself first**, even on a headless host. The command calls `webbrowser.open(auth_url)`, binds `127.0.0.1` for the OAuth callback, and saves the API key to `~/.yutori/config.json`. The Bash call blocks for up to 5 minutes waiting for the user — if it times out, rerun.

    Two cases:
    - **Desktop / browser available**: the sign-in tab opens automatically. Tell the user: *"I'm opening a Yutori sign-in tab — click Allow when it loads."*
    - **Headless host / no browser**: the command prints `Could not launch a browser` followed by an `auth_url`. **Relay that URL to the user** — they paste it into a browser on their own machine, click Allow, and the OAuth callback still completes through your Bash process. Don't skip running `yutori auth login` just because the host might be headless; try it and react to what it prints.

3. Ask the user to restart this coding agent so the MCP tools and skills load.

### Fallback: if step 1 didn't configure MCP or skills

The installer's status table will say `MCP server: SKIP` or `MCP skills: SKIP` if Node.js/npx wasn't on PATH. Run only the failed step(s):

```bash
# MCP server
npx add-mcp -y -g -n yutori -a <client> "uvx yutori-mcp"

# Workflow skills
npx skills add yutori-ai/yutori-mcp -g
```

If `npx` isn't available, native CLIs work for some clients:
- Claude Code: `claude mcp add --scope user yutori -- uvx yutori-mcp`
- Codex: `codex mcp add yutori -- uvx yutori-mcp`

**Fallback path:** if your Bash tool can't bind `127.0.0.1` for the auth callback (remote dev environment, sandboxed agent) or the user is on a different machine, ask the user to run `curl -fsSL https://yutori.com/install.sh | bash` in their own terminal — the interactive installer walks through CLI, auth, MCP, skills, and a verification task end-to-end.

## Verify

**You run these yourself** once the user confirms `yutori auth login` completed:

```bash
yutori auth status     # confirms the API key is saved and valid
yutori usage           # shows the user their daily quota and active scouts
```

If both succeed, proceed to **Demonstrate** below. If MCP tools have already loaded in your session (i.e. the coding agent was restarted), `list_api_usage` is an equivalent MCP check.

## Demonstrate

After auth and verify succeed, run the three demos yourself via the `yutori` CLI in your Bash tool — **no coding-agent restart needed**. (After restart, the MCP tools `run_research_task`, `run_browsing_task`, `create_scout` and the `/yutori-*` skills also become available; use either path.)

The task APIs are async: `run` starts the task and returns a `task_id`; you then poll `get TASK_ID` until `status` is `succeeded` or `failed`. Examples below mirror the canonical queries at <https://docs.yutori.com/reference/> so demo and docs stay aligned.

### Research (3–10 min)

```bash
yutori research run "What are the latest developments in quantum computing from the past week? Include company announcements, research papers, and product releases."
# returns task_id; poll until done
yutori research get <task_id>
```

Show the user the returned summary once `status: succeeded`.

### Browsing (30–120 sec)

```bash
yutori browse run "Give me a list of all employees (names and titles) of Yutori." "https://yutori.com"
yutori browse get <task_id>
```

Confirm with the user before running additional browsing tasks — each one spends credits.

### Scout — draft only, **do not auto-create**

Scouts are *recurring* and spend credits on every scheduled run. Show the user the query you would use and ask for explicit confirmation before running:

```bash
yutori scouts create -q "Tell me about the latest news, product updates, press releases, social media announcements, investments into, or other relevant information about Yutori"
```

If they decline, skip the Scout demo and end with a recap of Research + Browsing.

## Navigator API

Navigator is Yutori's computer-use model (model id `n1.5-latest`). It is an **OpenAI Chat Completions-compatible endpoint**: you send a screenshot of a web page plus a task instruction, and the model returns **browser actions** as tool calls (`left_click`, `type`, `scroll`, `goto_url`, …). You execute those actions in your own browser (e.g. Playwright), append the results, capture a fresh screenshot, and call again — an **agent loop** — until the model returns a text response with no tool calls.

There is no `yutori` CLI command for Navigator; it is called from Python via `client.chat.completions.create(...)`, which is a drop-in OpenAI-compatible client.

### Minimal single call

```python
from yutori import YutoriClient
from yutori.navigator import playwright_screenshot_to_data_url
from playwright.sync_api import sync_playwright

with YutoriClient() as client, sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    page.goto("https://www.yutori.com")

    image_url = playwright_screenshot_to_data_url(page)

    response = 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 reasoning / final answer
    for tc in message.tool_calls or []:
        print(tc.function.name, tc.function.arguments)
```

### Building an agent loop

In practice you run a loop: execute the returned tool calls on your Playwright `page`, append the results as `tool` messages, capture a fresh screenshot, and call `create()` again until the model returns no tool calls. The `yutori.navigator` subpackage provides helpers for this — screenshot capture, coordinate denormalization (model uses a 1000×1000 space), message trimming, and key mapping.

For a complete working agent loop with retries, structured output, and expanded tools, see [`examples/navigator_n1_5.py`](https://github.com/yutori-ai/yutori-sdk-python/blob/main/examples/navigator_n1_5.py).

### Navigator n1.5 parameters

Pass these as keyword args to `client.chat.completions.create(...)`:

| Parameter | Purpose |
|-----------|---------|
| `model` | `"n1.5-latest"` (default) or a dated version like `"n1.5-20260428"`. |
| `tool_set` | Built-in tool set: `"browser_tools_core-20260403"` (default — 18 coordinate-based tools) or `"browser_tools_expanded-20260403"` (adds `extract_elements`, `find`, `set_element_value`, `execute_js`). |
| `disable_tools` | Remove specific tools by name, e.g. `["hold_key", "drag"]`. |
| `json_schema` | JSON Schema dict for structured output. Model returns conforming JSON; accessible as `response.parsed_json`. |
| `temperature` | Sampling temperature (default 0.3). |

The core action space covers clicks, scroll, type, key press, drag, mouse move/down/up, navigation (`goto_url`, `go_back`, `go_forward`, `refresh`), `wait`, and `hold_key`. Coordinates are in a normalized 1000×1000 space — use `denormalize_coordinates(coords, width, height)` to map to viewport pixels. For the full action reference, see <https://docs.yutori.com/reference/n1-5>. For the SDK and CLI reference, see the link at the bottom of this file.

For SDK/API integration details, use:

- Python SDK and CLI reference: https://github.com/yutori-ai/yutori-sdk-python/blob/main/api.md
- MCP server and skill setup: https://github.com/yutori-ai/yutori-mcp
- API docs index for agents: https://docs.yutori.com/llms.txt