Как запустить Microsoft Fara в Google Colab с тестовым браузерным агентом

В этом руководстве мы настроим Microsoft Fara в Google Colab и пройдём весь путь запуска браузерного агента: склонируем репозиторий, установим пакет и Playwright, проверим файлы Fara и выполним тестовую задачу в браузере. Вместо того чтобы сразу запускать ресурсоёмкую модель Fara-7B, мы создадим небольшой тестовый сервер с API, совместимым с OpenAI. Он позволит проверить, передаёт ли обвязка задачу и выполняет ли два заранее заданных ответа в браузере. Качество Fara-7B такой тест не оценивает. Позже тот же ноутбук можно будет подключить к Azure Foundry, vLLM, LM Studio или Ollama.

Настройка параметров

Импортируем нужные библиотеки и зададим параметры. Переключатель определяет, использовать ли тестовый сервер или настоящее подключение к Fara. Задача агента — открыть example.com и описать страницу. Также создадим рабочие каталоги и укажем пути к репозиторию, конфигурации сервера и выходным файлам.

import os
import sys
import json
import time
import socket
import subprocess
import importlib
from pathlib import Path
USE_REAL_FARA_ENDPOINT = False
REAL_FARA_BASE_URL = "http://localhost:5000/v1"
REAL_FARA_API_KEY = os.environ.get("FARA_API_KEY", "not-needed")
REAL_FARA_MODEL = "microsoft/Fara-7B"
TASK = "Open example.com and tell me what the page is."
WORKDIR = Path("/content/fara_tutorial")
REPO_DIR = Path("/content/fara")
REPO_SRC = REPO_DIR / "src"
OUTPUT_DIR = WORKDIR / "outputs"
ENDPOINT_CONFIG_PATH = WORKDIR / "endpoint_config.json"
MOCK_SERVER_FILE = WORKDIR / "mock_fara_endpoint.py"
WORKDIR.mkdir(parents=True, exist_ok=True)
OUTPUT_DIR.mkdir(parents=True, exist_ok=True)

Вспомогательные функции

Функция run_cmd запускает команды оболочки и выводит их результат. wait_for_port проверяет, доступен ли сервер на указанном порту, прежде чем переходить к следующему шагу. В конце выведем версию Python и путь к рабочему каталогу, чтобы проверить среду Colab.

def run_cmd(cmd, cwd=None, check=True, env=None):
   print(f"\n$ {cmd}")
   result = subprocess.run(
       cmd,
       shell=True,
       cwd=str(cwd) if cwd else None,
       text=True,
       stdout=subprocess.PIPE,
       stderr=subprocess.STDOUT,
       env=env,
   )
   print(result.stdout)
   if check and result.returncode != 0:
       raise RuntimeError(f"Command failed with exit code {result.returncode}: {cmd}")
   return result
def wait_for_port(host, port, timeout=60):
   start = time.time()
   while time.time() - start < timeout:
       try:
           with socket.create_connection((host, port), timeout=2):
               return True
       except OSError:
           time.sleep(1)
   return False
print("Python:", sys.version)
print("Working directory:", WORKDIR)

Установка Fara и Playwright

Склонируем репозиторий Microsoft Fara в Colab. Если он уже существует, попробуем обновить его. Затем установим Fara и необходимые для тестового сервера и браузерного сценария пакеты. Установим Firefox и системные зависимости для Playwright.

os.chdir("/content")
if REPO_DIR.exists():
   print("Fara repo already exists. Pulling latest changes...")
   run_cmd("git pull", cwd=REPO_DIR, check=False)
else:
   run_cmd("git clone https://github.com/microsoft/fara.git /content/fara")
print("\nInstalling Fara and tutorial dependencies...")
run_cmd(
   f'{sys.executable} -m pip install -q "setuptools<82" wheel pip',
   check=True,
)
run_cmd(
   f'{sys.executable} -m pip install -q -e /content/fara fastapi uvicorn requests pillow',
   check=True,
)
if str(REPO_SRC) not in sys.path:
   sys.path.insert(0, str(REPO_SRC))
print("\nInstalling Playwright Firefox browser and system dependencies...")
run_cmd(
   f"{sys.executable} -m playwright install --with-deps firefox",
   check=True,
)

Проверка структуры пакета

