172 lines
5.4 KiB
Markdown
172 lines
5.4 KiB
Markdown
# 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`)
|
||
|
||
## Локальный запуск
|
||
|
||
```zsh
|
||
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
|
||
|
||
```zsh
|
||
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.
|
||
|
||
Пример ответа:
|
||
|
||
```json
|
||
{"ok": true}
|
||
```
|
||
|
||
### `POST /api/browser/tasks`
|
||
|
||
Создать задачу.
|
||
|
||
Request:
|
||
|
||
```json
|
||
{
|
||
"task": "Открой example.com и верни title",
|
||
"timeout": 300,
|
||
"metadata": {"source": "manual"}
|
||
}
|
||
```
|
||
|
||
Response `202`:
|
||
|
||
```json
|
||
{
|
||
"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`:
|
||
|
||
```json
|
||
{
|
||
"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:
|
||
|
||
```json
|
||
{
|
||
"thread_id": "thread-demo",
|
||
"input": "Открой example.com и верни title",
|
||
"timeout": 60,
|
||
"metadata": {"source": "manual"}
|
||
}
|
||
```
|
||
|
||
## Быстрый end-to-end пример
|
||
|
||
```zsh
|
||
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"
|
||
```
|