convez.ai
MCP ServerAutomaçãoAvançado
inbharatai

JAK Swarm

inbharatai/jak-swarm

Camada operacional de empresa com orquestração de agentes IA e auditoria integrada

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que funciona como camada operacional de empresa baseada em agentes IA, decompondo objetivos em linguagem natural em planos executáveis, roteando para agentes especialistas e registrando evidência de auditoria. Integra Gemini, Google ADK e GPT com 38 agentes, 122 ferramentas e controles de segurança JAK Shield para aprovações e conformidade (SOC2, HIPAA, ISO27001).

Instalação

$npx convez-ai inbharatai/jak-swarm

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 1 mês
Versão
—
Issues abertas
8
Contribuidores
3

Casos de uso

  • Decomposição automática de objetivos em tarefas roteadas para agentes especialistas
  • Execução de workflows de produto/engenharia com evidência de auditoria e conformidade
  • Sistema de aprovações e segurança para trabalho executado por agentes (JAK Shield)

Veredito

Solução ambiciosa e production-ready para orquestração de agentes em contexto empresarial, com foco em segurança, auditoria e conformidade. Beta ativo com 2156 testes passando e roadmap claro, ideal para equipes que precisam automatizar fluxos complexos com rastreabilidade regulatória.

README

A tradução para o português deste README ainda está na fila.

🐝 JAK

The Closed-Loop Company Operating Layer for Agent Work

JAK Shield Agents Tools Connectors ADK Audit Pack Release Tests TypeScript License

🏆 Google for Startups AI Agents Challenge — Built with Google's Agent Development Kit (ADK) for multi-agent orchestration, uses Gemini 2.5 Pro/Flash/Flash-Lite alongside GPT-5.5/5.4, and integrates Google Search Grounding for real-time, citation-backed responses. Per-tenant provider switching — no code changes, no env-var swaps.

JAK turns scattered company context into approved agent work. JAK Shield makes that work safe.

Give it a goal in plain English. JAK decomposes, routes, executes, and verifies — in real time.

📖 Documentation · ⚖️ License · 🔐 Security · 🏗️ Architecture · 🤖 Agents · ❓ FAQ · 🚀 Quick Start


Challenge Build Status

JAK Swarm is submitted as a working Google AI Agents Challenge build.

The submitted system includes:

  • Gemini-powered mission interpretation, planning, routing, tool calling, and verification
  • ADK-compatible orchestration through the JAK ADK bridge
  • Google Cloud deployment through the JAK API / agent gateway
  • JAK Shield local security, approval, permission, and audit checks
  • live demo access
  • short and long demo videos
  • audit-ready workflow evidence

Post-challenge production hardening roadmap:

  • full Cloud Run worker cutover
  • expanded health and observability endpoints
  • enterprise SLA packaging
  • deeper connector productionization
  • full JAK Shield MCP signed-decision integration for high-risk actions
  • more automated eval coverage

What JAK Swarm Does

JAK Swarm is a Gemini-powered Agentic Business Operating Layer for product and engineering execution. It captures evidence from company artifacts, maps decisions / tasks / risks / owners / customer signals / code changes, detects execution drift, generates agent-executable specs, and routes approved work through 38 specialist agents + 122 classified tools + 22 connectors.

What's unique

  • Evidence graph before agent action — artifacts become graph entities; graph entities become drift findings; drift findings become agent-executable specs. This is the closed-loop Company OS foundation — intentionally citation-first, not chatbot memory. (company-operating-layer.service.ts)
  • One task graph for AI agents AND humans — the CEO writes a prompt; the planner routes some steps to specialist agents (Research, CMO, CTO) and others to teammates ("@anita to sign the contract"). Both flow through the same orchestrator, emit lifecycle events, and feed the signed audit pack. (docs/team-and-trial.md)
  • JAK Shield as the trust gateway — high-risk agent actions are routed through a separate MCP-native 10-stage security gateway (github.com/inbharatai/jak-shield) with local policy enforcement inside Swarm. (docs/jak-shield-manifest.md · docs/EVOLUTION-PLAN.md)
  • Google ADK orchestration — when JAK_ADK_MODE=1, workflows route through Google's Agent Development Kit (@google/adk) using SequentialAgent and ParallelAgent for multi-agent orchestration. Google Search Grounding provides real-time, citation-backed responses. (packages/adk/)
  • Provider-native search without paid APIs — Gemini uses GOOGLE_SEARCH (free, built-in, citation-backed). OpenAI uses web_search_preview (free, native). No Serper, no Tavily, no third-party search API keys needed. API keys are required for OpenAI and Gemini — JAK does not bundle or provide free LLM API keys.
  • 30-day free trial with daily budget caps — sign up at /trial with just an email. No credit card. Four daily caps protect both your data AND your budget.
  • Integrate, don't rebuild — JAK is the cockpit for your existing stack. Gmail, Google Calendar, Slack, GitHub, Notion, browser automation, and MCP surfaces exist in code.

Who it's for

  • Product and engineering teams comparing customer/founder intent with what is actually being built
  • Solo founders and small ops teams who want AI to do real work, not just "give answers"
  • Compliance-aware teams needing tamper-evident agent action trails (SOC 2 / HIPAA / ISO 27001 control mappings shipped — third-party certification not yet; see FAQ)
  • Teams already on Slack / GitHub / Notion / Gmail wanting one place to turn evidence into approved execution

Build scope

