Управление сессиями

Интерактивные shell-сессии с агентами: жизненный цикл, timeout, конкурентные лимиты и безопасность

Обзор

Sessions позволяют создавать интерактивные shell-сессии с агентами через MCP. Каждая сессия сохраняет рабочую директорию, переменные окружения и историю команд между вызовами. Идеально для длительных задач: деплой, миграции, debug, работа с базами данных. Сессии управляются через REST API и MCP tool `flowlink_exec` с параметром `session_id`.

Таймаут

30 мин неактивности (настраивается)

Все тарифы

Лимит сессий

5 одновременных на агента

Team+

MCP интеграция

flowlink_exec + session_id

Все тарифы

Audit trail

Полный лог всех команд

Все тарифы

Архитектура и жизненный цикл

Каждая сессия проходит через 4 состояния: создание, активность, таймаут, закрытие. Сессия привязана к конкретному агенту и изолирована от других сессий на том же агенте. Все команды внутри сессии логируются в audit trail с привязкой к session_id.

# Жизненный цикл сессии

1. Создание:

POST /api/v1/sessions → status: active

# 2. Выполнение команд:

flowlink_exec(agent_id, session_id, command) → stdout/stderr

# 3. Таймаут (30 мин неактивности):

status: timeout → автоматическая очистка ресурсов

# 4. Ручное закрытие:

DELETE /api/v1/sessions/{id} → status: closed

active

Сессия готова к командам

closed

Закрыта пользователем

timeout

Истёк таймаут неактивности

error

Ошибка на стороне агента

Свойства сессии

Свойство	Тип	Описание
id	string	Уникальный ID сессии (sess_xxx)
agent_id	string	ID агента
cwd	string	Рабочая директория (сохраняется между командами)
env	object	Переменные окружения (key/value)
status	string	active \| closed \| timeout \| error
command_count	integer	Количество выполненных команд
total_execution_ms	integer	Суммарное время выполнения (ms)
created_at	string	Время создания (ISO 8601)
last_activity_at	string	Время последней активности
timeout_at	string	Время автоматического таймаута

Конфигурация

Настройки сессий задаются в конфигурации FlowLink server. Можно управлять таймаутами, конкурентными лимитами и политиками очистки.

yaml

1# Конфигурация сессий в flowlink.config.yml
2sessions:
3  timeout_seconds: 1800        # 30 минут неактивности
4  max_concurrent_per_agent: 5  # Максимум сессий на одного агента
5  max_concurrent_per_org: 50   # Максимум сессий на организацию
6  cleanup_interval_seconds: 60 # Интервал проверки таймаутов
7  max_command_history: 100     # Команд в истории сессии
8  env_defaults:                # Переменные окружения по умолчанию
9    PATH: "/usr/local/bin:/usr/bin:/bin"
10    LANG: "en_US.UTF-8"
11
12  # Политики хранения
13  retention:
14    active_commands: "7d"      # Команды активных сессий
15    closed_sessions: "30d"     # Данные закрытых сессий
16    audit_log: "365d"          # Audit trail (compliance)

Конкурентные лимиты

yaml

1# Лимиты по тарифам
2concurrency:
3  free:
4    max_sessions_per_agent: 2
5    max_sessions_per_org: 10
6  team:
7    max_sessions_per_agent: 5
8    max_sessions_per_org: 50
9  enterprise:
10    max_sessions_per_agent: 20
11    max_sessions_per_org: 200

API Reference

Создание сессии

bash

1curl -X POST "https://api.flowlink.io/v1/sessions" \
2  -H "Authorization: Bearer $TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "agent_id": "agent-prod-01",
6    "cwd": "/var/www/app",
7    "env": {
8      "NODE_ENV": "production",
9      "DEPLOY_VERSION": "2.4.1"
10    },
11    "timeout_seconds": 3600,
12    "metadata": {
13      "purpose": "deploy",
14      "initiated_by": "ci-pipeline"
15    }
16  }'

json

1{
2  "id": "sess_abc123def456",
3  "agent_id": "agent-prod-01",
4  "cwd": "/var/www/app",
5  "env": { "NODE_ENV": "production", "DEPLOY_VERSION": "2.4.1" },
6  "status": "active",
7  "command_count": 0,
8  "total_execution_ms": 0,
9  "created_at": "2026-01-15T14:00:00Z",
10  "last_activity_at": "2026-01-15T14:00:00Z",
11  "timeout_at": "2026-01-15T15:00:00Z",
12  "metadata": { "purpose": "deploy", "initiated_by": "ci-pipeline" }
13}

Список сессий

bash

1curl -s "https://api.flowlink.io/v1/sessions?agent_id=agent-prod-01&status=active&limit=20" \
2  -H "Authorization: Bearer $TOKEN" | jq

json

1{
2  "sessions": [
3    {
4      "id": "sess_abc123def456",
5      "agent_id": "agent-prod-01",
6      "cwd": "/var/www/app",
7      "status": "active",
8      "command_count": 12,
9      "created_at": "2026-01-15T14:00:00Z",
10      "last_activity_at": "2026-01-15T14:25:00Z",
11      "timeout_at": "2026-01-15T14:55:00Z"
12    },
13    {
14      "id": "sess_xyz789ghi012",
15      "agent_id": "agent-prod-01",
16      "cwd": "/home/deploy",
17      "status": "active",
18      "command_count": 3,
19      "created_at": "2026-01-15T14:10:00Z",
20      "last_activity_at": "2026-01-15T14:20:00Z",
21      "timeout_at": "2026-01-15T14:50:00Z"
22    }
23  ],
24  "total": 2,
25  "limit": 20
26}

