AgentCloud

Плоскость управления для постоянных ИИ-воркеров. Превратите цель в версионированного воркера, протестируйте его без записи, разверните в долговечной среде выполнения, требуйте одобрения человека для чувствительных действий и просматривайте каждое решение в единой временной шкале.

Обзор проекта · Интерактивное демо · Архитектура · Безопасность · Развертывание · План реализации

[!TIP] Полное демо детерминировано и не требует учетных данных. Оно использует фейковые адаптеры модели, Gmail, HubSpot, Slack и среды выполнения, при этом соблюдая те же границы политик, одобрений, идемпотентности и персистентности, что и в продакшене.

Что делает AgentCloud

Большинство демо агентов заканчиваются, когда чат закрывается. AgentCloud рассматривает ИИ-воркера как долговечный управляемый программный артефакт:

Related MCP server: GCP MCP Server

Быстрый старт

Требования

• Node.js 24 или новее

• pnpm 11

Установка и запуск

git clone https://github.com/premhiru/agentcloud.git
cd agentcloud
pnpm install
cp .env.example .env.local
pnpm dev

В PowerShell замените команду копирования на:

Copy-Item .env.example .env.local

Откройте http://localhost:3000. Включенный в репозиторий шаблон окружения уже включает безопасные демо-адаптеры, поэтому база данных или учетные данные вендоров не требуются.

Состояние демо сохраняется в .agentcloud/demo-store.json. Демо-режим явный и никогда не используется как запасной вариант для продакшена.

Запуск канонического воркера

Включенный Inbound Sales Worker демонстрирует полный управляемый жизненный цикл:

1. Откройте Workers и выберите Inbound Sales Guardian.

2. Выберите Test safely. AgentCloud читает детерминированные фикстуры лидов и записывает предлагаемые записи без их выполнения.

3. Разверните воркера, затем выберите Run now.

4. Запуск квалифицирует лида, один раз обновляет фейковую CRM, готовит черновик обращения и приостанавливается перед отправкой электронного письма.

5. Откройте Approvals, проверьте точное отредактированное действие, затем выберите Approve and view run.

6. Тот же запуск возобновляется с контрольной точки, отправляет ровно одно фейковое письмо, публикует одно фейковое уведомление в Slack и завершается полной временной шкалой.

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

Та же последовательность доступна через MCP AgentCloud, включая переподключение с нового клиента после закрытия инициирующего клиента.

Как это работает

Dashboard · MCP · Signed webhooks
                │
                ▼
      AgentCloud control plane
                │
     ┌──────────┼──────────┐
     ▼          ▼          ▼
 WorkerSpec   Policy     Budgets
 versions     engine     and usage
     │          │          │
     └──────────┼──────────┘
                ▼
        Governed worker runner
                │
      ┌─────────┴─────────┐
      ▼                   ▼
 WorkerRuntime     IntegrationAdapter
 Fake / Trigger.dev  Fake / Composio
                │
                ▼
 PostgreSQL · approvals · timelines · audit

AgentCloud держит код, специфичный для вендоров, за узкими интерфейсами:

Такое разделение сохраняет переносимость основного жизненного цикла и делает CI детерминированным.

WorkerSpec и полномочия

Развертывание воркера ссылается на неизменяемую версию WorkerSpec. Спецификация определяет идентичность, триггеры, полномочия, бюджеты, политику памяти и поведение среды выполнения без встраивания учетных данных. Этот фрагмент показывает форму полномочий и бюджета:

schemaVersion: "1.0"
identity:
  name: Inbound Sales Guardian
capabilities:
  - capability: gmail.search_messages
  - capability: hubspot.upsert_contact
  - capability: gmail.send_email
authority:
  defaultEffect: deny
  rules:
    - capability: gmail.search_messages
      effect: allow
    - capability: hubspot.upsert_contact
      effect: allow
    - capability: gmail.send_email
      effect: require_approval
budget:
  monthlyUsd: 50
  perRunUsd: 1
  maxModelCallsPerRun: 12
  maxToolCallsPerRun: 30

Движок политик оценивает каждый вызов инструмента относительно закрепленной спецификации. Отсутствующие возможности, недопустимые входные данные, превышенные бюджеты и неизвестные операции завершаются с отказом.

Модель безопасности

Безопасность обеспечивается в коде приложения и персистентности — а не делегируется промпту модели.

Полную модель угроз и инварианты безопасности см. в SECURITY.md.

MCP

AgentCloud предоставляет конечную точку MCP Streamable HTTP по адресу:

https://YOUR_DOMAIN/api/mcp

Аутентификация MCP в продакшене использует метаданные OAuth Clerk и членство в организации. Каждый инструмент повторно проверяет требуемую область действия на стороне сервера.

Доступные инструменты жизненного цикла включают:

create_worker       update_worker       test_worker
deploy_worker       trigger_worker      cancel_run
get_run             list_runs           list_approvals
approve_action      reject_action       pause_worker
resume_worker       list_worker_versions rollback_worker
get_usage           list_connections    delete_worker

Области OAuth:

workers:read        workers:write       workers:deploy
runs:read           approvals:read      approvals:write
connections:read

Протокольные тесты используют официальный MCP-клиент в процессе, обеспечивают аутентификацию и области действия и проверяют, что второй клиент может восстановить сохраненные воркеры и запуски.

Вебхуки