This is a working challenge build submitted for the Google AI Agents Challenge. Enterprise SLA packaging, expanded observability, and production hardening are part of the post-challenge roadmap. The current submitted Google Cloud deployment supports the JAK API / agent gateway for live workflows. Full connector auto-sync is an active product build item. The accurate claim is Company OS working challenge foundation, not a finished enterprise product. API keys are required for external LLM providers (Gemini, OpenAI) — JAK does not bundle API keys or provide free LLM access. See docs/beta-release.md for the full scope and go/no-go checklist.


🔮 Google ADK + Grounding

JAK Swarm integrates Google's Agent Development Kit at three layers, each independently activatable and completely additive — the Gemini + ADK orchestration pipeline runs alongside the existing LangGraph pipeline without modifying it.

Layer 1: Google Search Grounding + Vertex AI Search

When LLM_PROVIDER=gemini, the Gemini runtime injects { googleSearch: {} } and optionally { vertex_ai_search: { datastore } } into the Gemini API tools array. Responses include groundingMetadata with web search queries, source URLs, and confidence scores.

For OpenAI, the native web_search_preview hosted tool provides equivalent real-time search — no Serper or Tavily keys needed.

FlagEffect
GEMINI_GOOGLE_SEARCH_GROUNDING=1Enables Google Search grounding in Gemini
GEMINI_VERTEX_AI_SEARCH_DATASTORE=projects/.../dataStores/...Enables Vertex AI Search
OPENAI_WEB_SEARCH=1Enables web_search_preview for OpenAI

Layer 2: ADK Agent Wrappers + Orchestration

When JAK_ADK_MODE=1, workflows route through @google/adk instead of LangGraph:

SequentialAgent(root)
  ├── CommanderAgent          (GOOGLE_SEARCH + JAK tools)
  ├── PlannerAgent            (no tools)
  ├── ParallelAgent(workers)
  │     ├── Worker_CEO        (tools + search)
  │     ├── Worker_CTO        (tools + search)
  │     └── ...               (one per role)
  ├── SynthesisAgent           (merges parallel outputs)
  └── VerifierAgent            (quality assurance)

Provider-native search: Gemini agents use GOOGLE_SEARCH (ADK built-in, free). OpenAI agents use web_search_preview (hosted tool, free).

Key files: packages/adk/ — jak-tool-bridge.ts · jak-adk-agents.ts · adk-pipeline.ts · adk-runner.ts

Provider-Agnostic Guarantee

WhenWhat runs
LLM_PROVIDER=openai (any mode)Existing OpenAI path, zero changes
LLM_PROVIDER=gemini (no flags)Existing GeminiRuntime, no grounding
LLM_PROVIDER=gemini + GEMINI_GOOGLE_SEARCH_GROUNDING=1GeminiRuntime with Google Search grounding
LLM_PROVIDER=gemini + JAK_ADK_MODE=1ADK orchestration with Gemini + grounding

🏗️ How It Works

flowchart TD
    subgraph INPUT["🎤 Input Layer"]
        A["💬 Natural Language Goal"]
        B["🎤 Voice Command"]
    end

    subgraph ORCHESTRATION["🧠 Orchestration Layer"]
        C["🎯 Commander Agent"]
        D["📋 Planner Agent"]
        E["🛡️ Guardrail Agent"]
        F["🔀 Router Agent"]
    end

    subgraph WORKERS["⚡ Worker Layer — 32 Specialists"]
        direction LR
        G["📧 Email  📅 Calendar  👤 CRM"]
        H["📄 Document  📊 Spreadsheet  🌐 Browser"]
        I["🔍 Research  🧠 Knowledge  🎧 Support"]
        J["💻 Coder  🎨 Designer  🚀 Growth"]
        K["⚖️ Legal  💰 Finance  👔 HR"]
    end

    subgraph VERIFY["✅ Quality Layer"]
        M["✅ Verifier Agent"]
        N["⚠️ Approval Gate"]
    end

    subgraph OUTPUT["📊 Output"]
        O["Compiled Result"]
    end

    A --> C
    B --> C
    C --> D --> E
    E -->|"✅ Pass"| F
    E -->|"🚫 Block"| C
    F --> G & H & I & J & K
    G & H & I & J & K --> M
    M -->|"✅ Pass"| O
    M -->|"❌ Fail"| D
    M -->|"⚠️ Risk"| N
    N -->|"👍 Approved"| O
    N -->|"👎 Rejected"| C

Auto-Repair: If the Verifier rejects output, the system re-plans and re-routes failed tasks — no human intervention needed (configurable). Destructive actions are never auto-retried.

See ARCHITECTURE.md for the full system architecture, data model, error handling strategy, and scaling considerations.


🛡️ JAK Shield — The Trust Gateway

JAK Shield is a separate MCP-native security gateway (github.com/inbharatai/jak-shield) with a 10-stage decision pipeline that protects every real-world agent action. JAK Swarm currently enforces JAK Shield-style local policy controls inside packages/security, including guardrails, RBAC, audit logging, and the Agent Governance Overlay that enforces agent profiles, memory scopes, and autonomy boundaries. JAK Shield also exists as a separate MCP-native security gateway, with full signed high-risk action validation planned as a post-challenge hardening step.

JAK Shield 10-stage decision pipeline:

StageWhat it does
1. Hard rulesDeterministic block/allow based on tenant policy
2. Injection v26 substages, 13+ language detection of prompt injection
3. Taint trackerMinHash + n-gram fingerprinting for cross-prompt taint
4. Attack-chain detection20 patterns + data-flow analysis for multi-step attacks
5. PII v228 types (SSN, Aadhaar, IBAN, PAN, NRIC, CPF, CNPJ, etc.) + cryptographic checksums
6. Anomaly detectionEWMA + z-score per tenant/agent for behavioural drift
7. RBAC + thresholdRole, department, and autonomy-level gating
8. OpenAI classifierAdvisory-only second opinion (deterministic engine has final say)
9. HMAC signingCryptographic proof of every security decision
10. Output routingallow · redact · requires_approval · block · rewrite

