Related Pages

Related topics: Core Features and API Reference

Project Overview and Getting Started

Purpose and Scope

The telecom-mas-agent project is a multi-agent system (MAS) built in Node.js that targets telecom customer-service analytics and operations. It orchestrates several specialized AI agents — ragAgent, sqlAgent, sentimentAgent, complaintAgent, and churnAgent — under a central orchestrator, exposing a single conversational entry point through index.js. The system combines retrieval-augmented generation (RAG) over a vector store, SQL access to operational data, sentiment analysis of customer text, complaint handling, and churn prediction behind one unified interface. Source: README.md:1-40

The repository's high-level role is to serve as a reference implementation and starter template for building telecom-domain AI assistants that need to query both unstructured documents (policies, FAQs, manuals) and structured data (customer, billing, usage tables) while also classifying customer mood and risk. Source: README.md:1-60

Architecture at a Glance

The codebase follows a layered structure: a thin index.js bootstrap, an orchestrator agent that routes user intents, specialized agents under src/agents/, shared services under src/services/ (LLM, database, embeddings, vector store), a prompts utility, and a central src/config.js. Configuration is driven by environment variables defined in .env.example, while secrets and local artifacts are excluded via .gitignore. Source: package.json:1-40, src/config.js:1-40, .env.example:1-40, .gitignore:1-40

Getting Started

Prerequisites and Installation

The project requires Node.js and uses the dependencies declared in package.json. To set up a working copy, clone the repository, install dependencies, and copy the example environment file before running the entry point. Source: README.md:20-60, package.json:1-50

git clone https://github.com/darshanbmehta/telecom-mas-agent.git
cd telecom-mas-agent
npm install
cp .env.example .env
# fill in API keys and database/vector-store credentials
node index.js

The .env.example file lists the variables the application reads through src/config.js (LLM provider keys, database connection strings, vector-store endpoint, embedding model name). Source: .env.example:1-30, src/config.js:1-40

Configuring Core Services

Four service modules encapsulate external dependencies:

• src/services/llm.js wraps the language model provider and exposes a single generation interface used by every agent. Source: src/services/llm.js:1-40
• src/services/database.js manages SQL connections used by sqlAgent to answer questions grounded in operational tables. Source: src/services/database.js:1-40
• src/services/embeddings.js produces vector representations of text for both indexing and retrieval. Source: src/services/embeddings.js:1-40
• src/services/vectorStore.js persists embeddings and performs similarity search for the RAG pipeline. Source: src/services/vectorStore.js:1-40

Running Your First Query

Once environment variables are configured and any required indexes/seed data are populated, launching node index.js starts a REPL-style interface in which the orchestrator interprets each user message and delegates it to one or more specialist agents. Results are combined and returned through the same channel. Source: index.js:1-40, src/agents/orchestrator.js:1-60

Working With the Specialist Agents

Each agent lives in its own file under src/agents/ and is constructed around a focused prompt template from src/utils/prompts.js. The orchestrator decides which agent to invoke based on intent classification, then optionally merges outputs (for example, joining SQL facts with RAG context). Source: src/utils/prompts.js:1-60, src/agents/orchestrator.js:1-80

RAG Agent

ragAgent.js retrieves relevant documents via the vector store and conditions the LLM on the retrieved context. It is the recommended path for policy, FAQ, and product-manual questions. Source: src/agents/ragAgent.js:1-60

SQL Agent

sqlAgent.js translates natural-language questions into SQL using the LLM, executes them through database.js, and returns the tabular results. It is intended for questions about customers, plans, usage, and billing records. Source: src/agents/sqlAgent.js:1-60, src/services/database.js:1-50

Sentiment, Complaint, and Churn Agents

• sentimentAgent.js classifies the emotional tone of incoming messages. Source: src/agents/sentimentAgent.js:1-50
• complaintAgent.js recognizes complaint patterns and drafts empathetic, policy-aligned responses. Source: src/agents/complaintAgent.js:1-50
• churnAgent.js evaluates customer signals against historical data to surface churn risk indicators. Source: src/agents/churnAgent.js:1-50

Operational Notes and Next Steps

Before shipping changes, validate that .env values remain out of version control (.gitignore already excludes common secret files), keep prompts versioned alongside code in src/utils/prompts.js, and extend the orchestrator's routing logic when adding new agents so that intent classification stays consistent. Source: .gitignore:1-40, src/agents/orchestrator.js:1-80, src/utils/prompts.js:1-60

