Architecture Overview

Architecture Overview

ADEPT implements a production-ready three-tier architecture with clear separation of concerns.

---

System Diagram

Client Interfaces (10)
  Claude Desktop/Code | ChatGPT | Roo Code | Continue.dev | Cursor | OBot.ai
  AG-UI | OpenWebUI | JupyterLab | Python SDK (afk CLI)
                                         |
                            adept-connectors library
                                         v
 [Tier 1: Agent Gateway]  --> [Tier 2: Orchestration Service] --> [Tier 3: MCP Tool Servers]
      Auth proxy                  Core logic + state               Stateless executors
   (Keycloak JWT)             (PostgreSQL + LangGraph)          (MCP JSON-RPC protocol)

---

Tier 1: Agent Gateway

Role: Pure authentication proxy. No business logic.

• Keycloak JWT validation with RBAC via groups claim
• CORS handling and transparent proxying to Tier 2
• A2A mesh communication for multi-gateway federation
• Source: src/agentic_framework_pkg/agent_gateway/

Tier 2: Orchestration Service

Role: Core brain. All state and business logic lives here.

• OpenAI Response API (/v1/responses/chat/completions)
• ScientificWorkflowAgent with LangGraph state machine
• Multi-agent orchestration (Router mode + Graph mode)
• Per-role LLM purpose routing via YAML model catalog
• PostgreSQL-backed LangGraph checkpointing
• Dynamic tool management with ACL filtering
• Source: src/agentic_framework_pkg/orchestration_service/

Tier 3: MCP Tool Servers

Role: Stateless executors hosting domain-specific tools via MCP.

Server	Tools	Description
mcp_server/	BLAST, UniProt, PubChem, AlphaFold, RAG, WebSearch, File Mgmt	Scientific tools
hpc_mcp_server/	Nextflow, Video Transcription, GitXray	HPC pipelines
sandbox_mcp_server/	Python/R execution	Secure code sandbox

---

Supporting Services

Service	Role
Gateway Registry	A2A federation and service discovery
Keycloak	IAM with OIDC, JWT, RBAC
Redis	Tool config cache + session metadata
ChromaDB / pgvector	Hybrid vector store for RAG
PostgreSQL	State persistence (LangGraph checkpoints)
Langfuse	Observability and cost tracking

---

Network Architecture

Network	Services	Purpose
adept_frontend_network	nginx_proxy, OAuth2 proxy, UIs	External access
adept_application_network	Gateway, orchestration, Keycloak, MCP servers	Internal services
adept_data_network	PostgreSQL, Redis	Data persistence

---

API Strategy

ADEPT supports two API surfaces:

API	Endpoint	Status	Use Case
Response API	/v1/responses/chat/completions	Primary	New implementations, streaming
Assistants API	/v1/assistants/*, /v1/threads/*, /v1/runs/*	Legacy	Backward compatibility

Use Response API for all new work. See docs/architecture/DUAL_API_STRATEGY.md.

---

Key Design Principles

1. State ownership: All state in Tier 2. MCP servers are completely stateless.
2. Session isolation: Multi-tier session IDs prevent cross-user data leakage.
3. No HTTP self-calls: Orchestration uses direct tool_manager, never its own endpoints.
4. Tool discovery: Dynamic via MCP JSON-RPC tools/list with ACL filtering.
5. Additive routing: Any role name works; unknown roles fall back to default LLM.