Architecture

System Overview

CRED Agent AI uses a supervisor/subagent architecture where a lightweight routing supervisor delegates user requests to 7 domain-specialized subagents, each with focused tools and prompts.

flowchart TB
    subgraph inputs [Input Channels]
        slack[Slack]
        teams[Teams]
        ws["GraphQL / WebSocket"]
    end

    subgraph agent [cred-agent-ai]
        messages["Messages Service\nHistory, memory, debug"]
        supervisor["Supervisor Agent\ncurrentUser, platform_assistant,\nexport_document, list_subagents"]

        subgraph subagents [Domain Subagents]
            intel["intelligence_agent\n~20 tools"]
            lists["lists_agent\n~33 tools"]
            analytics["analytics_agent\n~26 tools"]
            workflows["workflows_agent\n~23 tools"]
            dataops["data_ops_agent\n~30 tools"]
            reports["report_agent\n~6 tools"]
            dsci["data_science_agent\n~6 tools"]
            customer["customer_tools_agent\n(dynamic)"]
        end
    end

    subgraph mcp [MCP Servers via IBM Gateway]
        graphql[graphql-mcp-server]
        assistant[assistant-mcp-server]
        datascience[data-science-mcp-server]
    end

    slack --> messages
    teams --> messages
    ws --> messages
    messages --> supervisor
    supervisor --> intel
    supervisor --> lists
    supervisor --> analytics
    supervisor --> workflows
    supervisor --> dataops
    supervisor --> reports
    supervisor --> dsci
    supervisor --> customer
    intel --> mcp
    lists --> mcp
    analytics --> mcp
    workflows --> mcp
    dataops --> mcp
    reports --> mcp
    dsci --> mcp

Core Design Principles

Supervisor routing — A lightweight supervisor LLM delegates to domain specialists instead of one agent handling everything
@agents tag routing — cred-mcp controls which tools go to which agent via @agents: tags in tool descriptions
Context isolation — Each subagent has its own focused tools and prompt, keeping context small
Modularity — Each platform integration is isolated in its own NestJS module
Scalability — Stateless design with external storage
Security — JWT-based authentication and secure token management

Supervisor/Subagent Architecture

How It Works

User sends a message via Slack, Teams, or WebSocket
MessagesService builds conversation context (history, memory)
buildSupervisorGraph() creates the supervisor + subagent graph:
Partitions MCP tools by @agents tags in descriptions
Creates one createAgent per domain
Wires them into createSupervisor from @langchain/langgraph-supervisor
Supervisor LLM receives the user message and decides which agent to delegate to
Handoff tool (transfer_to_intelligence_agent) transitions to the subagent
Subagent runs its tool loop (search, filter, create) and returns results
Supervisor relays the response to the user

Domain Agents

Agent	Domain	Example queries
`intelligence_agent`	Entity search, company/person profiles, financial data	"Find SaaS companies in Austin"
`lists_agent`	Lists, campaigns, message sequences	"Create a list of healthcare companies"
`analytics_agent`	Dashboards, metrics, scoring, charts, ClickHouse	"Build a revenue dashboard"
`workflows_agent`	Automations, triggers, alerts	"Set up an alert when revenue drops"
`data_ops_agent`	Imports, sources, CRM sync, matching	"Import this spreadsheet"
`report_agent`	Report builder (templates, calculations)	"Generate a market report"
`data_science_agent`	Pipeline management	"Run the business model pipeline"
`customer_tools_agent`	Customer-connected MCP servers (dynamic)	"Sync to my Salesforce"

Tool Routing via @agents Tags

Tool-to-agent assignment is controlled by @agents: tags embedded in MCP tool descriptions in cred-mcp. When cred-agent-ai loads tools from the MCP gateway, partitionTools() parses the tag, strips it from the LLM-facing description, and routes the tool to the declared agent(s).

Tag format (last line of tool description):

@agents: intelligence_agent, lists_agent

This means cred-mcp is the single source of truth for tool routing. Adding a new tool to cred-mcp with the right @agents tag automatically routes it to the correct subagent — no changes needed in cred-agent-ai.

Core Modules

Messages Module (`src/messages/`)

Central message processing orchestrator.

Key Components:

MessagesService — Main orchestrator for message processing
DatabaseConversationHistoryAdapter — Manages conversation persistence, filters handoff tools from history
Memory retrieval and injection into supervisor prompt

LLM Connector (`src/connectors/llm/`)

Handles the supervisor/subagent graph and streaming.

Key Components:

Component	Purpose
`LangGraphAgentConnector`	Main LLM processing — builds graph, handles streaming
`buildSupervisorGraph()`	Creates supervisor + subagent graph from registry + tool tags
`partitionTools()`	Routes tools to agents by @agents tags
`parseAgentTags()`	Extracts @agents tag from tool descriptions

MCP Connector (`src/connectors/mcp/`)

Model Context Protocol integration.

McpHttpHelper.getCredClient() — CRED platform MCP client
McpHttpHelper.getClients() — CRED + customer MCP clients
Customer servers use prefixToolNameWithServerName: true for clean tool names

Prompts (`src/connectors/prompts/`)

subagent-prompts/supervisor.ts — Pure routing prompt (never answers directly)
subagent-prompts/intelligence.ts, lists.ts, etc. — Domain-specific prompts
subagent-prompts/shared-formatting.ts — Citation format, work page links, number formatting