AgentCloud

Eine Kontrollebene für dauerhafte KI-Arbeiter. Verwandle ein Ziel in einen versionierten Worker, teste ihn ohne Schreibzugriffe, stelle ihn auf einer langlebigen Laufzeitumgebung bereit, verlange menschliche Genehmigung für sensible Aktionen und prüfe jede Entscheidung in einer einzigen Zeitleiste.

Projektübersicht · Interaktive Demo · Architektur · Sicherheit · Bereitstellung · Umsetzungsplan

[!TIP] Die vollständige Demo ist deterministisch und ohne Anmeldedaten. Sie verwendet Fake-Modell-, Gmail-, HubSpot-, Slack- und Laufzeit-Adapter, während sie dieselben Richtlinien-, Genehmigungs-, Idempotenz- und Persistenzgrenzen wie die Produktion anwendet.

Was AgentCloud leistet

Die meisten Agent-Demos enden, wenn der Chat geschlossen wird. AgentCloud behandelt einen KI-Arbeiter als dauerhaftes, verwaltetes Software-Artefakt:

Related MCP server: GCP MCP Server

Schnellstart

Voraussetzungen

• Node.js 24 oder neuer

• pnpm 11

Installieren und ausführen

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

Ersetzen Sie unter PowerShell den Kopierbefehl durch:

Copy-Item .env.example .env.local

Öffnen Sie http://localhost:3000. Die eingecheckte Umgebungsvorlage aktiviert bereits die sicheren Demo-Adapter, sodass keine Datenbank- oder Anbieter-Anmeldedaten erforderlich sind.

Der Demo-Zustand wird in .agentcloud/demo-store.json gespeichert. Der Demo-Modus ist explizit und wird niemals als Produktions-Fallback verwendet.

Den kanonischen Worker ausführen

Der enthaltene Inbound-Sales-Worker demonstriert den vollständigen verwalteten Lebenszyklus:

1. Öffnen Sie Workers und wählen Sie Inbound Sales Guardian.

2. Wählen Sie Sicher testen. AgentCloud liest deterministische Lead-Fixtures und protokolliert vorgeschlagene Schreibzugriffe, ohne sie auszuführen.

3. Stellen Sie den Worker bereit und wählen Sie dann Jetzt ausführen.

4. Der Lauf qualifiziert den Lead, aktualisiert das Fake-CRM einmal, entwirft die Kontaktaufnahme und pausiert vor dem Senden der E-Mail.

5. Öffnen Sie Genehmigungen, prüfen Sie die genaue redigierte Aktion und wählen Sie dann Genehmigen und Lauf anzeigen.

6. Derselbe Lauf wird von seinem Checkpoint fortgesetzt, sendet genau eine Fake-E-Mail, postet eine Fake-Slack-Benachrichtigung und endet mit einer vollständigen Zeitleiste.

7. Pausieren oder setzen Sie die Bereitstellung fort, erstellen Sie eine neue Version, stellen Sie sie bereit und setzen Sie auf eine frühere unveränderliche Version zurück.

Derselbe Ablauf wird über das AgentCloud-MCP abgedeckt, einschließlich der Wiederverbindung von einem neuen Client, nachdem der auslösende Client geschlossen wurde.

So funktioniert es

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 hält anbieterspezifischen Code hinter schmalen Schnittstellen:

Diese Trennung hält den Kernlebenszyklus portabel und macht CI deterministisch.

WorkerSpec und Autorität

Eine Worker-Bereitstellung referenziert eine unveränderliche WorkerSpec-Version. Die Spezifikation definiert Identität, Trigger, Autorität, Budgets, Speicherrichtlinie und Laufzeitverhalten, ohne Anmeldedaten einzubetten. Dieser Auszug zeigt die Form von Autorität und Budget:

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

Die Richtlinien-Engine prüft jeden Tool-Aufruf gegen die fixierte Spezifikation. Fehlende Fähigkeiten, ungültige Eingaben, überschrittene Budgets und unbekannte Operationen schlagen fehl (Fail-Closed).

Sicherheitsmodell

Sicherheit wird im Anwendungscode und in der Persistenz durchgesetzt – nicht an das Modell-Prompt delegiert.

Siehe SECURITY.md für das vollständige Bedrohungsmodell und die Sicherheitsinvarianten.

MCP

AgentCloud stellt einen Streamable-HTTP-MCP-Endpunkt bereit unter:

https://YOUR_DOMAIN/api/mcp

Die MCP-Authentifizierung in der Produktion verwendet Clerk-OAuth-Metadaten und Organisationsmitgliedschaft. Jedes Tool prüft seinen erforderlichen Umfang serverseitig erneut.

Verfügbare Lebenszyklus-Tools:

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-Umfang:

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

Die Protokolltests verwenden den offiziellen MCP-Client im Prozess, erzwingen Authentifizierung und Umfang und verifizieren, dass ein zweiter Client persistierte Worker und Läufe wiederherstellen kann.

