AgentCloud

Un plano de control para trabajadores de IA persistentes. Convierte un objetivo en un trabajador versionado, pruébalo sin escrituras, despliégalo en un runtime duradero, exige aprobación humana para acciones sensibles e inspecciona cada decisión en una única línea de tiempo.

Descripción del proyecto · Demo interactiva · Arquitectura · Seguridad · Despliegue · Plan de implementación

[!TIP] La demo completa es determinista y sin credenciales. Utiliza adaptadores simulados de modelo, Gmail, HubSpot, Slack y runtime, mientras ejercita las mismas fronteras de política, aprobación, idempotencia y persistencia que en producción.

Qué hace AgentCloud

La mayoría de las demos de agentes terminan cuando se cierra el chat. AgentCloud trata a un trabajador de IA como un artefacto de software duradero y gobernado:

Related MCP server: GCP MCP Server

Inicio rápido

Requisitos

• Node.js 24 o posterior

• pnpm 11

Instalación y ejecución

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

En PowerShell, sustituye el comando de copia por:

Copy-Item .env.example .env.local

Abre http://localhost:3000. La plantilla de entorno incluida ya habilita los adaptadores de demo seguros, por lo que no se requieren credenciales de base de datos ni de proveedores.

El estado de la demo se persiste en .agentcloud/demo-store.json. El modo demo es explícito y nunca se utiliza como respaldo de producción.

Ejecutar el trabajador canónico

El Inbound Sales Worker incluido demuestra el ciclo de vida gobernado completo:

1. Abre Workers y selecciona Inbound Sales Guardian.

2. Elige Test safely. AgentCloud lee fixtures deterministas de leads y registra las escrituras propuestas sin ejecutarlas.

3. Despliega el trabajador y luego elige Run now.

4. La ejecución cualifica el lead, actualiza el CRM simulado una vez, redacta el borrador de divulgación y se pausa antes de enviar el correo.

5. Abre Approvals, inspecciona la acción redactada exacta y luego elige Approve and view run.

6. La misma ejecución se reanuda desde su punto de control, envía exactamente un correo simulado, publica una notificación simulada de Slack y finaliza con una línea de tiempo completa.

7. Pausa o reanuda el despliegue, crea una nueva versión, despliégala y revierte a una versión inmutable anterior.

La misma secuencia está cubierta a través del MCP de AgentCloud, incluida la reconexión desde un nuevo cliente después de que el cliente iniciador se haya cerrado.

Cómo funciona

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 mantiene el código específico del proveedor detrás de interfaces estrechas:

Esta separación mantiene el ciclo de vida principal portable y hace que la CI sea determinista.

WorkerSpec y autoridad

Un despliegue de trabajador referencia una versión inmutable de WorkerSpec. La especificación define identidad, disparadores, autoridad, presupuestos, política de memoria y comportamiento del runtime sin incrustar credenciales. Este extracto muestra la forma de la autoridad y el presupuesto:

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

El motor de políticas evalúa cada llamada de herramienta contra la especificación fijada. Las capacidades faltantes, las entradas no válidas, los presupuestos excedidos y las operaciones desconocidas fallan de forma cerrada.

Modelo de seguridad

La seguridad se aplica en el código de la aplicación y en la persistencia, no se delega en el prompt del modelo.

Consulta SECURITY.md para el modelo de amenazas completo y los invariantes de seguridad.

MCP

AgentCloud expone un endpoint MCP HTTP de transmisión en:

https://YOUR_DOMAIN/api/mcp

La autenticación MCP de producción utiliza metadatos OAuth de Clerk y membresía de organización. Cada herramienta vuelve a verificar su alcance requerido en el servidor.

Las herramientas de ciclo de vida disponibles incluyen:

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

Alcances OAuth:

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

Las pruebas de protocolo utilizan el cliente MCP oficial en proceso, aplican autenticación y alcances, y verifican que un segundo cliente pueda recuperar trabajadores y ejecuciones persistidos.

Webhooks