Проверим, откуда импортируется установленный пакет Fara, и выведем список Python-файлов в его исходном каталоге. Затем попробуем получить определения действий агента. Эта проверка необязательна: если структура пакета изменилась или нужный модуль не найден, выполнение руководства продолжится.

print("\nInspecting Fara package files...")
try:
   import fara
   print("Imported fara from:", getattr(fara, "__file__", "unknown"))
except Exception as e:
   print("Could not import fara:", repr(e))
print("\nAvailable files inside /content/fara/src/fara:")
if (REPO_SRC / "fara").exists():
   for p in sorted((REPO_SRC / "fara").glob("*.py")):
       print("-", p.name)
else:
   print("Could not find /content/fara/src/fara")
print("\nTrying to inspect Fara action definitions...")
try:
   fara_agent = importlib.import_module("fara.fara_agent")
   action_defs = getattr(fara_agent, "FARA_ACTION_DEFINITIONS", None)
   if action_defs:
       print("\nFara action space:")
       for action_name, arg_names in action_defs.items():
           args = ", ".join(sorted(arg_names)) if arg_names else "no arguments"
           print(f"- {action_name}: {args}")
   else:
       print("FARA_ACTION_DEFINITIONS was not found. Continuing because this step is optional.")
except Exception as e:
   print("Could not import fara.fara_agent directly:", repr(e))
   print("Continuing because this inspection step is optional.")

Создание тестового сервера

Создадим небольшой сервер, совместимый с OpenAI API. При первом запросе он вернёт команду открыть example.com, а при следующем сообщит, что открылась демонстрационная страница Example Domain, и завершит задачу. Сохраним настройки подключения: по умолчанию используется тестовый сервер на локальном порту 8001. Если включить настоящий сервер, будут использованы заданные параметры Fara-7B.

mock_server_code = r'''
from fastapi import FastAPI, Request
import time
app = FastAPI()
STATE = {"calls": 0}
@app.post("/v1/chat/completions")
async def chat_completions(request: Request):
   payload = await request.json()
   STATE["calls"] += 1
   model_name = payload.get("model", "mock-fara-7b")
   if STATE["calls"] == 1:
       content = (
           "I will open a stable public test page so the browser-control loop can be demonstrated.\n"
           "{\"name\":\"computer\",\"arguments\":{\"action\":\"visit_url\",\"url\":\"https://example.com\"}}"
       )
   else:
       content = (
           "The browser has opened Example Domain, a stable demonstration page used for documentation and examples.\n"
           "{\"name\":\"computer\",\"arguments\":{\"action\":\"terminate\",\"status\":\"success\"}}"
       )
   return {
       "id": f"chatcmpl-mock-{STATE['calls']}",
       "object": "chat.completion",
       "created": int(time.time()),
       "model": model_name,
       "choices": [
           {
               "index": 0,
               "message": {
                   "role": "assistant",
                   "content": content
               },
               "finish_reason": "stop"
           }
       ],
       "usage": {
           "prompt_tokens": 100,
           "completion_tokens": 50,
           "total_tokens": 150
       }
   }
'''
MOCK_SERVER_FILE.write_text(mock_server_code)
print(f"\nMock endpoint written to: {MOCK_SERVER_FILE}")
if USE_REAL_FARA_ENDPOINT:
   endpoint_config = {
       "model": REAL_FARA_MODEL,
       "base_url": REAL_FARA_BASE_URL,
       "api_key": REAL_FARA_API_KEY,
   }
else:
   endpoint_config = {
       "model": "mock-fara-7b",
       "base_url": "http://127.0.0.1:8001/v1",
       "api_key": "not-needed",
   }