Webhooks

Worker können signierte Webhook-Trigger bereitstellen unter:

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

Anfragen erfordern:

• X-AgentCloud-Signature: sha256=<hex>, berechnet aus dem Roh-Body mit WEBHOOK_SIGNING_SECRET

• Einen stabilen Idempotency-Key

• Einen Body von höchstens 256 KiB

Webhook-Anfragen werden ratenbegrenzt, strukturell validiert, mandantenbezogen und dedupliziert. Die Wiederverwendung eines Idempotenzschlüssels mit einer anderen Nutzlast wird abgelehnt.

Konfiguration

AgentCloud hat zwei explizite Betriebsmodi:

Beginnen Sie mit .env.example, das jede Variable und ihren sicheren Standardwert dokumentiert. Setzen Sie Serversecrets niemals über NEXT_PUBLIC_*-Variablen ein.

Entwicklung

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

Validierungsvertrag

CI führt Folgendes gegen Node.js 24, pnpm 11 und PostgreSQL 16 aus:

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

Die Testmatrix deckt Unit-, Integrations-, Mandanten-Isolations-, Trockenlauf-Sicherheits-, Genehmigungs-Pause/Fortsetzungs-, Duplikat-Nebenwirkungs-, MCP-Lebenszyklus-, signierte-Webhook-, Produktionspersistenz- und kritische Browserabläufe ab.

Repository-Anleitung

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

Produktionsbereitstellung

Stellen Sie die Webanwendung und die Laufzeitumgebung aus derselben Git-Revision bereit:

1. Stellen Sie PostgreSQL oder Neon bereit und führen Sie die eingecheckten Migrationen aus.

2. Konfigurieren Sie Clerk-Organisationen und MCP-OAuth-Umfänge.

3. Konfigurieren Sie Trigger.dev und stellen Sie die Worker-Aufgabe bereit.

4. Erstellen Sie Composio-Gmail-, HubSpot- und Slack-Authentifizierungskonfigurationen.

5. Konfigurieren Sie OpenAI, die Anwendungs-URL und den Webhook-Signaturschlüssel.

6. Stellen Sie die Next.js-Anwendung auf Vercel bereit und führen Sie dann die Betriebsprüfungen aus.

Die genaue Release-Reihenfolge, Smoke-Tests, Rollback-Verfahren und anmeldedatenabhängige Prüfungen finden Sie in DEPLOYMENT.md.

[!IMPORTANT] Dieses Repository verifiziert Produktionscodepfade mit deterministischen Adaptern. Es beansprucht keine erfolgreiche Anbieter-OAuth-Einwilligung, Trigger.dev-Cloud-Ausführung, Vercel-Bereitstellung oder echte Drittanbieter-Schreibzugriffe ohne anbietereigene Anmeldedaten.

Projektstatus

Das anmeldedatenunabhängige MVP und alle Meilensteine in PLAN.md sind abgeschlossen. PROGRESS.md dokumentiert die implementierten Verhaltensweisen und Verifikationsnachweise für jeden Meilenstein.

Echte Gmail-, HubSpot-, Slack-, Clerk-OAuth-, Trigger.dev-Cloud-, OpenAI- und Vercel-Prüfungen bleiben anbietergenehmigte Bereitstellungsschritte. Das Produkt stellt bewusst keine finanziellen, destruktiven, Massen-, beliebigen MCP-, Browser-, Shell- oder Benutzercode-Tools bereit.

Dokumentation

• ARCHITECTURE.md — Grenzen, Kernverträge, Persistenz und Laufzeitunabhängigkeit

• SECURITY.md — Bedrohungsmodell, Mandanten-Isolation, Genehmigungen, Nebenwirkungen und Schwachstellenmeldung

• DEPLOYMENT.md — Produktionsbereitstellung, Release, Verifikation und Rollback

• docs/MCP_REGISTRY.md — Remote-MCP-OAuth-Gates und geschützte Registry-Veröffentlichung

• docs/LAUNCH_KIT.md — Positionierung, Launch-Texte und das verifizierte 75-Sekunden-Demoskript

• CONTRIBUTING.md — Entwicklungsworkflow, Sicherheitsleitplanken und Testerwartungen

• PLAN.md — Produktthese, technisches Design, Meilensteine und Definition of Done

• PROGRESS.md — Meilenstein-Checkpoints und genaue Verifikationshistorie

• .env.example — vollständiger Konfigurationsvertrag

Sicherheit

Öffnen Sie kein öffentliches Issue, das eine Schwachstelle, Zugangsdaten, Kundendaten oder eine nicht geschwärzte Aktions-Payload enthält. Befolgen Sie die Anleitung zur privaten Meldung in SECURITY.md.

Lizenz

AgentCloud ist unter der Apache License 2.0 verfügbar.