Los trabajadores pueden exponer disparadores de webhook firmados en:

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

Las solicitudes requieren:

• X-AgentCloud-Signature: sha256=<hex> calculada a partir del cuerpo sin procesar con WEBHOOK_SIGNING_SECRET

• Una Idempotency-Key estable

• Un cuerpo de no más de 256 KiB

Las solicitudes de webhook están limitadas en velocidad, validadas estructuralmente, limitadas al inquilino y deduplicadas. Reutilizar una clave de idempotencia con un payload diferente se rechaza.

Configuración

AgentCloud tiene dos modos de funcionamiento explícitos:

Comienza con .env.example, que documenta cada variable y su valor predeterminado seguro. Nunca expongas secretos del servidor a través de variables NEXT_PUBLIC_*.

Desarrollo

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

Contrato de validación

La CI ejecuta lo siguiente contra Node.js 24, pnpm 11 y PostgreSQL 16:

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

La matriz de pruebas cubre pruebas unitarias, de integración, de aislamiento de inquilinos, de seguridad en seco, de pausa/reanudación de aprobaciones, de efectos secundarios duplicados, de ciclo de vida MCP, de webhooks firmados, de persistencia de producción y flujos críticos del navegador.

Guía del repositorio

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

Despliegue de producción

Despliega la aplicación web y el runtime desde la misma revisión de Git:

1. Aprovisiona PostgreSQL o Neon y ejecuta las migraciones confirmadas.

2. Configura Clerk Organizations y los alcances OAuth de MCP.

3. Configura Trigger.dev y despliega la tarea del trabajador.

4. Crea configuraciones de autenticación de Gmail, HubSpot y Slack en Composio.

5. Configura OpenAI, la URL de la aplicación y el secreto de firma de webhooks.

6. Despliega la aplicación Next.js en Vercel y luego ejecuta las comprobaciones operativas.

El orden exacto de lanzamiento, las pruebas de humo, el procedimiento de reversión y las comprobaciones dependientes de credenciales están en DEPLOYMENT.md.

[!IMPORTANT] Este repositorio verifica las rutas de código de producción con adaptadores deterministas. No afirma un consentimiento OAuth exitoso del proveedor, ejecución en Trigger.dev Cloud, despliegue en Vercel ni escrituras reales de terceros sin credenciales propiedad del operador.

Estado del proyecto

El MVP independiente de credenciales y todos los hitos en PLAN.md están completos. PROGRESS.md registra el comportamiento implementado y la evidencia de verificación para cada hito.

Las comprobaciones reales de Gmail, HubSpot, Slack, Clerk OAuth, Trigger.dev Cloud, OpenAI y Vercel siguen siendo pasos de despliegue con credenciales del operador. El producto intencionalmente no expone herramientas financieras, destructivas, masivas, MCP arbitrarias, de navegador, de shell ni de código de usuario.

Documentación

• ARCHITECTURE.md — límites, contratos principales, persistencia e independencia del runtime

• SECURITY.md — modelo de amenazas, aislamiento de inquilinos, aprobaciones, efectos secundarios y notificación de vulnerabilidades

• DEPLOYMENT.md — aprovisionamiento de producción, lanzamiento, verificación y reversión

• docs/MCP_REGISTRY.md — puertas OAuth de MCP remoto y publicación de Registry protegida

• docs/LAUNCH_KIT.md — posicionamiento, texto de lanzamiento y el guion verificado de demo de 75 segundos

• CONTRIBUTING.md — flujo de trabajo de desarrollo, salvaguardas de seguridad y expectativas de prueba

• PLAN.md — tesis del producto, diseño técnico, hitos y Definición de Hecho

• PROGRESS.md — puntos de control de hitos e historial de verificación exacto

• .env.example — contrato de configuración completo

Seguridad

No abras una incidencia pública que contenga una vulnerabilidad, una credencial, datos de clientes o un payload de acción sin redactar. Sigue la guía de notificación privada en SECURITY.md.

Licencia

AgentCloud está disponible bajo la Apache License 2.0.