# Synapse AI — Multi-Agent Orchestration Platform

> Open-source, production-grade platform for building deterministic multi-agent AI workflows with a visual DAG builder, 14+ LLM providers, real tool servers, and human-in-the-loop support.

Synapse AI (version 1.6.5) is a complete platform for running AI agents in production. It goes beyond LLM libraries: you get a visual DAG (Directed Acyclic Graph) builder, 14 typed step types (including zero-LLM control-flow steps like IF_ELSE, SWITCH, and EXTRACT_JSON), four agent types (Conversational, Code, Orchestrator, Delegate), native tool servers, built-in MCP server support, a 3-layer caching system (prompt / tool / response), and messaging integrations with 5 platforms — all with strict deterministic execution and per-step cost controls. Runs fully locally via Ollama or local HuggingFace transformers, or against any cloud LLM. AGPL-3.0 licensed and free to use.

Homepage: https://synapseorch.com
GitHub: https://github.com/synapseorch-ai/synapse-ai
Discord: https://discord.gg/9UN45qyGh8
PyPI: synapse-orch-ai
npm: synapse-orch-ai
Version: 1.6.5
License: AGPL-3.0-only
Requirements: Python 3.11+, Node.js 22+

---

## Installation

```bash
# macOS / Linux
curl -sSL https://raw.githubusercontent.com/synapseorch-ai/synapse-ai/main/setup.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/synapseorch-ai/synapse-ai/main/setup.ps1 | iex

# npm
npm install -g synapse-orch-ai && synapse

# pip
pip install synapse-orch-ai && synapse
```

### CLI Commands
- `synapse start` — start backend + frontend, open browser
- `synapse stop` — stop background processes
- `synapse upgrade` — upgrade to latest version
- `synapse setup` — interactive wizard for API keys
- `synapse status` — show running processes
- `synapse restart` — restart both servers
- `synapse uninstall` — remove Synapse entirely

---

## LLM Provider Support (14+)

Each workflow step can use a different LLM provider and model. No vendor lock-in.

### Cloud Providers
| Provider | Model Prefix | Examples |
|---|---|---|
| Anthropic (Claude) | `claude-` | Claude 3.5 Sonnet, Claude 3 Opus, Claude 3.7 Sonnet |
| OpenAI | `gpt-` | GPT-4o, GPT-4 Turbo, o1, o3-mini |
| Google Gemini | `gemini-` / `gemma-` | Gemini 1.5 Pro, Gemini 2.0 Flash, Gemma models |
| xAI (Grok) | `grok-` | Grok-2, Grok-3, Grok-3 Mini |
| DeepSeek | `deepseek-` | DeepSeek-V3, DeepSeek-R1 (reasoning model) |
| AWS Bedrock | `bedrock.` | Any Bedrock model via the Converse API |

### Local & Compatible Providers
| Provider | Model Prefix | Description |
|---|---|---|
| Ollama | *(bare model name)* | Any model pulled via `ollama pull`; fully offline |
| HuggingFace (local transformers) | `hf.<org>/<model>` | Runs locally via `torch` + `transformers` (optional install). Example: `hf.Qwen/Qwen2.5-7B-Instruct`. Gated models (Llama, Gemma) require `huggingface_token`. Generation length configurable via `huggingface_max_new_tokens` (default 1024). |
| OpenAI-Compatible (cloud) | `oaic.<model>` | OpenRouter, Together AI, Fireworks, Replicate — configure base URL + key |
| OpenAI-Compatible (local) | `locv1.<model>` | vLLM, LM Studio, Jan, Ollama `/v1` endpoint |

### CLI Providers (no API key — uses existing subscriptions)
| Provider | Prefix | Auth |
|---|---|---|
| Claude Code CLI | `cli.claude` | Installed `claude` CLI |
| Gemini CLI | `cli.gemini` | Installed `gemini` CLI |
| Codex CLI | `cli.codex` | Installed `codex` CLI |
| GitHub Copilot CLI | `cli.copilot` | GitHub Copilot subscription |

