LangGraph MCP AWS DynamoDB CRM Agent

Galaxy Telecom — Стандартизированная интеграция AI-инструментов через Model Context Protocol

Подготовленный к продакшену ИИ-агент, демонстрирующий MCP-интеграцию (Model Context Protocol) с AWS DynamoDB: подключение агента LangGraph к актуальным данным CRM через стандартизированный протокол инструментов, а не через разрозненные кастомные интеграции.

📄 Портфолио (PDF) — полное описание с архитектурой, настройкой AWS DynamoDB и примерами взаимодействия

Обзор

Традиционным ИИ-агентам для доступа к данным CRM требуются жестко прописанные интеграции — отдельный код для каждой внешней системы, тесно связанный с логикой агента. Этот проект демонстрирует более правильный подход: агент подключается к Python MCP-серверу во время выполнения, динамически обнаруживает доступные инструменты и вызывает их для получения актуальных данных об аккаунтах и тикетах клиентов из AWS DynamoDB — без единой жестко прописанной интеграционной логики в самом агенте.

Related MCP server: Agorus MCP Server

Что такое MCP?

MCP (Model Context Protocol) — открытый стандарт, представленный Anthropic, который определяет, как ИИ-агенты подключаются к внешним инструментам и источникам данных. Он для ИИ-агентов — то же, чем REST API являются для веб-сервисов: универсальный контракт, обеспечивающий совместимость без создания отдельных адаптеров для каждой интеграции.

Ключевая возможность — обнаружение инструментов в рантайме. Агент не знает заранее, какие инструменты существуют. Он подключается к MCP-серверу и спрашивает: «что вы умеете?» Сервер возвращает названия инструментов, их описания и входные схемы. На основании запроса клиента агент решает, какие инструменты вызвать.

Архитектура

Customer CLI Input
        │
        ▼
┌─────────────────────┐
│   LangGraph Agent   │  ← ReAct pattern, Claude Haiku (Anthropic API)
│   (crm_agent.py)    │
└──────────┬──────────┘
           │ MCP protocol — stdio transport
           │ Runtime tool discovery via get_tools()
           ▼
┌─────────────────────┐
│    MCP Server       │  ← FastMCP, Python
│    (server.py)      │
│                     │
│  get_customer_      │  ← queries CustomerAccounts table
│  account()          │
│                     │
│  get_open_          │  ← queries SupportTickets table
│  tickets()          │
└──────────┬──────────┘
           │ boto3
           ▼
┌─────────────────────┐
│   AWS DynamoDB      │  ← eu-west-1
│                     │
│ GalaxyTelecom_      │
│ CustomerAccounts    │
│                     │
│ GalaxyTelecom_      │
│ SupportTickets      │
└─────────────────────┘

Определение инструментов MCP

Инструменты регистрируются на MCP-сервере с помощью декоратора @server.tool(). Агент не имеет заранее никакого знания об этих функциях — он получает их определения динамически через протокол во время выполнения.

@server.tool()
def get_customer_account(customer_id: str) -> str:
    """
    Retrieve a Galaxy Telecom customer account from DynamoDB.
    Returns account details including plan, status, and balance due.
    """
    ...

@server.tool()
def get_open_tickets(customer_id: str) -> str:
    """
    Retrieve all open support tickets for a Galaxy Telecom customer.
    Returns a list of tickets with issue type, description, status and priority.
    """
    ...

Замена DynamoDB на Salesforce или Dynamics потребует лишь новой реализации MCP-сервера. Код агента остаётся полностью без изменений — это демонстрирует преимущество переносимости протокола.

Таблицы AWS DynamoDB

GalaxyTelecom_CustomerAccounts

• Ключ партиционирования: customer_id

• Содержит: name, email, rate plan, monthly charge, account status, balance due, member since

GalaxyTelecom_SupportTickets

• Ключ партиционирования: customer_id, ключ сортировки: ticket_id

• Содержит: issue type, description, status, date raised, assigned team, priority

• Составной ключ позволяет получить все тикеты клиента одним запросом

Примеры взаимодействия

Просроченный аккаунт с открытыми тикетами (C001)

Customer ID : C001
Message     : Hi, I wanted to check on my account and see if there are any issues.

[MCP] Tools discovered: ['get_customer_account', 'get_open_tickets']

Response: Hi John, I can see your account is overdue with a balance of £47.50.
You have 2 open tickets — a billing query (T001, medium priority) and
broadband dropouts (T002, high priority, in progress with Technical Support)...

Активный аккаунт с существующим техническим тикетом (C002)

Customer ID : C002
Message     : I have been having some signal issues at home, can you help?

Response: Hello Sarah! I can see you're on our EliteMax plan with no balance due.
You've already raised ticket T003 regarding weak 5G signal — an engineer
visit has been requested, marked medium priority...

Неверный идентификатор клиента — аккуратная обработка ошибок