fd = os.open(ENDPOINT_CONFIG_PATH, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
with os.fdopen(fd, "w", encoding="utf-8") as config_file:
   json.dump(endpoint_config, config_file, indent=2)
print("Endpoint config written; credentials are not printed.")
mock_process = None
if not USE_REAL_FARA_ENDPOINT:
   print("\nStarting mock OpenAI-compatible endpoint...")
   mock_process = subprocess.Popen(
       [
           sys.executable,
           "-m",
           "uvicorn",
           "mock_fara_endpoint:app",
           "--host",
           "127.0.0.1",
           "--port",
           "8001",
       ],
       cwd=str(WORKDIR),
       stdout=subprocess.PIPE,
       stderr=subprocess.STDOUT,
       text=True,
   )
   if not wait_for_port("127.0.0.1", 8001, timeout=60):
       if mock_process and mock_process.stdout:
           print(mock_process.stdout.read())
       raise RuntimeError("Mock endpoint did not start on port 8001.")
   print("Mock endpoint is running at http://127.0.0.1:8001/v1")
else:
   print("\nUsing real Fara endpoint. Make sure it is reachable.")

Запуск браузерного агента

Запустим агент через fara-cli. Если команда завершится с ошибкой, попробуем запустить модуль fara.run_fara. После этого выведем код завершения и проверим, появились ли файлы в каталоге результатов.

print("\nRunning Fara browser agent...")
fara_command = (
   f'fara-cli '
   f'--task "{TASK}" '
   f'--endpoint_config "{ENDPOINT_CONFIG_PATH}"'
)
agent_result = run_cmd(fara_command, cwd=REPO_DIR, check=False)
if agent_result.returncode != 0:
   print("\nfara-cli failed, trying module form...")
   fara_command = (
       f'{sys.executable} -m fara.run_fara '
       f'--task "{TASK}" '
       f'--endpoint_config "{ENDPOINT_CONFIG_PATH}"'
   )
   agent_result = run_cmd(fara_command, cwd=REPO_DIR, check=False)
print("\nFara command exit code:", agent_result.returncode)
print("\nSaved tutorial outputs:")
if OUTPUT_DIR.exists():
   files = sorted(OUTPUT_DIR.glob("*"))
   if files:
       for path in files:
           print("-", path)
   else:
       print("No files saved in output directory.")
else:
   print("Output directory does not exist.")

Подключение настоящей модели

Чтобы перейти от тестового режима к Fara-7B, установите USE_REAL_FARA_ENDPOINT = True и задайте адрес сервера, ключ API и название модели. Для Azure Foundry укажите адрес конечной точки и ключ. Для vLLM запустите сервер на машине с GPU командой ниже, а затем задайте соответствующий адрес. LM Studio и Ollama также подойдут, если загрузить совместимую модель Fara-7B и включить локальный сервер, совместимый с OpenAI API.

============================================================================
How to switch this notebook from mock mode to real Fara-7B
============================================================================
Option A: Azure Foundry endpoint
Set:
USE_REAL_FARA_ENDPOINT = True
REAL_FARA_BASE_URL = "https://your-endpoint.inference.ml.azure.com/"
Задайте FARA_API_KEY в окружении или через секреты Colab.
REAL_FARA_MODEL = "Fara-7B"
Option B: self-host with vLLM on a GPU machine
Run this separately on the GPU machine:
vllm serve "microsoft/Fara-7B" --port 5000 --dtype auto
Then set:
USE_REAL_FARA_ENDPOINT = True
REAL_FARA_BASE_URL = "http://localhost:5000/v1"
REAL_FARA_API_KEY = os.environ.get("FARA_API_KEY", "not-needed")
REAL_FARA_MODEL = "microsoft/Fara-7B"
Option C: LM Studio or Ollama
Load a compatible Fara-7B model and enable an OpenAI-compatible local server.
Example base URLs:
LM Studio: http://localhost:1234/v1
Ollama-style OpenAI server: http://localhost:11434/v1
Important:
Browser agents should be tested in sandboxed environments only.
Avoid private accounts, payments, credentials, and high-risk websites.
============================================================================

Браузерных агентов следует тестировать только в изолированной среде. Не используйте их для работы с личными аккаунтами, платежами, учётными данными и сайтами, где возможны серьёзные риски.

После выполнения сценария остановим тестовый сервер, если он был запущен, и завершим работу ноутбука.

if mock_process is not None:
   print("\nStopping mock endpoint...")
   mock_process.terminate()
   try:
       mock_process.wait(timeout=10)
   except subprocess.TimeoutExpired:
       mock_process.kill()
   print("Mock endpoint stopped.")
ENDPOINT_CONFIG_PATH.unlink(missing_ok=True)
print("\nTutorial complete.")

Пример описывает настройку Fara для Colab, которая демонстрирует основной цикл управления браузером без GPU и работающего сервера с моделью. Установка фреймворка, подготовка браузера, проверка структуры пакета, запуск тестового сервера и простая задача позволяют проверить формат запросов и выполнение действий до перехода на настоящую модель. Чтобы подключить Fara-7B, достаточно изменить параметры конечной точки.