---

## Step Types (14 total)

Each node in a Synapse DAG is one of 14 typed steps. Four of them (Transform, Extract JSON, If/Else, Switch) are zero-LLM — they branch, reshape, and route data without spending tokens.

| Step | Purpose |
|---|---|
| **Agent** | Full ReAct reasoning loop with tool calling; reads from and writes to shared state |
| **LLM** | Direct LLM call without agent reasoning; fast and cheap; supports `{state.key}` prompt templates |
| **Tool** | Execute a specific MCP tool directly; no reasoning loop; deterministic |
| **Evaluator** | LLM-based classifier that routes to the next step based on a labeled decision (e.g., "approved" → publish); supports per-route descriptions and a dedicated `evaluator_prompt` |
| **Parallel** | Fan out to multiple simultaneous branches |
| **Merge** | Combine parallel branch outputs using `list`, `concat`, or `dict` strategy |
| **Loop** | Repeat a sequence of steps N times; combine with Transform to iterate lists |
| **Transform** | Execute arbitrary Python on shared state; reshape data, filter lists, compute values — zero LLM cost |
| **Extract JSON** | LLM-backed step that coerces upstream text into a typed JSON object against a schema; useful before If/Else or Switch |
| **If/Else** | Evaluate a Python condition against shared state (e.g. `state.result.flag == True`) and route to one of two downstream steps — zero LLM cost |
| **Switch** | Match a state expression (e.g. `state.result.status`) against multiple case values; falls back to `switch_default_step_id` — zero LLM cost |
| **Print** | Write user-defined text/markdown into shared state via `output_key`; supports `{state.key}` interpolation — zero LLM cost, useful for fixed messages, headers, or pre-formatted prompts |
| **Human** | Pause execution for user input via form or messaging platform; resumable across server restarts; configurable `human_timeout_seconds` (default 3600) |
| **End** | Finalize run; return shared state; trigger messaging notifications |

---

## Native Tool Servers

These start automatically with Synapse and are accessible to all agents:

| Tool | What It Does |
|---|---|
| **Sandbox (Python)** | Execute Python in isolated Docker container; 512 MB RAM, 1 CPU; pre-loaded with pandas, numpy, matplotlib, scikit-learn, and 15+ data science packages |
| **Vault** | Persistent file storage for agents across sessions; supports create, read, update, patch, JSON deep-merge, text find-replace, directory listing |
| **SQL Agent** | Connect to PostgreSQL, MySQL, SQLite, or MSSQL; list tables, introspect schemas, run queries; write access optional via setting |
| **Browser** | Full Chromium browser automation via Playwright; navigate, click, fill forms, take screenshots, extract content |
| **Web Scraper** | Powered by crawl4ai; clean markdown extraction, structured data with CSS schemas, parallel crawling, infinite-scroll, authenticated sessions, stealth anti-bot mode |
| **PDF Parser** | Extract text and tables from PDF URLs; page-by-page; tables converted to Markdown |
| **Excel Parser** | Parse `.xlsx` files from URLs; multi-sheet support; all sheets converted to Markdown tables |
| **Collect Data** | Render dynamic input forms inside workflows; supports text, number, email, date, phone, and dropdown fields |
| **Time** | Natural language date/time parsing; relative offsets, weekday targets, timezone conversions |
| **Code Search** | Semantic code search via embeddings (Chroma); index repos; query by natural language; returns file paths + line numbers |

---

## Built-In MCP Servers (auto-enabled)

| MCP Server | Provides |
|---|---|
| Filesystem | Read/write access to local repos configured in Settings → Repos |
| Google Workspace | Gmail (read, search, send), Google Drive (list, read, create), Google Calendar (events, scheduling) |
| Playwright | Headless browser automation (used by the Browser tool) |
| Sequential Thinking | Structured step-by-step reasoning; enabled by default |
| Memory | Persistent knowledge graph memory across sessions; enabled by default |