Воркеры могут предоставлять подписанные вебхук-триггеры по адресу:

POST /api/webhooks/workers/{workerId}/{triggerKey}

Запросы требуют:

• X-AgentCloud-Signature: sha256=<hex>, вычисленный из необработанного тела с помощью WEBHOOK_SIGNING_SECRET

• Стабильный Idempotency-Key

• Тело размером не более 256 КиБ

Вебхук-запросы ограничиваются по частоте, проверяются структурно, ограничиваются тенантом и дедуплицируются. Повторное использование ключа идемпотентности с другим полезным грузом отклоняется.

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

AgentCloud имеет два явных режима работы:

Начните с .env.example, который документирует каждую переменную и ее безопасное значение по умолчанию. Никогда не раскрывайте серверные секреты через переменные NEXT_PUBLIC_*.

Разработка

pnpm dev               # Next.js development server
pnpm lint              # ESLint with zero warnings
pnpm typecheck         # strict TypeScript
pnpm test              # full Vitest suite
pnpm test:unit         # domain and adapter tests
pnpm test:integration  # persistence and lifecycle tests
pnpm test:security     # product safety invariants
pnpm test:mcp          # authenticated MCP lifecycle
pnpm test:e2e          # critical Playwright journeys
pnpm build             # optimized production build
pnpm db:migrate        # apply committed migrations
pnpm db:seed           # seed a local tenant
pnpm trigger:dev       # Trigger.dev local task runner
pnpm trigger:deploy    # deploy Trigger.dev tasks

Контракт валидации

CI выполняет следующее на Node.js 24, pnpm 11 и PostgreSQL 16:

pnpm install --frozen-lockfile
pnpm db:migrate
pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm test:e2e

Матрица тестов покрывает модульные, интеграционные, изоляцию тенантов, безопасность пробного режима, паузу/возобновление одобрений, дублирование побочных эффектов, жизненный цикл MCP, подписанные вебхуки, продакшен-персистентность и критические браузерные сценарии.

Гид по репозиторию

src/
  application/       control plane and durable demo store
  domain/            WorkerSpec, versions, policy, budgets
  runtime/           governed runner and runtime adapters
  integrations/      tool registry and integration adapters
  approvals/         approval hashing, decisions, and waitpoints
  persistence/       PostgreSQL repositories and audit records
  mcp/               authenticated MCP server and tool service
  app/               dashboard, API, MCP, and webhook routes
tests/
  unit/              domain contracts
  integration/       persistence and lifecycle boundaries
  security/          non-negotiable product invariants
  mcp/               protocol-level lifecycle tests
  e2e/               Playwright user journeys
trigger/              Trigger.dev durable task entrypoint
agentcloud-site/      companion product site

Продакшен-развертывание

Разверните веб-приложение и среду выполнения из одной и той же ревизии Git:

1. Подготовьте PostgreSQL или Neon и выполните зафиксированные миграции.

2. Настройте Clerk Organizations и области OAuth MCP.

3. Настройте Trigger.dev и разверните задачу воркера.

4. Создайте конфигурации аутентификации Composio для Gmail, HubSpot и Slack.

5. Настройте OpenAI, URL приложения и секрет подписи вебхуков.

6. Разверните приложение Next.js на Vercel, затем выполните операционные проверки.

Точный порядок релиза, смоук-тесты, процедура отката и проверки, зависящие от учетных данных, описаны в DEPLOYMENT.md.

[!IMPORTANT] Этот репозиторий проверяет продакшен-пути кода с помощью детерминированных адаптеров. Он не заявляет об успешном согласии OAuth вендоров, выполнении в Trigger.dev Cloud, развертывании на Vercel или реальных записях сторонних систем без учетных данных, принадлежащих оператору.

Статус проекта

Независимый от учетных данных MVP и все вехи из PLAN.md завершены. PROGRESS.md фиксирует реализованное поведение и доказательства проверки для каждой вехи.

Реальные проверки Gmail, HubSpot, Slack, Clerk OAuth, Trigger.dev Cloud, OpenAI и Vercel остаются шагами развертывания с учетными данными оператора. Продукт намеренно не предоставляет финансовые, разрушительные, массовые, произвольные MCP, браузерные, шелл или пользовательские инструменты.

Документация

• ARCHITECTURE.md — границы, основные контракты, персистентность и независимость среды выполнения

• SECURITY.md — модель угроз, изоляция тенантов, одобрения, побочные эффекты и отчеты об уязвимостях

• DEPLOYMENT.md — продакшен-подготовка, релиз, проверка и откат

• docs/MCP_REGISTRY.md — удаленные OAuth-шлюзы MCP и защищенная публикация в Registry

• docs/LAUNCH_KIT.md — позиционирование, тексты для запуска и проверенный сценарий демо на 75 секунд

• CONTRIBUTING.md — рабочий процесс разработки, защитные ограждения и ожидания от тестов

• PLAN.md — тезис продукта, технический дизайн, вехи и определение готовности

• PROGRESS.md — контрольные точки вех и точная история проверок

• .env.example — полный контракт конфигурации

Безопасность

Не открывайте публичный issue, содержащий уязвимость, учетные данные, данные клиентов или неотредактированную полезную нагрузку действия. Следуйте руководству по приватному сообщению в SECURITY.md.

Лицензия

AgentCloud доступен под Apache License 2.0.