Local policy enforcement inside JAK Swarm (packages/security):

#DefenseWhat it doesCode
1Agent FirewallBlocks prompt-injection attacks AND offensive-cyber requests before the LLM sees them.offensive-cyber-detector.ts · injection-detector.ts
2Risk-Based ApprovalsEvery tool call classified across the 6-tier ToolRiskLevel lattice. Risky calls pause the workflow. Approval bound to exact payload via SHA-256 hash.approval-policy.ts
3Secure Tool PermissionsPer-tenant tool registry + industry-pack restrictions + Standing Orders (allowed-tools whitelist + blocked-actions list + budget cap + expiry).tenant-tool-registry.ts
4Sandboxed ExecutionBrowser sessions: per-tenant data dirs, 500 MB disk quota, URL allowlist, DNS-rebind defense. Subprocess: literal argv, 60s timeout, stripped env.playwright-browser-operator.ts
5Defensive Vulnerability TriageSupports defensive security work — repo audits, dependency scans, secret-leak detection. Offensive work is blocked at the boundary.offensive-cyber-detector.ts
6Audit Evidence LayerEvery workflow lifecycle event lands in AuditLog. AgentTrace PII-redacted at write time. Evidence bundles HMAC-SHA256 signed. Field-level encryption via field-cipher.ts available for sensitive workflow data.bundle.service.ts · field-cipher.ts

Safety boundary: JAK Shield is built for defensive security, safe automation, permissioned workflows, and audit-ready agent execution. It does not support offensive hacking, malware generation, credential theft, phishing, unauthorized scanning, or exploit generation.

Full manifest: docs/jak-shield-manifest.md. Architecture plan: docs/EVOLUTION-PLAN.md. Security policy: SECURITY.md.


✨ Key Features

FeatureDescription
🤖38 AI Agents6 orchestrators + 32 specialist workers across Executive, Operations, Core, and Vibe Coding layers. Full roster →
🧠Company BrainPer-tenant profile (industry, brand voice, competitors, goals) LLM-extracted from documents → user approves → grounds every agent prompt. Refuses unapproved profiles. UI at /company.
🎯Intent Vocabulary + Templates18 named CompanyOSIntents constrained at the LLM layer via strict Zod schema. 6 system-seeded WorkflowTemplates provide pre-tuned decompositions.
💬Follow-up NL ParserRule-based parser maps short chat inputs to workflow actions: approve, reject, continue, pause, resume, cancel, show graph/cost/failed, "what is the CMO doing?"
🛡️Audit & Compliance PackSOC 2 Type 2 (63) + HIPAA (37) + ISO 27001 (82) = 182 controls seeded. 108 operationally backed, 74 require reviewer attestation. LLM-driven control testing, reviewer-gated workpaper PDFs, HMAC-signed evidence packs, External Auditor Portal. Full details →
🔧122 Classified ToolsEvery tool carries an honest CI-enforced maturity label (real / heuristic / llm_passthrough / config_dependent / experimental). Inventory →
⚡Vibe Coding BuilderDescribe an app → Architect → Generate → 3-layer build check → Debug loop (≤3 retries) → Deploy. Details →
🧠Agent-first RuntimeAll work routes through specialist agents with tier-based model execution. Both OpenAI (GPT-5.5/5.4) and Gemini (2.5 Pro/Flash/Flash-Lite) with per-tenant switching.
🔍Provider-Native SearchGoogle Search Grounding (free, citation-backed) for Gemini. web_search_preview (free, native) for OpenAI. No Serper, no Tavily, no external search API keys required.
🧬ADK OrchestrationGoogle Agent Development Kit (@google/adk) for multi-agent orchestration. SequentialAgent + ParallelAgent pipeline mirrors JAK's DAG. Activated via JAK_ADK_MODE=1.
🧠Memory SystemLLM-powered fact extraction, token-budgeted retrieval injected via <memory> tags. Server-side conversation threads with full history injection into LangGraph state.
🔌MCP IntegrationsSlack, GitHub, Notion wired with provider management. 21 MCP providers auto-mapped. Connector Runtime with honest status badges. Connector docs →
💬Slack + WhatsApp BridgesSlack messages trigger authenticated workflows with HMAC-verified webhooks. WhatsApp control via QR verification.
🎤Voice SessionsOpenAI Realtime API via WebRTC. Optional Deepgram STT / ElevenLabs TTS adapters.
🏢Multi-Tenant SaaSRBAC (5 roles + External Auditor), approval gates, audit logging, tenant isolation. Tenant secrets are protected through environment secret storage, Supabase Vault, and Google Secret Manager where deployed.
💰Credit-Based Billing4 plans (Free / Pro / Team / Enterprise), daily + monthly caps, per-task cost estimation, usage dashboard.
📊Observability35+ Prometheus metrics, OpenTelemetry tracing, per-node cost breakdown, workflow timeline API, /ready readiness endpoint. Additional health and telemetry endpoints are part of the production observability roadmap.
🏗️Distributed ReadyRedis coordination: distributed locks, leader election, cross-instance signals, shared circuit breakers. Worker-lease reclaim: dead workers' jobs auto-recovered in 30s.

🎭 Agent Roster — 38 Agents