### Remote MCP Servers
Connect to any MCP server over HTTP. Supports native OAuth and Personal Access Token (PAT) auth. Pre-configured presets for: Vercel, GitHub Copilot, Jira, Zapier, Figma, Fetch. No code required — UI-based setup.

---

## Human-in-the-Loop

Synapse's Human step type pauses any workflow and requests input from a human before continuing.

- **Delivery channels:** Slack, Discord, Telegram, Microsoft Teams, WhatsApp
- **Form fields:** text, number, email, date, phone, dropdown
- **Resumable:** survives server restarts; the workflow picks up exactly where it paused
- **Timeout:** configurable (default 1 hour)
- **Routing:** the human's response can feed directly into an Evaluator step for conditional branching

---

## Messaging Platform Integrations (5)

Bind agents to channels in any of the supported platforms. Users interact with agents directly inside their team communication tools.

| Platform | Features |
|---|---|
| Slack | Send/receive messages; multi-agent mode via `/agent <name>`; per-channel agent binding |
| Discord | Send/receive messages; multi-agent mode; per-channel agent binding |
| Telegram | Send/receive messages; multi-agent mode; per-chat-ID binding |
| Microsoft Teams | Send/receive messages; multi-agent mode |
| WhatsApp | Send/receive messages via Twilio; multi-agent mode |

**Multi-agent mode:** users switch agents mid-conversation with `/agent <name>` and list options with `/agents`.

---

## Agent Types

| Type | Purpose | Default Tools |
|---|---|---|
| **Conversational** | General-purpose assistant | All available tools (browser, vault, databases, MCP servers) |
| **Code** | Codebase analysis and navigation; higher default `max_turns` (50) | `search_codebase` (semantic); file system tools; configurable linked `repos` |
| **Orchestrator** | Routes user input into a pre-defined orchestration workflow | No default tools; runs the bound orchestration DAG |
| **Delegate** | Dynamically routes each user query to one of several sub-agents at runtime via a synthetic `delegate_to_agent` tool | No default tools; the engine injects `delegate_to_agent` and exposes the eligible sub-agent pool. Restrict the pool with `delegate_agent_ids` (empty list = allow any non-builder, non-delegate agent). Prevents infinite delegation loops by skipping self and other delegate agents. |

Per-agent configuration: custom system prompt, tool restrictions, model override, linked code repos, database configs, max turns (default 30; 50 for `code` agents), and `delegate_agent_ids` for `delegate` agents.

---

## Scheduling

Agents and orchestrations can run on a schedule without manual triggering:

- **Interval-based:** every N minutes/hours/days
- **Cron / fixed time:** e.g., every weekday at 9 AM for a standup report
- **Custom prompt per run:** standing instructions sent to the agent each execution
- **Auto-push results:** outcomes delivered to Slack, Discord, Telegram, Teams, or WhatsApp

---

## Orchestration Controls

- **Shared state:** all steps read/write a typed JSON state object; schema-validated
- **Budget cap:** `max_total_cost_usd` — execution halts if cost limit exceeded mid-run
- **Global timeout:** `timeout_minutes` (default 30)
- **Per-step timeout:** `timeout_seconds` (default 300)
- **Global turn cap:** `max_total_turns` (default 100) across the whole run
- **Iteration guard:** `max_iterations` per step (default 3) prevents infinite loops
- **Conditional routing:** Evaluator, If/Else, and Switch steps each route to downstream steps
- **Re-run context:** per-step `include_full_history` (tri-state) controls whether evaluator-feedback or loop re-runs see prior attempts in full or only the last attempt

---

## Caching (3-Layer)

Synapse runs three independent caches to cut LLM and tool spend across runs. All three are configurable globally (Settings) and overridable per step (`StepConfig.cache_*`).

### Prompt Cache (provider-side)
- Decorates provider payloads with native cache_control markers (e.g. Anthropic prompt caching)
- Reuses the system prompt + tool definitions prefix across ReAct turns within a run
- Global toggle: `prompt_cache_enabled` (default `True`)