Детали сессии

bash

1curl -s "https://api.flowlink.io/v1/sessions/sess_abc123def456" \
2  -H "Authorization: Bearer $TOKEN" | jq

json

1{
2  "id": "sess_abc123def456",
3  "agent_id": "agent-prod-01",
4  "cwd": "/var/www/app/releases/2.4.1",
5  "env": { "NODE_ENV": "production", "DEPLOY_VERSION": "2.4.1" },
6  "status": "active",
7  "command_count": 12,
8  "total_execution_ms": 4520,
9  "created_at": "2026-01-15T14:00:00Z",
10  "last_activity_at": "2026-01-15T14:25:00Z",
11  "timeout_at": "2026-01-15T14:55:00Z",
12  "commands": [
13    {
14      "id": "cmd_001",
15      "command": "git pull origin main",
16      "exit_code": 0,
17      "execution_time_ms": 1200,
18      "executed_at": "2026-01-15T14:01:00Z"
19    },
20    {
21      "id": "cmd_002",
22      "command": "npm ci --production",
23      "exit_code": 0,
24      "execution_time_ms": 3200,
25      "executed_at": "2026-01-15T14:02:00Z"
26    }
27  ]
28}

Закрытие сессии

bash

1curl -X DELETE "https://api.flowlink.io/v1/sessions/sess_abc123def456" \
2  -H "Authorization: Bearer $TOKEN"

json

1{
2  "id": "sess_abc123def456",
3  "status": "closed",
4  "closed_at": "2026-01-15T14:30:00Z",
5  "summary": {
6    "total_commands": 12,
7    "successful": 11,
8    "failed": 1,
9    "total_execution_ms": 4520
10  }
11}

Продление таймаута

bash

1curl -X PATCH "https://api.flowlink.io/v1/sessions/sess_abc123def456/extend" \
2  -H "Authorization: Bearer $TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{"extend_seconds": 1800}'

json

1{
2  "id": "sess_abc123def456",
3  "timeout_at": "2026-01-15T15:25:00Z",
4  "extended_by_seconds": 1800
5}

MCP интеграция

Сессии используются через MCP tool `flowlink_exec` с параметром `session_id`. Без session_id каждая команда выполняется в изолированном shell. С session_id — все команды делят общее окружение.

json

1{
2  "name": "flowlink_exec",
3  "arguments": {
4    "agent_id": "agent-prod-01",
5    "session_id": "sess_abc123def456",
6    "command": "npm run build"
7  }
8}

json

1{
2  "result": {
3    "exit_code": 0,
4    "stdout": "Build completed successfully\nBundle size: 2.4MB",
5    "stderr": "",
6    "execution_time_ms": 8500,
7    "session": {
8      "id": "sess_abc123def456",
9      "cwd": "/var/www/app",
10      "command_count": 13
11    }
12  }
13}

Events API сессий

Каждое изменение состояния сессии генерирует событие. События используются для интеграции с webhook, SIEM и мониторингом.

json

1{
2  "event_type": "session.created",
3  "session_id": "sess_abc123def456",
4  "agent_id": "agent-prod-01",
5  "timestamp": "2026-01-15T14:00:00Z",
6  "metadata": { "purpose": "deploy" }
7}
8
9{
10  "event_type": "session.command_executed",
11  "session_id": "sess_abc123def456",
12  "command": "npm run build",
13  "exit_code": 0,
14  "execution_time_ms": 8500,
15  "timestamp": "2026-01-15T14:02:00Z"
16}
17
18{
19  "event_type": "session.timeout",
20  "session_id": "sess_abc123def456",
21  "reason": "inactivity_timeout_1800s",
22  "timestamp": "2026-01-15T14:55:00Z"
23}

Устранение неполадок

Сессия закрывается слишком быстро

Увеличьте timeout_seconds при создании сессии. Проверьте, что между командами нет длинных пауз. Используйте PATCH /extend для продления.

Ошибка "max concurrent sessions exceeded"

Закройте ненужные сессии через DELETE /sessions/{id}. На тарифе Free лимит — 2 сессии на агента, Team — 5, Enterprise — 20.

Команда выполняется в другой директории

CWD сохраняется между командами. Если предыдущая команда изменила директорию (cd), следующая выполнится в ней. Используйте абсолютные пути или явно указывайте cwd при вызове.

Агент offline — сессия недоступна

Сессия привязана к агенту. Если агент offline, команды ставятся в очередь (до 60 секунд), затем возвращается ошибка. Сессия не удаляется — она будет доступна при reconnect.

Лучшие практики

Именуйте сессии через metadata

Добавляйте purpose и initiated_by в metadata для идентификации. Это облегчает поиск в audit trail и debug.

Закрывайте сессии явно

Не полагайтесь на таймаут. Явное закрытие (DELETE) освобождает ресурсы и создаёт финальный summary в audit trail.

Используйте absolute paths

Избегайте cd внутри сессии. Используйте абсолютные пути для предотвращения проблем с состоянием CWD.

Минимизируйте env в сессии

Передавайте только необходимые переменные окружения. Не передавайте секреты через env — используйте Secret Store.

Мониторьте открытые сессии

Используйте GET /sessions?status=active для отслеживания. Настройте алерт на зомби-сессии (active, но без команд > 1 часа).

← Monitoring Secrets →

Теги агентов

Форензика

Edit this page