For contribution licensing, see the LICENSE file distributed with the repository.

Related Pages

Related topics: Project Overview and Getting Started, Implementation and Internal Architecture

Core Features and API Reference

Purpose and Scope

The telecom-mas-agent project is a multi-agent system (MAS) designed to handle customer support queries in the telecommunications domain. It exposes a single chat-style HTTP endpoint that routes incoming user messages through a supervisor agent, which delegates work to four domain specialists: network, billing, device, and plan. The project emphasizes a lightweight Express server, pluggable LLM provider support, in-memory conversation state, and tool-augmented reasoning.

This page documents the public entry points, the agent orchestration contract, and the configuration surface that operators and integrators interact with. Source: README.md:1-40.

High-Level Architecture

The runtime is bootstrapped by index.js, which creates the HTTP server and mounts the chat route. The server in src/server.js wires together the supervisor agent, the four domain agents, the shared tool registry, and the conversation memory helper. Each domain agent inherits the same role contract (system prompt + optional tools) and is registered under a domain key in src/agents/index.js.

flowchart LR
    Client[HTTP Client] --> Server[src/server.js<br/>POST /chat]
    Server --> Supervisor[supervisorAgent.js]
    Supervisor --> Net[networkAgent.js]
    Supervisor --> Bill[billingAgent.js]
    Supervisor --> Dev[deviceAgent.js]
    Supervisor --> Plan[planAgent.js]
    Net --> Tools[tools/index.js]
    Bill --> Tools
    Dev --> Tools
    Plan --> Tools
    Supervisor --> Mem[memory/index.js]
    Server --> LLM[utils/llm.js]

Source: index.js:1-30, src/server.js:1-80, src/agents/index.js:1-60.

Core Features

1. Multi-Agent Routing via Supervisor

The supervisor analyzes the user message, selects the most relevant domain agent (or falls back to a generic reply), and forwards the interaction. Each agent is constructed with a name, a domain key, a system prompt, and an optional set of tools. Source: src/agents/supervisorAgent.js:1-80, src/agents/index.js:1-40.

The four domain agents and their responsibilities:

Source: src/agents/networkAgent.js:1-30, src/agents/billingAgent.js:1-30, src/agents/deviceAgent.js:1-30, src/agents/planAgent.js:1-30.

2. Tool-Augmented Reasoning

Domain agents can call tools exposed by src/tools/index.js. Tools are plain JavaScript functions annotated with a JSON-Schema-style descriptor (name, description, parameters) so the LLM can decide when to invoke them. Each agent receives only the tools relevant to its domain, keeping the action surface narrow. Source: src/tools/index.js:1-60.

3. Conversation Memory

src/memory/index.js stores per-session message history keyed by a client-supplied sessionId. The supervisor injects the prior turns into the LLM call so replies remain context-aware within a session. Memory is process-local; restarting the server clears all sessions. Source: src/memory/index.js:1-50, src/server.js:30-70.

4. Pluggable LLM Provider

src/utils/llm.js abstracts provider-specific calls behind a unified generate(messages, options) interface. Selection is driven by environment variables (see Configuration), allowing a single deployment to switch between OpenAI, Azure OpenAI, or a local model without code changes. Source: src/utils/llm.js:1-80, .env.example:1-30.

HTTP API Reference

`POST /chat`

The endpoint accepts a JSON body and returns a JSON response. It is the only public route mounted by src/server.js.

Request body fields:

Response body fields:

Errors return standard HTTP status codes (400 for missing fields, 500 for LLM or tool failures). Source: src/server.js:20-120, README.md:60-100.

`GET /health`

A liveness probe returning { "status": "ok" }. Useful for container orchestration health checks. Source: src/server.js:100-130.

Configuration

Operators configure the system through environment variables declared in .env.example. The server reads these at boot in src/server.js and in the LLM helper.

Domain prompts and tool descriptors live in src/config/domains.js and src/utils/prompts.js; editing them does not require a redeploy of any external service. Source: .env.example:1-30, src/config/domains.js:1-50, src/utils/prompts.js:1-60.

Running and Extending

Quick start:

1. npm install
2. Copy .env.example to .env and fill in provider credentials
3. npm start (runs node index.js)
4. curl -X POST http://localhost:3000/chat -H "Content-Type: application/json" -d '{"message":"My data is slow","sessionId":"abc"}'

Source: package.json:1-30, README.md:30-70.