### Tool Cache (deterministic tool memoization)
- Memoizes results of tools registered in the `DETERMINISTIC_TOOLS` registry (read-only MCP/builder/custom tool calls)
- Keyed on tool name + arguments; safe only for idempotent tools
- Global toggle: `cache_tools_enabled` (default `True`); per-step opt-out via `StepConfig.cache_tools_enabled`
- TTL: `cache_tool_ttl_seconds` (default 3600)

### Response Cache (LLM responses, exact + semantic)
- Caches LLM responses for LLM, EVALUATOR, EXTRACT_JSON, and other non-AGENT steps
- Skipped for AGENT steps (state-dependent, multi-turn behavior)
- Exact-match: per-step `cache_responses_enabled` (default `False`)
- Semantic-match: per-step `cache_semantic_enabled` (default `False`), with similarity threshold `cache_response_threshold` (default `0.95`)
- TTL: `cache_response_ttl_seconds` (default 3600)

### Cache Metrics (per run)
Each `OrchestrationRun` records: `cache_read_tokens_total`, `cache_write_tokens_total`, `cache_hit_count`, `cache_miss_count` — visible in the run dashboard.

---

## Starter Packs (Import Ready)

Synapse ships with 4 curated import bundles containing pre-configured agents, orchestrations, and MCP connections:

**Starter Pack**
- 5 agents: Personal Assistant, Web Research Agent, Document Creator, Drafter, Career Search Agent
- 2 orchestrations: Content Research & Writing Pipeline, Job Search Pipeline

**Developer Pack**
- 7 agents: Code Review, Software Engineer, Deployment Monitor, QA Engineer, Code Executor, and more
- 3 orchestrations: multi-step dev pipelines with human-in-the-loop PR gates
- 2 MCP servers: GitHub, Jira

**Productivity Pack**
- 4 agents: Data Analyst, Content Writer, Jira Analyst, Slack Notifier
- 1 orchestration: Market Intelligence pipeline
- 3 MCP servers: Jira, Slack, additional APIs

**MCP Servers Pack**
- Pre-configured MCP definitions for GitHub, Slack, Notion, Brave Search, and more

---

## Example Workflow: Content Research & Writing Pipeline

1. **Research Topic** (Agent) — browses web, extracts findings into shared state
2. **Research Quality Gate** (Evaluator) — routes: "sufficient" → draft, "needs_clarification" → ask user
3. **Ask User for Clarification** (Human) — pauses and loops back to research if needed
4. **Parallel Drafting** (Parallel):
   - Branch A: Write Article Draft (Document Drafter, 800–1200 words)
   - Branch B: Find Real-World Examples (Web Research agent)
5. **Merge Outputs** (Merge, `concat` strategy)
6. **Quality Review** (Evaluator) — final gate before save
7. **Save to Vault** (Tool) — persist the finished document
8. **End** — return result, push to Slack if configured

---

## How Synapse Compares

| Capability | Synapse AI | LangChain | CrewAI | AutoGen | n8n |
|---|---|---|---|---|---|
| Visual DAG Builder | Yes | No | No | No | Yes |
| Deterministic execution | Yes | No | No | No | Yes |
| Per-step LLM selection | Yes | Partial | No | No | No |
| AI Builder (Chat-to-DAG) | Yes | No | No | No | No |
| Human-in-the-loop (5 platforms) | Yes | No | No | No | Partial |
| Local execution (Ollama) | Yes | Yes | No | No | No |
| 10+ native tool servers | Yes | Partial | No | No | Yes |
| Built-in MCP support | Yes | Partial | No | No | No |
| Per-run budget cap | Yes | No | No | No | No |
| Scheduling built-in | Yes | No | No | No | Yes |
| Semantic code search | Yes | No | No | No | No |
| Open source (AGPL-3.0) | Yes | Yes (MIT) | Yes | Yes | Yes |

---

