BrowserUse_and_ComputerUse_skills/api/README.md

Browser REST API

REST API-обертка над browser-use RPC (POST /run в контейнере браузера).

Сервис принимает задачу, ставит ее в in-memory очередь, выполняет через browser-use и отдает статус/результат по task_id.

Актуальный статус

Проверено smoke-тестом:

• GET /health отвечает 200 с {"ok": true}
• POST /api/browser/tasks возвращает 202 и task_id
• GET /api/browser/tasks/{task_id} возвращает queued/running/...
• GET /api/browser/tasks/{task_id}/result возвращает 202, пока задача не завершена
• GET /api/browser/tasks/{task_id}/history возвращает историю шагов агента

Архитектура

Слои сейчас разделены и выглядят нормально для MVP:

• api/main.py — точка входа ASGI (uvicorn api.main:app), сборка FastAPI и lifespan
• api/routes/tasks.py — HTTP-слой (валидация входа/выхода, status codes)
• api/services/task_service.py — orchestration (фоновые задачи, timeout, обработка ошибок)
• api/repositories/task_store.py — in-memory хранилище задач
• api/clients/browser_rpc_client.py — aiohttp-клиент к browser RPC
• api/clients/browser_rpc_contracts.py — protocol + исключения RPC-слоя
• api/contracts/task_schemas.py — Pydantic request/response DTO
• api/domain/task_status.py — доменный enum статусов
• api/core/settings.py — конфигурация из env

Ограничения текущей реализации

• хранилище in-memory: после рестарта контейнера задачи теряются
• нет ретраев RPC при транспортных ошибках
• один инстанс процесса хранит задачи только локально (без shared state)

Переменные окружения

• BROWSER_API_HOST (default: 0.0.0.0)
• BROWSER_API_PORT (default: 8080)
• BROWSER_USE_RPC_URL (default: http://browser:8787/run)
• BROWSER_USE_RPC_TIMEOUT (default: 900)
• BROWSER_API_MAX_CONCURRENCY (default: 2)

Локальный запуск

cd "/Users/fedorkobylkevic/PycharmProjects/BrowserUse_and_ComputerUse_skills"
source .venv/bin/activate
uvicorn api.main:app --host 0.0.0.0 --port 8088

Запуск через Docker Compose

cd "/Users/fedorkobylkevic/PycharmProjects/BrowserUse_and_ComputerUse_skills"
docker compose build browser-api
docker compose up -d browser browser-api
docker compose logs -f browser-api

REST API

GET /health

Проверка доступности API.

Пример ответа:

{"ok": true}

POST /api/browser/tasks

Создать задачу.

Request:

{
  "task": "Открой example.com и верни title",
  "timeout": 300,
  "metadata": {"source": "manual"}
}

Response 202:

{
  "task_id": "53f54fa4c1f24219b3949d56b0457875",
  "status": "queued"
}

GET /api/browser/tasks/{task_id}

Текущий статус и таймстемпы.

GET /api/browser/tasks/{task_id}/result

• 202 если задача еще queued/running
• 200 с финальным payload после завершения

GET /api/browser/tasks/{task_id}/history

• 202 если задача еще queued/running
• 200 с финальной историей шагов после завершения

Пример ответа 200:

{
  "task_id": "53f54fa4c1f24219b3949d56b0457875",
  "status": "succeeded",
  "history": [
    {
      "step": 1,
      "kind": "thought",
      "content": "Open target page",
      "data": {"value": "Open target page"}
    },
    {
      "step": 2,
      "kind": "action",
      "content": "Click login",
      "data": {"value": "Click login"}
    }
  ]
}

Runs API (background runs)

Новый набор endpoint-ов для фоновых запусков:

• POST /runs — создать run в фоне
• GET /runs/{run_id} — получить run и его статус
• POST /runs/{run_id}/cancel — отменить pending/running run
• DELETE /runs/{run_id} — удалить завершенный run
• GET /runs/{run_id}/wait — дождаться завершения и вернуть финальный output
• GET /runs/{run_id}/stream — подключиться к live-потоку новых событий run (SSE)
• GET /threads/{thread_id}/runs — список run-ов в треде

Пример создания run:

{
  "thread_id": "thread-demo",
  "input": "Открой example.com и верни title",
  "timeout": 60,
  "metadata": {"source": "manual"}
}

Быстрый end-to-end пример

curl -sS http://localhost:8088/health

RESP=$(curl -sS -X POST http://localhost:8088/api/browser/tasks \
  -H "Content-Type: application/json" \
  -d '{"task":"Открой example.com и верни title","timeout":30}')

echo "$RESP"

TASK_ID=$(python -c "import json,sys;print(json.loads(sys.argv[1])['task_id'])" "$RESP")

curl -sS "http://localhost:8088/api/browser/tasks/$TASK_ID"
curl -sS "http://localhost:8088/api/browser/tasks/$TASK_ID/result"
curl -sS "http://localhost:8088/api/browser/tasks/$TASK_ID/history"