1. Что такое Deck и зачем он нужен

Deck — это developer infrastructure для Computer Use агентов. В отличие от API-интеграций (где нужно, чтобы у сервиса был REST/GraphQL), Deck использует тот же интерфейс, что и человек: видит экран, кликает, вводит текст, проходит 2FA.

2. Установка и первый запуск

2.1 Установка CLI

# macOS / Linux
curl -fsSL https://deck.co/install.sh | bash

# npm (любая платформа)
npm install -g @deckhq/cli

# Проверка
deck --version
deck doctor              # проверка окружения

2.2 Python SDK

pip install deck-sdk

from deck import Deck

# Инициализация клиента
client = Deck(api_key="dk_live_...")  # из dashboard.deck.co

# Проверка соединения
health = client.health()
print(f"Status: {health['status']}, Agents: {health['available_agents']}")

3. Credential Vault — безопасная аутентификация

Credential Vault — ключевая фича Deck. Учётные данные хранятся изолированно per-user и используются агентами для аутентификации в целевом софте. Поддерживаются все факторы: пароли, TOTP, SMS, email-коды, SSO, капчи.

# CLI: создание credential
deck credentials create \
  --name "ADP Payroll Access" \
  --type "username_password" \
  --username "hermes@acme-corp.com" \
  --2fa-method "totp" \
  --2fa-secret "JBSWY3DPEHPK3PXP"

# Python SDK: программное создание
credential = client.credentials.create(
    name="Google Workspace",
    auth_type="oauth2",
    provider="google",
    scopes=["https://www.googleapis.com/auth/spreadsheets"]
)

# CLI: проверить статус
deck credentials list
deck credentials test --name "ADP Payroll Access"

4. Создание Source — подключаем целевой софт

Source — это описание целевого веб-приложения, с которым будет работать агент. Source содержит URL, привязанные credentials и инструкции.

4.1 Google Sheets

# CLI
deck sources create \
  --name "Competitor Research" \
  --url "https://docs.google.com/spreadsheets/d/1ABC" \
  --credential "Google Workspace"

4.2 ADP Payroll (multi-step auth)

# Source с двухфакторной аутентификацией
deck sources create \
  --name "ADP Payroll" \
  --url "https://my.adp.com" \
  --credential "ADP Payroll Access" \
  --auth-flow "multi-step" \
  --auth-steps '["username","password","2fa-totp","company-id"]'

5. Запуск задач — агент в действии

5.1 Простая задача

# CLI: запуск с live-стримингом
deck tasks run \
  --source "Competitor Research" \
  --prompt "Get all rows from 'Pricing 2026' sheet. Extract company, plan, price, features." \
  --output "./competitor-pricing.json" \
  --watch          # live-стриминг: видим каждый шаг агента

5.2 Задача с JSON Schema

Создайте payroll-schema.json:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "pay_runs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "run_id": {"type": "string"},
          "amount": {"type": "number"},
          "status": {"enum": ["Complete", "Pending"]}
        }
      }
    }
  }
}

# Запуск с схемой — строго типизированный JSON на выходе
deck tasks run \
  --source "ADP Payroll" \
  --prompt "Get all pay runs for March 2026" \
  --schema "./payroll-schema.json" \
  --output "./march-payroll.json"

cat ./march-payroll.json
# {"pay_runs":[{"run_id":"PR-065","amount":142800,"status":"Complete"},...]}

6. Масштабирование — сотни агентов параллельно

6.1 Bash: параллельный запуск

# Параллельный запуск 3 агентов для разных sources
for source in "Duke Energy" "ADP Payroll" "Google Sheets"; do
  deck tasks run \
    --source "$source" \
    --output "./output-${source// /-}.json" &
done
wait
echo "All 3 agents complete"

6.2 Python asyncio

import asyncio
from deck import Deck

client = Deck(api_key="dk_live_...")

async def run_agent(source_name, prompt, output_file):
    task = await client.tasks.run(source=source_name, prompt=prompt)
    with open(output_file, 'w') as f:
        json.dump(task.result, f, indent=2)
    return f"{source_name}: done"

async def main():
    tasks = [
        run_agent("ADP Payroll", "Get March pay runs", "payroll.json"),
        run_agent("Duke Energy", "Get Feb statements", "energy.json"),
        run_agent("Google Sheets", "Get competitor data", "competitors.json"),
    ]
    results = await asyncio.gather(*tasks)
    for r in results: print(f"Done: {r}")

asyncio.run(main())

7. Observability — мониторинг агентов

# Live-стриминг сессии
deck tasks run --source "ADP Payroll" --watch

# Вывод:
# [10:23:01] Agent starting — session abc123
# [10:23:04] Navigating to https://my.adp.com
# [10:23:06] 🔐 Authenticating as hermes@acme-corp.com
# [10:23:09] 📱 2FA code requested (TOTP)
# [10:23:12] ✅ Authenticated
# [10:23:15] 📂 Navigating to Payroll → Pay Runs
# [10:23:20] ✅ Task complete — 21 pay runs extracted

# История и replay
deck sessions list --source "ADP Payroll" --limit 10
deck sessions replay --id "abc123"

# Webhook на завершение
deck webhooks create \
  --url "https://your-server.com/deck-events" \
  --events "task.completed,task.failed"

8. Production-развёртывание

DECK_API_KEY=dk_live_...
DECK_WEBHOOK_SECRET=whsec_...

docker run -d \
  -e DECK_API_KEY \
  -v ./tasks:/tasks \
  deckhq/agent-runner

# Ежедневно в 8:00
0 8 * * * deck tasks run \
  --source "Sheet" \
  --output /data/daily.json