Give your AI app a browser

import OpenAI from 'openai';
import type { ChatCompletionMessageParam, ChatCompletionTool } from 'openai/resources/chat/completions';
import { ConcurrencyLimitError, Outcrawl } from '@outcrawl/sdk';

const openai = new OpenAI(); // reads OPENAI_API_KEY
const oc = new Outcrawl(); // reads OUTCRAWL_API_KEY

// The one tool your assistant gets.
const browseTool: ChatCompletionTool = {
  type: 'function',
  function: {
    name: 'browse',
    description:
      'Do a task in a real web browser on live websites: search, open pages, pick dates, read what the page shows. ' +
      'Use it when the answer depends on current information from a specific site. ' +
      'Returns an answer and the URLs it came from.',
    parameters: {
      type: 'object',
      properties: {
        task: {
          type: 'string',
          description: 'What to do and what to report back, in one or two sentences. Name the site when you know it.',
        },
      },
      required: ['task'],
      additionalProperties: false,
    },
  },
};

// Every browse call answers in this shape, so the model reads the same thing each time.
const answerSchema = {
  type: 'object',
  properties: {
    answer: { type: 'string', description: 'The answer to the task, with the specific numbers, dates and names found.' },
    sources: {
      type: 'array',
      items: {
        type: 'object',
        properties: { url: { type: 'string' }, title: { type: 'string' } },
        required: ['url'],
      },
    },
  },
  required: ['answer', 'sources'],
};

async function browse(task: string): Promise<string> {
  try {
    const job = oc.agent({
      task,
      schema: answerSchema,
      caps: { budget: '40.00' }, // about 2.5 minutes of a typical run
      rules: ['Do not sign in, buy anything, or submit any form with personal details.'],
    });
    const { watchUrl } = await job.submitted;
    console.log(`browse: ${task}\n  watch it live: ${watchUrl ?? 'recording declined'}`);

    const run = await job;
    if (run.data === undefined) {
      return JSON.stringify({ error: `The browser run ended ${run.status} (${run.stopReason ?? 'no reason given'}).` });
    }
    // `partial` and `capped` runs still carry what they found. Tell the model which it got.
    return JSON.stringify({ ...(run.data as object), status: run.status, credits: run.credits });
  } catch (err) {
    if (err instanceof ConcurrencyLimitError) {
      return JSON.stringify({ error: 'Every browser on this account is busy right now. Try again shortly.' });
    }
    throw err;
  }
}

const messages: ChatCompletionMessageParam[] = [
  {
    role: 'system',
    content:
      'You are a travel assistant. Use the browse tool for anything that depends on live prices or availability, ' +
      'and cite the URLs it returns.',
  },
  {
    role: 'user',
    content:
      'Two adults at The Hoxton, Williamsburg, Friday 16 to Sunday 18 October. ' +
      'What is the cheapest room I can still cancel for free, and until when?',
  },
];

for (;;) {
  const completion = await openai.chat.completions.create({ model: 'gpt-5', messages, tools: [browseTool] });
  const message = completion.choices[0]!.message;
  messages.push(message);

  const calls = message.tool_calls ?? [];
  if (calls.length === 0) {
    console.log(message.content);
    break;
  }
  // One call at a time: each browse holds one of your account's browser slots while it runs.
  for (const call of calls) {
    if (call.type !== 'function') continue;
    const { task } = JSON.parse(call.function.arguments) as { task: string };
    messages.push({ role: 'tool', tool_call_id: call.id, content: await browse(task) });
  }
}

import asyncio
import json

from openai import AsyncOpenAI
from outcrawl import ConcurrencyLimitError, Outcrawl

# The one tool your assistant gets.
BROWSE_TOOL = {
    "type": "function",
    "function": {
        "name": "browse",
        "description": (
            "Do a task in a real web browser on live websites: search, open pages, pick dates, read what the page shows. "
            "Use it when the answer depends on current information from a specific site. "
            "Returns an answer and the URLs it came from."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "task": {
                    "type": "string",
                    "description": "What to do and what to report back, in one or two sentences. Name the site when you know it.",
                }
            },
            "required": ["task"],
            "additionalProperties": False,
        },
    },
}

# Every browse call answers in this shape, so the model reads the same thing each time.
ANSWER_SCHEMA = {
    "type": "object",
    "properties": {
        "answer": {"type": "string", "description": "The answer to the task, with the specific numbers, dates and names found."},
        "sources": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {"url": {"type": "string"}, "title": {"type": "string"}},
                "required": ["url"],
            },
        },
    },
    "required": ["answer", "sources"],
}


async def browse(oc: Outcrawl, task: str) -> str:
    try:
        job = oc.agent(
            task=task,
            schema=ANSWER_SCHEMA,
            caps={"budget": "40.00"},  # about 2.5 minutes of a typical run
            rules=["Do not sign in, buy anything, or submit any form with personal details."],
        )
        submitted = await job.submitted
        print(f"browse: {task}\n  watch it live: {submitted.get('watchUrl', 'recording declined')}")
        run = await job
    except ConcurrencyLimitError:
        return json.dumps({"error": "Every browser on this account is busy right now. Try again shortly."})

    data = run.get("data")
    if data is None:
        return json.dumps({"error": f"The browser run ended {run['status']} ({run.get('stopReason', 'no reason given')})."})
    # `partial` and `capped` runs still carry what they found. Tell the model which it got.
    return json.dumps({**data, "status": run["status"], "credits": run["credits"]})


async def main() -> None:
    llm = AsyncOpenAI()  # reads OPENAI_API_KEY
    async with Outcrawl() as oc:  # reads OUTCRAWL_API_KEY
        messages: list = [
            {
                "role": "system",
                "content": "You are a travel assistant. Use the browse tool for anything that depends on live prices "
                "or availability, and cite the URLs it returns.",
            },
            {
                "role": "user",
                "content": "Two adults at The Hoxton, Williamsburg, Friday 16 to Sunday 18 October. "
                "What is the cheapest room I can still cancel for free, and until when?",
            },
        ]

        while True:
            completion = await llm.chat.completions.create(model="gpt-5", messages=messages, tools=[BROWSE_TOOL])
            message = completion.choices[0].message
            messages.append(message)

            if not message.tool_calls:
                print(message.content)
                break
            # One call at a time: each browse holds one of your account's browser slots while it runs.
            for call in message.tool_calls:
                if call.type != "function":
                    continue
                task = json.loads(call.function.arguments)["task"]
                messages.append({"role": "tool", "tool_call_id": call.id, "content": await browse(oc, task)})


asyncio.run(main())