graph LR
    subgraph ORCH["🧠 Orchestrators"]
        O1["🎯 Commander"]
        O2["📋 Planner"]
        O3["🔀 Router"]
        O4["✅ Verifier"]
        O5["🛡️ Guardrail"]
        O6["⚠️ Approval"]
    end

    subgraph EXEC["💼 Executive"]
        E1["🎯 Strategist (CEO)"]
        E2["🏗️ Technical (CTO)"]
        E3["💰 Finance (CFO)"]
        E4["📣 Marketing (CMO)"]
        E5["👔 HR"]
        E6["💻 Coder"]
        E7["🎨 Designer"]
        E8["🚀 Growth"]
    end

    subgraph VIBE["⚡ Vibe Coding"]
        V1["🏛️ Architect"]
        V2["⚡ Generator"]
        V3["🔧 Debugger"]
        V4["🚀 Deployer"]
        V5["📸 Screenshot→Code"]
    end

    subgraph OPS["🏢 Operations"]
        P1["✏️ Content"]
        P2["📈 SEO"]
        P3["📰 PR"]
        P4["⚖️ Legal"]
        P5["🤝 Success"]
        P6["📉 Analytics"]
        P7["🗺️ Product"]
        P8["📌 Project"]
    end

    subgraph CORE["⚙️ Core Workers"]
        W1["📧 Email"]
        W2["📅 Calendar"]
        W3["👤 CRM"]
        W4["📄 Doc"]
        W5["📊 Sheet"]
        W6["🌐 Browser"]
        W7["🔍 Research"]
        W8["🧠 Knowledge"]
        W9["🎧 Support"]
        W10["⚙️ Ops"]
        W11["🎤 Voice"]
    end
LayerCountPurpose
🧠 Orchestrators6Parse goals, build DAGs, route tasks, verify quality, enforce guardrails
💼 Executive8CEO/CTO/CFO/CMO-level strategic decisions and specialized expertise
⚡ Vibe Coding5Full-stack app generation — architecture, code, debug, deploy, vision
🏢 Operations8Content, SEO, PR, Legal, Analytics, Product, Project management
⚙️ Core Workers11Email, Calendar, CRM, Browser, Research, Voice, infrastructure tools

Full agent details: AGENTS.md


🧠 LLM Providers & Routing

ProviderModelsUse Case
Gemini2.5 Pro, 2.5 Flash, 2.5 Flash-LiteParallel function calling, controllable thinking, structured output, Google Search Grounding
OpenAIGPT-5.5, GPT-5.4Responses API, strict structured output, prompt-cache-aware telemetry (alternate provider)

Per-tenant provider switching — each tenant chooses Gemini or OpenAI from the Settings UI. The preference flows through TenantMemory → SwarmExecutionService → SwarmRunner → SwarmState → AgentContext.llmProvider → BaseAgent.setContextOverride(). Tenant API keys are protected through environment secret storage, Supabase Vault, and Google Secret Manager where deployed.

Tier-based model selection:

TierGeminiOpenAIAssigned to
💎 PremiumGemini 2.5 ProGPT-5.5Commander, Planner, Verifier, CEO/CMO/CFO
⚡ BalancedGemini 2.5 FlashGPT-5.4Code Generator, Architect, Research
💰 EconomyGemini 2.5 Flash-LiteGPT-5.4Router, Guardrail, simple workers

Provider-native search — no paid search API keys required:

ProviderSearch MethodCostCitations
GeminiGOOGLE_SEARCH (ADK built-in) or googleSearch groundingFree✅ URLs + snippets
OpenAIweb_search_preview hosted toolFree✅ Source URLs

🚀 Quick Start

Prerequisites

RequirementVersion
Node.js20+
pnpm9+
PostgreSQL15+ (pgvector recommended)
RedisOptional (for scheduling + distributed locks)

1. Clone & Install

git clone https://github.com/inbharatai/jak-swarm.git
cd jak-swarm
pnpm install

2. Configure Environment

cp .env.example .env

At minimum set:

# LLM provider (set one or both — per-tenant switching available in the dashboard)
OPENAI_API_KEY=sk-your-openai-key-here
GEMINI_API_KEY=your-gemini-key-here          # Optional: enables Gemini 2.5 Pro/Flash

# Google ADK orchestration (optional — activates ADK multi-agent pipeline)
JAK_ADK_MODE=1                                # Routes workflows through @google/adk
GEMINI_GOOGLE_SEARCH_GROUNDING=1              # Google Search grounding for Gemini
OPENAI_WEB_SEARCH=1                           # Native web_search for OpenAI

DATABASE_URL=postgresql://user:pass@localhost:5432/jak_swarm
AUTH_SECRET=your-random-32-char-string-here
EVIDENCE_SIGNING_SECRET=$(openssl rand -base64 48)

# Supabase (required for production auth)
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

Full reference: docs/environment-setup.md

3. Setup Database

pnpm --filter @jak-swarm/db db:migrate
pnpm --filter @jak-swarm/db db:seed              # optional: seed sample data
pnpm seed:compliance                             # seeds 182 SOC 2 / HIPAA / ISO 27001 controls

4. Build & Run

pnpm turbo build

# Terminal 1 — API server (Fastify, port 4000)
pnpm --filter @jak-swarm/api dev

# Terminal 2 — Web dashboard (Next.js, port 3000)
pnpm --filter @jak-swarm/web dev

Open http://localhost:3000 — give it a goal and watch the swarm execute.

Docker: docker/docker-compose.yml · Production: docker-compose.prod.yml

Deploy to Railway (Rollback Continuity)

Railway remains available as rollback continuity during the challenge window. Google Cloud Run is the primary submitted deployment.

npm i -g @railway/cli
railway link
railway up