## Production Use Cases

- **Content Research & Writing** — web research agent → evaluator gate → parallel drafting → vault storage
- **Autonomous Code Review** — static analysis tool → LLM reviewer → GitHub PR comment via MCP
- **Market Intelligence Reports** — multi-source scraper → data transformer → Slack-delivered report on schedule
- **Customer Support Bot** — intent classifier → knowledge base retriever → response generator with human escalation
- **Database Q&A Agent** — natural language → SQL generator → query executor → formatted results
- **Deep Web Research** — parallel stealth browser agents → aggregator → synthesizer
- **Scheduled Standup Reports** — cron-triggered orchestration → data collector → formatted Slack post
- **Autonomous PR Creator** — code analyzer → implementer → test runner → GitHub PR via MCP, human approval gate

---

## Technology Stack

- **Backend:** Python 3.11+ / FastAPI / Uvicorn
- **Frontend:** Next.js / React / TypeScript
- **Vector DB:** ChromaDB (semantic code search)
- **Browser:** Playwright (Chromium)
- **Web scraping:** crawl4ai
- **Sandbox:** Docker (Python execution)
- **Database:** SQLAlchemy (PostgreSQL, MySQL, SQLite, MSSQL)
- **Messaging:** slack-bolt, discord.py, python-telegram-bot, Teams webhook, Twilio (WhatsApp)
- **MCP:** Model Context Protocol SDK

---

## Frequently Asked Questions

**Q: What is Synapse AI?**
A: Synapse AI is an open-source multi-agent AI orchestration platform. You build workflows as DAGs using a visual builder, connect 14+ LLMs, and execute them deterministically in production. It includes native tool servers, MCP support, human-in-the-loop, and messaging integrations.

**Q: Is Synapse AI free?**
A: Yes. Synapse AI is AGPL-3.0 licensed and fully free. No paid tier, no feature gating. Source code at https://github.com/synapseorch-ai/synapse-ai.

**Q: Does Synapse AI require cloud services or send data externally?**
A: No. Synapse AI runs fully locally with Ollama for LLMs and Docker for tool execution. No data leaves your infrastructure unless you explicitly configure cloud LLM providers.

**Q: How is Synapse AI different from LangChain?**
A: LangChain is a Python library — you write code to chain LLM calls. Synapse AI is a complete platform: visual DAG builder, 10 step types, built-in tool servers, AI Builder (English-to-DAG), human-in-the-loop across 5 platforms, scheduling, cost controls, and a frontend UI. No glue code required.

**Q: How is Synapse AI different from CrewAI?**
A: CrewAI uses role-based agents with emergent behavior (non-deterministic). Synapse AI uses strict DAGs — every execution follows the exact path you define. Synapse also ships a visual builder, per-step model selection, cost caps, and production-grade tool servers that CrewAI lacks.

**Q: How is Synapse AI different from n8n?**
A: n8n is a general automation tool. Synapse AI is purpose-built for AI agent workflows: it supports multi-step agent reasoning (ReAct), per-step LLM selection, semantic code search, an AI Builder, and native MCP server connections. n8n has no equivalent to Synapse's Agent, Evaluator, or Human step types.

**Q: Can I use my existing Python functions as tools in Synapse AI?**
A: Yes. Any Python function, REST API, webhook, or MCP server works as a tool out of the box. Zero adapter code needed.

**Q: What databases does Synapse AI support?**
A: PostgreSQL, MySQL, SQLite, and Microsoft SQL Server, via the built-in SQL Agent tool server.

**Q: Can I run Claude and GPT-4o in the same workflow?**
A: Yes. Synapse supports per-step model selection. Each Agent, LLM, or Evaluator step can use a different provider and model within the same orchestration.

**Q: What is the AI Builder?**
A: The AI Builder is Synapse's Chat-to-DAG feature. You describe the workflow you want in plain English and the AI Builder constructs the full DAG automatically — wiring agents, tools, and LLM calls — which you can then edit visually.