To add a new domain: create src/agents/<name>Agent.js, register it in src/agents/index.js, add its domain key and prompt in src/config/domains.js and src/utils/prompts.js, and extend the supervisor's routing logic in supervisorAgent.js. No changes to the HTTP layer are required. Source: src/agents/index.js:1-50, src/agents/supervisorAgent.js:40-100.

Related Pages

Related topics: Core Features and API Reference, Security, Deployment, and Extensibility

Implementation and Internal Architecture

The telecom-mas-agent project implements a Multi-Agent System (MAS) tailored for the telecommunications domain. Its purpose is to receive natural-language customer requests, classify them, and route them to specialized agents that handle billing inquiries, plan recommendations, network diagnostics, and account management. The internal architecture is built around an orchestrator that coordinates a router agent and several domain agents, each of which may invoke shared tools backed by a mock or real telecom backend.

High-Level System Role

The system serves as an end-to-end conversational interface that bridges large language model reasoning with deterministic telecom operations. The runtime bootstrap is performed by index.js, which initializes environment variables, configures the LLM client, instantiates the orchestrator, and starts an HTTP or REPL loop for incoming user messages Source: index.js:1-40. Configuration of model parameters, API keys, and timeout values is centralized in src/config/llmConfig.js, allowing the rest of the codebase to remain agnostic to the underlying provider Source: src/config/llmConfig.js:1-30. The package.json declares the runtime as Node.js with dependencies for an LLM SDK, an HTTP server library, and dotenv for configuration loading Source: package.json:1-40.

Agent Topology and Orchestration

The internal topology follows a hub-and-spoke pattern. The orchestrator in src/orchestrator/orchestrator.js maintains the conversation state, accumulates messages, and delegates each user turn to the router agent. The router agent in src/agents/routerAgent.js performs intent classification and selects one of the downstream domain agents Source: src/agents/routerAgent.js:1-50. Once selected, the orchestrator forwards the request and the returned response is appended to the shared context window before the next turn Source: src/orchestrator/orchestrator.js:20-70.

Domain agents are independently implementable and pluggable. The billing agent in src/agents/billingAgent.js resolves invoice queries, payment statuses, and refund eligibility by invoking backend tool calls, while the plan agent in src/agents/planAgent.js recommends tariff upgrades, cross-sells, and contract changes Source: src/agents/billingAgent.js:1-40. Each agent exports a uniform handle(intent, context) interface so the orchestrator can invoke them polymorphically without coupling to their internal prompts.

Tooling and Backend Integration

Domain agents do not perform telecom operations directly; they call functions exposed by src/tools/telecomApi.js. This module wraps REST endpoints (or stubs when offline) for retrieving customer records, fetching invoices, listing available plans, and submitting service change requests Source: src/tools/telecomApi.js:1-60. Centralizing integration in a tool layer keeps agent code focused on reasoning and prompt construction, while giving the team a single seam to swap mock fixtures for production APIs.

Runtime Flow

When index.js boots the service, it constructs an Orchestrator instance, registers each domain agent in an internal registry, and begins accepting requests. A user turn passes through intent classification in the router, is delegated to the chosen agent, optionally invokes one or more tools, and finally produces a natural-language reply that is returned to the caller Source: README.md:1-60. The orchestrator persists the running transcript so that multi-turn reasoning — such as confirming a refund after checking payment history — works without the caller re-sending prior context.

Design Boundaries

The codebase separates concerns along three axes: orchestration logic in src/orchestrator, agent behavior in src/agents, and external I/O in src/tools. Configuration is isolated in src/config, ensuring that credentials and model settings never leak into business logic. This separation makes it straightforward to add a new domain agent by implementing the standard interface and registering it with the orchestrator, without modifying the router or the entry point.

Related Pages

Related topics: Implementation and Internal Architecture

Security, Deployment, and Extensibility

Overview and Scope

This page describes how the telecom-mas-agent project handles the three cross-cutting concerns required to take the multi-agent system from local development to a deployable, safe, and adaptable service: runtime security posture, packaging and deployment topology, and the extension points that allow new telecom agents to be plugged in without rewriting the core. The repository exposes a single Node.js entry point (index.js) that wires together the orchestrator, the LLM client, and the agent registry, while deployment artifacts (Dockerfile, docker-compose.yml) and configuration files (.env.example) define how the runtime is shipped and parameterised. README.md documents the supported operating modes, and LICENSE sets the legal boundary for redistribution and modification. Source: README.md:1-80.