See docs/railway-deployment.md for the full Railway runbook.

Deploy to Google Cloud Run

JAK Swarm API is deployed on Google Cloud Run (primary). Railway remains available as rollback continuity during the challenge window.

# Prerequisites: gcloud CLI, billing-enabled GCP project
# See docs/DEPLOYMENT_GOOGLE_CLOUD_RUN.md for full setup

gcloud builds submit --config=cloudbuild-api.yaml
# Worker migration to Cloud Run is part of the post-challenge production hardening roadmap

See docs/DEPLOYMENT_GOOGLE_CLOUD_RUN.md for step-by-step instructions.

Current Deployment Status

JAK Swarm API is currently deployed successfully on Google Cloud Run.

FieldValue
Servicejak-swarm-api
Regionasia-south1
URLhttps://jak-swarm-api-565531938617.asia-south1.run.app
Last deployed byreetu004@gmail.com
Last deployed at2026-06-09T05:50:22Z (≈ 11:20 AM IST)

Verification commands:

gcloud config get-value project

gcloud run services list --platform managed

gcloud run services describe jak-swarm-api \
  --region asia-south1 \
  --format="value(status.url,status.conditions[0].status,status.conditions[0].type)"

curl -i https://jak-swarm-api-565531938617.asia-south1.run.app/health

gcloud run services logs read jak-swarm-api \
  --region asia-south1 \
  --limit=50

Component Status:

ComponentStatus
Cloud Run API (jak-swarm-api)✅ Deployed, accessible through the submitted demo path
Cloud Run Worker (jak-swarm-worker)🔜 Post-challenge hardening roadmap
Supabase PostgreSQL✅ Connected (shared with Railway)
Redis✅ Connected via Railway public endpoint (rediss://, not .railway.internal)
Google Secret Manager✅ Configured, 12 secrets mounted
Vercel NEXT_PUBLIC_API_URL🔜 Points to Railway for challenge accessibility; Cloud Run URL switch planned post-validation

Health Endpoints:

EndpointStatusNotes
/ready✅ PASSPrimary readiness check. Env, DB, Redis, LLM all pass.
/health✅ OperationalDeep diagnostic. Redis OK. Prisma/Supabase pooler has a prepared-statement compatibility note (non-blocking — queries still work).
/healthz🔜 PlannedAdditional health and telemetry endpoints are part of the production observability roadmap. Cloud Run health probes currently use /ready.

Post-Challenge Hardening Items:

  • Wire /healthz as a fast liveness probe (no dependency checks, always returns 200)
  • Resolve /health Prisma prepared-statement note (Supabase pooler session mode or direct URL)
  • Complete Cloud Run Worker migration
  • Switch Vercel NEXT_PUBLIC_API_URL to Cloud Run URL after full validation

Railway as Rollback Continuity:

The frontend remains on Vercel for challenge accessibility. The submitted Google Cloud deployment supports the JAK API / agent gateway path, while Railway remains available as rollback continuity during the challenge window. If Cloud Run has issues, switch NEXT_PUBLIC_API_URL in Vercel back to the Railway URL and redeploy — no code changes needed.

Integration Setup

  1. Enable 2FA → generate an App Password at Google App Passwords
  2. Add to .env: GMAIL_EMAIL="you@gmail.com" + GMAIL_APP_PASSWORD="abcd efgh ijkl mnop"
  3. System auto-detects and switches from mock to real adapters
  1. Create Slack app at api.slack.com/apps → add Bot Token Scopes: channels:read, chat:write, search:read, users:read
  2. Install to workspace → copy Bot User OAuth Token
  3. Dashboard: Settings > Integrations > Slack → paste token + Team ID
  • GitHub: Generate PAT at github.com/settings/tokens (scopes: repo, read:org, read:user) → paste in Settings > Integrations > GitHub
  • Notion: Create integration at notion.so/my-integrations → copy Internal Integration Secret → share pages with integration → paste in Settings > Integrations > Notion

📸 Screenshots

Landing PageAgent Network
HeroAgents
Workflow ExecutionPricing
WorkflowPricing
LoginOnboarding
LoginOnboarding

🖥️ Dashboard Pages

PageDescription
🏠 HomeMission control — activity feed, approvals, quick actions
🏢 WorkspaceCommand center — text/voice input, DAG view, agent tracker
⚡ BuilderVibe Coding IDE — Monaco editor, chat, preview, deploy
🐝 SwarmWorkflow inspector with agent timeline visualization
🛡️ AuditAudit & Compliance home — dashboard, log, reviewer queue, compliance frameworks
🛡️ Audit RunsEngagement detail — control matrix, workpapers, exceptions, final pack
🔎 TracesFull agent trace explorer with token/cost breakdown
📊 AnalyticsUsage metrics, cost tracking, agent performance charts
⏰ SchedulesCron-based recurring workflow management
🔌 IntegrationsMCP provider connections
🧠 KnowledgeMemory store — facts, preferences, policies
⚙️ SettingsLLM provider config, approval thresholds
👑 AdminTenant management, users, API keys, tool toggles
📁 FilesDocument upload, storage, and management
📋 My TasksPersonal task list and assignments
👥 TeamTeam management, departments, member roles
🏢 CompanyCompany profile, brand voice, competitors, goals
📨 InboxNotification center and message feed
📅 CalendarCalendar events and scheduling
💬 SocialSocial media management and drafts
✏️ Social DraftsDraft social media posts for review
🔧 Tool InstallerTool installation and configuration
📜 Standing OrdersPersistent tool allowlists and blocked actions
💡 SkillsReusable workflow templates and skill library
🏃 RunsWorkflow run history and results
💳 BillingSubscription plans, usage, credits

🔧 Tool Inventory (122 Registered)

CategoryCountKey ToolsStatus
Email10read_email, draft_email, send_email, gmail_read_inbox, gmail_send_email, track_email_engagement✅ Real (Gmail IMAP/SMTP)
Calendar3list_calendar_events, create_calendar_event, find_availability✅ Real (CalDAV)
CRM14lookup_crm_contact, update_crm_record, search_deals, enrich_contact, score_lead, predict_churn🔌 Pluggable adapter
Browser30navigate, extract, fill_form, click, screenshot, analyze_page, manage_cookies, evaluate_js, pdf_export✅ Real (Playwright)
Document16summarize_document, extract_document_data, pdf_extract_text, pdf_analyze, generate_report, file_read, file_write✅ Real (pdf-parse + DALL-E)
Research31web_search, web_fetch, classify_text, audit_seo, research_keywords, analyze_serp, code_execute✅ Real (web)
Spreadsheet4parse_spreadsheet, compute_statistics, generate_report, export_csv✅ Built-in
Knowledge9search_knowledge, memory_store, memory_retrieve, ingest_document✅ Real (DB-backed)
Webhook2send_webhook, deploy_to_vercel✅ Built-in
MCPDynamicSlack, GitHub, Notion + 18 more loaded at runtime✅ Real (MCP servers)

Tool maturity labels enforced by CI: pnpm check:truth fails if any tool ships unclassified.


⚖️ How JAK Swarm Compares

FeatureJAK SwarmCrewAILangGraphDevin
Pre-built agents38001
Tools12250+Custom~10
Built-in UI26 pages—LangSmithIDE
Gemini + OpenAI (per-tenant)✅❌❌❌
Google ADK orchestration✅❌❌❌
Google Search Grounding✅❌❌❌
SOC 2 / HIPAA / ISO 27001 audit pack✅❌❌❌
Self-debugging loop✅ 3 retriesLimitedManualLimited
Open source✅ MIT✅ MIT✅ MIT— $20/mo

🔭 Long-Term Vision

JAK is evolving from a multi-agent workflow operator into an ever-learning Company OS that remembers company context, understands departmental roles, and safely completes approved work across the organisation. JAK Shield is the MCP-native trust gateway that protects every real-world agent action.

flowchart TB
    subgraph INPUTS["1. Company Inputs"]
        I1["Calls"] & I2["Meetings"] & I3["Docs"] & I4["Websites"]
        I5["Emails"] & I6["Code"] & I7["Tasks"] & I8["CRM"] & I9["Support"]
    end

    subgraph MEMORY["2. Company Memory Layer"]
        M1["Transcripts"] & M2["Decisions"] & M3["Policies"] & M4["People"]
        M5["Projects"] & M6["Risks"] & M7["Evidence"]
    end

    subgraph INTELLIGENCE["3. Role-Based Intelligence Layer"]
        R1["CEO"] & R2["HR"] & R3["CTO"] & R4["CMO"]
        R5["Finance"] & R6["Legal"] & R7["Ops"] & R8["Support"]
    end

    subgraph PERMISSIONS["4. Permission + Governance Layer"]
        P1["RBAC"] & P2["Dept access"] & P3["Approval gates"]
        P4["Agent Governance Overlay"] & P5["JAK Shield MCP"]
        P6["Audit evidence"] & P7["Autonomy Ladder"]
    end

    subgraph EXECUTION["5. Autonomous Execution Layer"]
        E1["Plan"] & E2["Assign"] & E3["Execute"]
        E4["Verify"] & E5["Report"] & E6["Learn again"]
    end

    INPUTS --> MEMORY --> INTELLIGENCE --> PERMISSIONS --> EXECUTION
    EXECUTION -->|"feedback loop"| MEMORY

Short term (Phase 1-4) — Foundation: Agent Profile Registry, Ability Packs, Thread Model, Company Memory Base, Role-Based Memory Permissions, Marketing OS backend. Security enforced by local policy logic in packages/security.

Medium term (Phase 5-10) — Intelligence + Governance: Commander Coach, Capability Gap Detector, Agent Forge, Evaluation + Learning Loop, Autonomy Ladder (L0-L4 with local policy; L5 deferred). Agent Governance Overlay enforces profiles, scopes, and role boundaries using local policy.

Long term (Phase 11A-11B) — Production Hardening + JAK Shield MCP Integration:

  • Phase 11A: Production hardening, Cloud Run Worker cutover
  • Phase 11B: Full JAK Shield MCP signed-decision integration for high-risk action validation (separate MCP-native gateway at github.com/inbharatai/jak-shield)

Architecture separation: JAK Swarm (Company OS) and JAK Shield (MCP-native trust gateway) are separate products. JAK Shield is independently deployable and auditable. Phase 1-11A uses local policy logic in packages/security. Phase 11B+ adds full JAK Shield MCP signed-decision integration for high-risk actions.

Full roadmap with implementation milestones and honest scope boundaries: docs/ROADMAP.md. Full architecture plan: docs/EVOLUTION-PLAN.md.


🏗️ Tech Stack

LayerTechnology
Monorepopnpm workspaces + Turborepo
LanguageTypeScript 5.7 (strict)
APIFastify
FrontendNext.js 16, React 19, Tailwind CSS
DAG VisualizationReact Flow
DatabasePostgreSQL + Prisma ORM + pgvector
AuthSupabase (email/password + OAuth) + NextAuth
Durable WorkflowsLangGraph StateGraph + PostgresCheckpointSaver
ADK Orchestration@google/adk (SequentialAgent + ParallelAgent)
LLM — OpenAIGPT-5.5 / GPT-5.4 — Responses API, json_schema strict mode
LLM — GeminiGemini 2.5 Pro / Flash / Flash-Lite — parallel function calling, responseSchema, Google Search Grounding
Search — GeminiGOOGLE_SEARCH (ADK built-in) / googleSearch grounding — free, citation-backed
Search — OpenAIweb_search_preview hosted tool — free, native
Browser AutomationPlaywright
Emailimapflow (IMAP) + nodemailer (SMTP)
Calendartsdav (CalDAV)
PDFpdfkit, pdf-parse
External IntegrationsModel Context Protocol (MCP)
TestingVitest
Schema ValidationZod
OpenAPIzod-to-json-schema — auto-generated from Zod schemas

📁 Project Structure

jak-swarm/
├── apps/
│   ├── api/                     # Fastify REST API (port 4000)
│   │   └── src/
│   │       ├── routes/           # Route modules (workflows, approvals, audit, compliance, ...)
│   │       ├── services/         # Business logic (audit, compliance, swarm-execution, ...)
│   │       ├── middleware/       # Auth, RBAC, rate limiting
│   │       └── openapi/         # Zod → JSON Schema → OpenAPI spec
│   └── web/                     # Next.js 16 dashboard (port 3000)
│       └── src/app/(dashboard)/ # 26 dashboard pages
├── packages/
│   ├── adk/                      # 🆕 Google ADK orchestration (JAK_ADK_MODE=1)
│   │   ├── bridge/              # JAK → ADK tool bridge (FunctionTool, GOOGLE_SEARCH)
│   │   ├── agents/              # LlmAgent wrappers for Commander, Planner, Workers, Verifier
│   │   ├── orchestration/       # SequentialAgent + ParallelAgent pipeline + Runner bridge
│   │   └── types/               # Type augmentation for @google/adk v1.2.0
│   ├── agents/                  # 38 agent implementations
│   │   ├── base/                # BaseAgent (decomposed: llm-call, prompt-builder, tool-execution)
│   │   ├── roles/               # 6 orchestrator agents
│   │   ├── workers/             # 32 worker agents
│   │   └── runtime/             # OpenAI + Gemini runtime adapters + grounding config
│   ├── tools/                   # 122 tool implementations
│   │   ├── registry/            # Singleton ToolRegistry + approval policy
│   │   ├── builtin/             # Built-in + sandbox tools
│   │   ├── adapters/            # Email, Calendar, CRM, Browser, Memory
│   │   └── mcp/                 # MCP client + bridge + provider configs
│   ├── swarm/                   # Orchestration engine
│   │   ├── graph/               # LangGraph nodes + task scheduler
│   │   ├── runner/              # SwarmRunner execution loop
│   │   ├── state/               # Immutable SwarmState
│   │   └── supervisor/          # Event bus, circuit breakers, telemetry
│   ├── db/                      # Prisma schema, migrations, seed
│   ├── security/                # Audit logging, RBAC, guardrails, encryption
│   ├── client/                  # @jak-swarm/client TypeScript SDK
│   ├── shared/                  # Shared types, enums, skills parser
│   ├── voice/                   # Voice pipeline (WebRTC, STT, TTS)
│   ├── verification/            # Email/document/transaction verification
│   ├── industry-packs/           # 13 industry-specific agent configurations
│   └── workflows/               # Temporal workflow definitions (optional)
├── tests/
│   ├── unit/                    # Unit tests
│   ├── integration/             # Integration tests
│   └── e2e/                     # End-to-end tests
├── docker/                      # Docker Compose for Postgres, Redis
├── scripts/                     # Dev scripts, doctor, setup
└── docs/                        # Documentation

🔐 Security

Risk LevelExamplesApproval Required
🟢 READ_ONLYweb_search, file_read, list_calendarNever
🟡 DRAFT_ONLYdraft_email, create_calendar_event (uncommitted)Never
🟡 SANDBOX_EDITBrowser ops within sandboxConfigurable
🟠 LOCAL_EXEC_ALLOWLISTCode execution, file write (allowlisted tools)Configurable
🟠 EXTERNAL_ACTION_APPROVALsend_email, send_webhook, post_slackAlways
🔴 CRITICAL_MANUAL_ONLYdelete records, credential rotation, production deploysAlways
  • AES-256-GCM field-level encryption available for sensitive workflow data; tenant secrets are protected through environment secret storage, Supabase Vault, and Google Secret Manager where deployed
  • JWT auth with per-tenant isolation enforced at middleware level
  • bcrypt password hashing (12 rounds)
  • PII redaction at LLM boundary and at write time
  • 5-layer hallucination detection (heuristic/regex-based) on every agent output: grounding check, invented statistics, fabricated sources, overconfidence, impossible claims
  • RBAC roles: END_USER < REVIEWER < OPERATOR < TENANT_ADMIN < SYSTEM_ADMIN + EXTERNAL_AUDITOR

Full security policy: SECURITY.md


🛠️ Development

pnpm test                  # Run all tests (2156 passing)
pnpm typecheck             # Type checking (strict mode, zero errors)
pnpm lint                  # Lint
pnpm check:truth           # Verify tool classifications + landing claims
pnpm audit:tools           # Audit all 122 tools against registry

# Run specific package tests
pnpm --filter @jak-swarm/agents test
pnpm --filter @jak-swarm/tools test
pnpm --filter @jak-swarm/swarm test
pnpm --filter @jak-swarm/adk test

Adding a New Agent

  1. Create packages/agents/src/workers/your-agent.ts (follow growth.agent.ts pattern)
  2. Export from packages/agents/src/index.ts
  3. Add AgentRole.WORKER_YOUR_ROLE to packages/shared/src/types/agent.ts
  4. Add case to createWorkerAgent() in packages/swarm/src/graph/nodes/worker/agent-factory.ts
  5. Add case to buildTaskInput() in packages/swarm/src/graph/nodes/worker/task-input-builders.ts
  6. Add infer*Action() in packages/swarm/src/graph/nodes/worker/intent-inference/text.ts
  7. Add role description to packages/agents/src/roles/planner.agent.ts
  8. Run pnpm turbo build to verify

Adding a New Tool

  1. Add toolRegistry.register(metadata, executor) in packages/tools/src/builtin/index.ts
  2. Define inputSchema / outputSchema (JSON Schema)
  3. Set riskClass (READ_ONLY → CRITICAL_MANUAL_ONLY) and maturity label
  4. Run pnpm turbo build to verify

Adding a New LLM Provider

Follow the GeminiRuntime adapter pattern: create a runtime adapter that converts message shapes, map tool definitions, and translate responses back. Wire it through BaseAgent.setContextOverride(). See gemini-runtime.ts as reference.

Using Google ADK Orchestration

Set JAK_ADK_MODE=1 in your .env. Workflows will route through @google/adk's SequentialAgent + ParallelAgent pipeline instead of LangGraph. Falls back to LangGraph on ADK error. See packages/adk/ for architecture details.


📚 Documentation

DocDescription
ARCHITECTURE.mdFull system architecture, data model, error handling, scaling
AGENTS.mdEvery agent role: purpose, input/output contracts, handoff logic
SECURITY.mdVulnerability reporting, SLA, scope, cryptographic assumptions
docs/jak-shield-manifest.mdLocal policy defenses (claim-to-code mapping) — JAK Shield is a separate 10-stage MCP gateway (github.com/inbharatai/jak-shield)
docs/audit-compliance-agent-pack.mdAudit & Compliance product overview
docs/audit-framework-library.mdPer-framework + per-control reference (SOC 2, HIPAA, ISO 27001)
docs/audit-api.mdAudit endpoint reference + error codes + SSE channel
docs/audit-workpapers.mdWorkpaper generation + approval flow
docs/beta-release.mdBeta scope, go/no-go checklist, production readiness
docs/team-and-trial.mdTeam hierarchy, free trial, daily caps
docs/connector-runtime.mdConnector Runtime design + phase status
docs/vibe-coding.mdVibe Coding pipeline, cost tables, feature comparison
docs/faq.mdFull FAQ — product, trial, security, integrations, costs
docs/api-reference.mdComplete API endpoint reference
docs/DEPLOYMENT_GOOGLE_CLOUD_RUN.mdGoogle Cloud Run deployment guide for live API and pending Worker rollout
docs/environment-setup.mdEnvironment variables, integration setup, troubleshooting
docs/agent-run-cockpit.mdCockpit audit event vocabulary
docs/competitive-positioning.mdMarket positioning analysis
docs/ROADMAP.mdLong-term vision, 5-layer Company OS evolution, honest scope boundaries
docs/EVOLUTION-PLAN.mdNext-evolution architecture — JAK Shield MCP integration, Agent Governance Overlay, Company Memory, Agent Forge, Commander Coach, Ability Packs, Autonomy Ladder, 11-phase implementation roadmap

❓ Common Questions

This is a working challenge build. The architecture is solid (LangGraph + ADK + Postgres checkpointer + signed evidence bundles + JAK Shield local policy controls). 2,156 unit/structural tests passing. Zero TypeScript errors under strict mode.

Enterprise SLA packaging, expanded observability, and production hardening are part of the post-challenge roadmap. Specific items on that roadmap: live-hosted smoke tests, third-party security audit/certification, lawyer-reviewed ToS/DPA, pen test, AuditLog row chain-hashing, and incident-response runbook.

Full checklist: docs/beta-release.md.

No. The infrastructure is shipped (182 controls seeded, 108 operationally backed, HMAC-signed evidence bundles, External Auditor Portal) — everything an external auditor needs. The actual third-party attestation has not happened. We deliberately avoid phrases that imply certification we don't have.

Yes. MIT-licensed, the code is here. Docker for Postgres + Redis, an API key, Node 20+, pnpm 9+. No cloud-only feature — the same code that runs at jakswarm.com is what you self-host.

Google's Agent Development Kit (@google/adk) provides SequentialAgent, ParallelAgent, and LlmAgent primitives for building multi-agent workflows. When JAK_ADK_MODE=1, JAK routes workflows through ADK's orchestration instead of LangGraph. The output shape is identical (SwarmState) so persistence, SSE, and approval flows work unchanged. ADK's built-in GOOGLE_SEARCH tool provides free, citation-backed web search for Gemini agents.

No. When GEMINI_GOOGLE_SEARCH_GROUNDING=1, Gemini agents use Google Search Grounding (free, built-in). When OPENAI_WEB_SEARCH=1, OpenAI agents use web_search_preview (free, native). Both provide real-time web search without any external search API keys. If neither flag is set, JAK falls back to its built-in web_search tool (which can optionally use Serper for enhanced results).

Full FAQ: docs/faq.md


📄 License

MIT — free for commercial and personal use. See LICENSE.


Built with ❤️ by InBharat AI

Website · Quick Start · Architecture · Security · FAQ

GitHub stars Twitter Follow

Ver o original no GitHub

Bom para

Relacionados