Models

Scout has no built-in model and no default: no model id, no provider and no base URL. You name a model for each job you use, on any endpoint that speaks the chat completions API (POST /chat/completions): a hosted provider, a gateway, or a server on your own machine. Each job can use its own endpoint and its own key.

const scout = new Scout({
  browser: 'outcrawl',
  models: {
    hands: { model: 'your-fast-model', baseURL: urlA, apiKey: keyA },
    brain: { model: 'your-strong-model', baseURL: urlB, apiKey: keyB, effort: 'low' },
    eyes: { model: 'your-vision-model', baseURL: urlA, apiKey: keyA },
    extract: { model: 'your-local-model', baseURL: localUrl, apiKey: '' },
  },
});

The jobs

Job	What it does	What matters
`hands`, required	Reads the page’s accessibility tree and picks each action: click, type, scroll, navigate, read.	Called on every step, so it sets most of a run’s speed and cost. A fast model that follows a JSON schema reliably.
`brain`, optional	Decides every step from a compact view of the page and the run so far; `hands` carries the decision out.	Helps long tasks that cross several pages or need a plan. A stronger reasoning model.
`eyes`, optional	Answers questions about a screenshot when the agent asks to look at the page.	Must accept images. Without it the agent works from the accessibility tree alone.
`extract`, optional	Reads a page into the answer or into your schema.	Long pages and exact fields. Without it `hands` extracts.

models takes only these four keys and rates. Anything else throws ScoutConfigError.

What each job takes

Field	Required	What it is
`model`	yes	The model id, exactly as your endpoint expects it.
`baseURL`	yes	The endpoint’s `http` or `https` base URL, the part before `/chat/completions`, for example `https://api.example.com/v1` or `http://localhost:11434/v1`.
`apiKey`	yes	Sent as a bearer token. `''` sends none, for a local server.
`effort`	no	How hard the model may think, for a model that takes a reasoning effort: `'minimal'`, `'low'`, `'medium'` or `'high'`. Absent sends none.
`structuredOutput`	no	How a JSON reply is asked for. Default `'tool_choice'`. See below.
`headers`	no	Extra headers sent with every request to this endpoint, as a map of header names to strings.

Structured replies

Scout asks each model for JSON. structuredOutput sets how:

'tool_choice' (the default) forces one function call whose parameters are the schema. Function calling is the most widely supported way to get structured output across chat completions endpoints.
'json_object' asks for any JSON and spells the schema out in the prompt, for an endpoint without function calling.
'strict' sends a strict json_schema response format, for an endpoint that supports it.

If your endpoint refuses the mode, it answers 400 and the run’s error names the job, its model and the two other settings to try, for example set models.hands.structuredOutput to 'json_object' or 'strict'. Scout does not switch modes on its own: you decide which one your endpoint takes.

Cost

When your endpoint states a cost per call, result.costUsd is the run’s model spend in USD. To price models yourself, and to hold a run to a caps.budget, pass models.rates with every job’s model:

models: {
  hands: { ... },
  rates: {
    'your-model-id': {
      input: '0.30',
      output: '1.20',
      cacheRead: null,
      cacheWrite: null,
      inputModalities: ['text'],
    },
  },
}

Prices are USD per million tokens as decimal strings, keyed by model id. cacheRead and cacheWrite are null when the endpoint bills no such line, which is not the same as billing zero. inputModalities lists what the model accepts: 'text', and 'image' for a model that reads screenshots. Once you pass rates, every job’s model needs an entry, or new Scout throws ScoutConfigError rather than report a cost that reads as zero. Without rates and without a stated cost, costUsd is absent rather than zero.

Models from the environment

The examples read their models from environment variables through a small helper, examples/models.ts. Scout itself reads none of these: the only variable it reads is OUTCRAWL_API_KEY, for the cloud browser. Start from the helper if the pattern suits you.

Variable	What it sets
`SCOUT_BASE_URL`	Your endpoint’s base URL, the part before `/chat/completions`.
`SCOUT_API_KEY`	Its key. Leave it empty for a local server that takes none.
`SCOUT_HANDS_MODEL`	Required: the model that reads the page and acts.
`SCOUT_BRAIN_MODEL`	Optional: decides each step on long, multi-page tasks.
`SCOUT_EYES_MODEL`	Optional: an image-capable model for questions about a screenshot.
`SCOUT_EXTRACT_MODEL`	Optional: reads pages into your schema.

Any job can use its own endpoint with SCOUT_<JOB>_BASE_URL and SCOUT_<JOB>_API_KEY, for example SCOUT_BRAIN_BASE_URL.

Get started

Configure

Resources

The jobs

What each job takes

Structured replies

Cost

Models from the environment

​The jobs

​What each job takes

​Structured replies

​Cost

​Models from the environment

The jobs

What each job takes

Structured replies

Cost

Models from the environment