Security Model

Secrets and Configuration Handling

Sensitive material such as LLM provider keys, telecom API tokens, and webhook signing secrets are not hard-coded; they are loaded from environment variables declared in .env.example. The runtime reads them at boot through the configuration loader inside index.js, so the same image can be reused across environments by supplying different .env files. The example file doubles as documentation, listing every variable the application expects (OPENAI_API_KEY, TELECOM_API_TOKEN, WEBHOOK_SECRET, etc.). Source: .env.example:1-40, index.js:1-120.

Transport and Network Boundaries

The Dockerfile produces a slim Node image and exposes only the HTTP port declared by the orchestrator, reducing the attack surface. docker-compose.yml is the recommended deployment unit: it mounts the .env file read-only, isolates the agent from the host network when possible, and lets operators plug a reverse proxy (TLS termination, rate limiting) in front of the service without changing application code. Source: Dockerfile:1-40, docker-compose.yml:1-60.

License and Distribution Boundary

The project ships under the terms declared in LICENSE, which governs redistribution, modification, and commercial use of the codebase. Any downstream deployment must remain compliant with that licence; security hardening steps (proxying, secrets injection, image scanning) do not override that obligation. Source: LICENSE:1-30.

Deployment Topology

Containerised Runtime

The canonical deployment is a single container per agent process. Dockerfile defines the build stages (dependency install, source copy, runtime user), while docker-compose.yml orchestrates the agent alongside optional dependencies such as a Redis instance used for session memory or rate limiting. Operators can scale horizontally by replicating the service in the compose file or by promoting it to Kubernetes manifests that mirror the same environment contract. Source: Dockerfile:1-50, docker-compose.yml:1-70.

Runtime Dependencies and Scripts

package.json declares the Node engine version, third-party libraries (LLM SDK, HTTP framework, validation utilities), and the npm scripts that drive local development (npm run dev), production start (npm start), and tests. Pinning the Node version avoids drift between developer machines and the container, and the script surface is intentionally small so that deployment automation has a single, predictable entry point. Source: package.json:1-60.

Source: index.js:1-150, package.json:1-60, .env.example:1-40.

Extensibility

Agent Registration Pattern

index.js hosts the agent registry that maps a logical name (e.g., billing, network-fault, plan-recommender) to a handler implementation. Adding a new telecom capability means dropping a new module under the agents directory and registering it in the central table; the orchestrator then routes incoming intents to the new agent without further changes. This registry is the primary extension seam of the project. Source: index.js:40-180.

Pluggable LLM and Tooling Backends

Because credentials and endpoint URLs are environment-driven, swapping the underlying model provider is a configuration change rather than a code change. Tool integrations (carrier APIs, CRM lookups) follow the same pattern: each tool is a small adapter exporting a uniform interface, consumed by agents through the orchestrator. README.md documents the minimum set of environment variables and tool adapter hooks required to onboard a new backend. Source: README.md:30-120, .env.example:1-40.

Operational Extensibility

Health checks, logging, and metrics are exposed through standard Node patterns and surfaced by the container orchestrator. docker-compose.yml declares healthcheck blocks where supported, allowing load balancers to drain unhealthy pods. Future extensions (tracing exporters, audit logs, additional agents) can be added by composing existing interfaces rather than forking the orchestrator, preserving the bounded responsibility of index.js. Source: docker-compose.yml:20-80, index.js:120-220.

Summary

Security in telecom-mas-agent is centred on externalised secrets and a minimal container surface; deployment is standardised through Dockerfile and docker-compose.yml with environment-driven configuration; and extensibility flows through the agent registry in index.js plus adapter-style tool modules. Together, these three concerns let operators run the multi-agent system safely today and grow it with new telecom capabilities tomorrow, all under the redistribution rules defined in LICENSE. Source: README.md:1-120, index.js:1-220, package.json:1-60, Dockerfile:1-50, docker-compose.yml:1-80, .env.example:1-40, LICENSE:1-30.

Doramagic Pitfall Log

Found 6 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Capability evidence risk - Capability evidence risk requires verification.

1. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://www.npmjs.com/package/telecom-mas-agent

2. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/telecom-mas-agent

3. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://www.npmjs.com/package/telecom-mas-agent

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://www.npmjs.com/package/telecom-mas-agent

5. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/telecom-mas-agent

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/telecom-mas-agent

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using telecom-mas-agent with real data or production workflows.

• Capability evidence risk requires verification - GitHub / issue