Customer ID : 99
Message     : I have been having some signal issues at home, can you help?

Response: I'm unable to locate a Galaxy Telecom account associated with
Customer ID 99. The ID may have been entered incorrectly...

Технологический стек

Структура проекта

langgraph-mcp-aws-dynamodb-agent/
├── agent/
│   ├── __init__.py
│   └── crm_agent.py        # LangGraph ReAct agent — connects to MCP server
├── dynamo/
│   ├── __init__.py
│   └── seed_data.py        # Creates DynamoDB tables and seeds mock CRM data
├── mcp_server/
│   ├── __init__.py
│   └── server.py           # MCP server — exposes CRM tools backed by DynamoDB
├── main.py                 # Interactive CLI entry point
├── requirements.txt
├── .env.example            # Environment variable template
└── .gitignore

Установка и настройка

Предварительные требования

• Python 3.11+

• API-ключ Anthropic

• AWS-аккаунт с настроенным CLI (aws configure)

• Пользователь IAM с правами чтения/записи в DynamoDB

Установка

# Clone the repository
git clone https://github.com/gayatrianne/langgraph-mcp-aws-dynamodb-agent.git
cd langgraph-mcp-aws-dynamodb-agent

# Create and activate virtual environment
python -m venv venv
venv\Scripts\activate        # Windows
source venv/bin/activate     # macOS/Linux

# Install dependencies
pip install -r requirements.txt

# Configure environment variables
cp .env.example .env
# Edit .env and add your Anthropic API key

Переменные окружения

# Anthropic
ANTHROPIC_API_KEY=your_key_here

# AWS — credentials come from AWS CLI profile (aws configure)
AWS_REGION=eu-west-1

# DynamoDB table names
CUSTOMER_TABLE=GalaxyTelecom_CustomerAccounts
TICKETS_TABLE=GalaxyTelecom_SupportTickets

# LLM Configuration
CLAUDE_MODEL=claude-haiku-4-5-20251001
CLAUDE_TEMPERATURE=0.3

Заполнение таблиц DynamoDB

Запустите один раз перед началом работы с агентом:

python dynamo/seed_data.py

Скрипт создаёт обе таблицы DynamoDB в евро-западном регионе (eu-west-1) и наполняет их тестовыми данными клиентов Galaxy Telecom и их обращений в поддержку.

Запуск

python main.py

Введите идентификатор клиента (C001, C002, C003, C004) и обращение в поддержку. Агент самостоятельно обнаружит MCP-инструменты и Tool, выполнит запрос к DynamoDB и вернёт персонализированный ответ на основе данных клиента.

Ключевые проектные решения

Динамическое обнаружение инструментов через MCP Агент вызывает await client.get_tools() в рантайме — он не знает о существовании инструментов до того, как спросит MCP-сервер. В этом ключевое преимущество протокола: агент отделён от конкретной реализации.

Корректная обработка ошибок MCP-сервер возвращает структурированный JSON-объект с ошибкой для неверного идентификатора. Агент естественным образом интерпретирует его и даёт полезный ответ, не раскрывая клиенту технические детали.

Переносимость через MCP Замена DynamoDB на Salesforce, Dynamics или любую другую CRM требует только реализовать новый MCP-сервер. Код агента LangGraph из файла crm_agent.py остаётся при этом полностью без изменений — протокольный уровень отделяет агент от источника данных.

Модель данных AWS DynamoDB В таблице CustomerAccounts используется один ключ партиционирования (customer_id). В таблице SupportTickets — составной ключ (customer_id + ticket_id), что позволяет одним запросом получать все тикеты клиента и повторяет реальные сценарии обращения к данным CRM.

Демонстрируемые навыки

• Model Context Protocol (MCP) — Стандартизированная интеграция AI-инструментов

• Динамическое обнаружение инструментов — агент обнаруживает инструменты в рантайме, без жёстко заданного набора

• LangGraph-оркестрация агентов — паттерн ReAct с обращением к внешним инструментам

• AWS DynamoDB — NoSQL хранилище CRM-данных с ключами партиционирования и сортировки

• boto3 — AWS SDK для Python

• FastMCP — фреймворк для создания MCP-серверов на Python

• Аккуратность обработка ошибок — структурированные MCP-ответы об ошибках

• Внешние настройки: конфигурация модели и региона через переменные окружения

Автор

Gayatri Anne AI и облачный архитектор | 18+ лет в корпоративных ИТ

Я создаю системы автоматизации на основе ИИ, которые устраняются ручную работу в бизнес-процессах, сочетая агентные рабочие процессы, большие языковые модели и облачную интеграцию, и получаются на выходе готовые к продакшену решения.

Сертификаты: Azure Solutions Architect Expert | Azure AI Engineer Associate | Python PCAP | TOGAF Foundation

GitHub: gayatrianne