Company Agents

🤖 Company Agents - Multi-Agent Automation System

Hệ thống multi-agent tự động hóa công việc cho các bộ phận trong công ty. Agents chạy local và tương tác qua Claude Desktop App thông qua MCP (Model Context Protocol).

📋 Tổng Quan

Company Agents cung cấp các AI agents chuyên biệt cho từng bộ phận:

• 📊 Sales Agent: Phân tích dữ liệu bán hàng, tạo báo cáo tự động ✅ READY
• 🤖 Agent Generator: Tự động tạo agent mới trong 3 phút ✅ NEW!
• 👥 HR Agent: Quản lý nhân sự, tuyển dụng (tạo bằng Generator)
• 💰 Finance Agent: Báo cáo tài chính, dự báo (tạo bằng Generator)

✨ Tính Năng Chính - Sales Agent

Phân Tích Dữ Liệu

• ✅ Tự động đọc dữ liệu từ Excel/CSV
• ✅ Phát hiện và chuẩn hóa tên cột
• ✅ Làm sạch và validate dữ liệu
• ✅ Tính toán metrics tổng quan

Báo Cáo Chi Tiết

• 📈 Tổng doanh thu, số đơn hàng, giá trị trung bình
• 🏆 Top 5 sản phẩm bán chạy
• 🗺️ Phân tích theo vùng/region
• 📉 Xu hướng doanh thu theo ngày
• 📊 So sánh với tháng trước (growth %)

Visualizations

• 📊 Biểu đồ cột: Top products
• 📈 Biểu đồ đường: Daily revenue trend
• 🥧 Biểu đồ tròn: Revenue by region

MCP Integration

• 🔧 4 tools tích hợp với Claude Desktop
• 💬 Chat tự nhiên: "Tạo báo cáo bán hàng tháng 10"
• 🤖 Agent tự động xử lý và trả kết quả

🤖 Agent Generator - TẠO AGENT MỚI TRONG 3 PHÚT!

NEW FEATURE: Tự động tạo agent mới chỉ với vài câu hỏi!

Cách 1: Slash Command (Dễ nhất) ⚡

/create-agent

Chat trực tiếp trong Claude Desktop, trả lời vài câu hỏi → Done!

Cách 2: Python Script

python tools/agent_generator.py

Chỉ cần trả lời:

1. Tên agent (HR, Finance, Marketing...)
2. Mô tả ngắn
3. Các cột dữ liệu
4. Metrics cần tính
5. Số lượng biểu đồ

→ Generator tự động tạo:

• ✅ Agent structure (config, tools, agent.py)
• ✅ MCP Server
• ✅ Sample data generator
• ✅ Test script

Sau đó chỉ cần:

# 1. Tạo sample data
cd data/
python create_sample_data.py

# 2. Test
python examples/quick_test.py

# 3. Add to Claude Desktop config

# 4. Chat: "Tạo báo cáo  tháng 11/2024"

📖 Chi tiết: Agent Generator Guide

🎯 Claude Slash Commands

4 commands hỗ trợ full workflow:

• /create-agent - Tạo agent mới
• /test-agent - Test agent
• /customize-agent - Customize logic
• /add-mcp-tool - Thêm MCP tools

📖 Commands Guide: .claude/README.md

🚀 Cài Đặt Nhanh

1. Requirements

• Python 3.10+
• pip (Python package manager)
• Claude Desktop App

2. Setup Project

Windows:

# Clone hoặc download project
cd company-agents

# Chạy script setup
tools\setup\setup.bat

Linux/Mac:

# Clone hoặc download project
cd company-agents

# Make script executable
chmod +x tools/setup/setup.sh

# Chạy script setup
tools/setup/setup.sh

Script sẽ tự động:

• ✅ Tạo virtual environment
• ✅ Cài đặt dependencies
• ✅ Tạo file .env
• ✅ Generate sample data
• ✅ Test agent

3. Configure Claude Desktop

Bước 1: Mở file config

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Mac:

~/Library/Application Support/Claude/claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

Bước 2: Thêm MCP server

{
  "mcpServers": {
    "sales-agent": {
      "command": "python",
      "args": [
        "D:/path/to/company-agents/mcp_servers/sales_agent_server.py"
      ],
      "env": {
        "PYTHONPATH": "D:/path/to/company-agents"
      }
    }
  }
}

⚠️ Lưu ý: Thay D:/path/to/company-agents bằng đường dẫn thực tế đến project của bạn.

Bước 3: Restart Claude Desktop

Đóng và mở lại Claude Desktop để load MCP server.

📊 Sử Dụng

Chuẩn Bị Dữ Liệu

Đặt file dữ liệu vào folder data/sales/ theo định dạng:

Tên file:

• sales_YYYY_MM.xlsx
• sales_YYYY_MM.csv

Ví dụ:

• sales_2024_10.xlsx
• sales_2024_11.csv

Cấu trúc dữ liệu:

Các cột bắt buộc:

• date: Ngày bán hàng
• product: Tên sản phẩm
• quantity: Số lượng
• unit_price: Đơn giá

Các cột tùy chọn:

• customer / customer_id: ID khách hàng
• region: Vùng/khu vực

Chat với Agent

Mở Claude Desktop và chat tự nhiên:

1. Tạo Báo Cáo

Tạo báo cáo bán hàng tháng 10 năm 2024

Agent sẽ:

• Tìm file dữ liệu
• Phân tích và tính toán metrics
• Tạo biểu đồ
• Generate báo cáo Markdown

2. Xem Danh Sách Báo Cáo

Cho tôi xem các báo cáo đã tạo

3. Phân Tích Sản Phẩm

Phân tích sản phẩm Laptop tháng 10/2024

4. So Sánh Tháng

So sánh doanh thu tháng 10 và tháng 11 năm 2024

Kết Quả

Báo cáo được lưu tại: reports/sales_report_MM_YYYY.md

Bao gồm:

• ✅ Tóm tắt điều hành
• ✅ Bảng metrics chi tiết
• ✅ Top sản phẩm với biểu đồ
• ✅ Phân tích theo vùng
• ✅ Xu hướng theo ngày
• ✅ So sánh với tháng trước
• ✅ Insights và khuyến nghị

🧪 Testing

Test Agent Directly

# Activate virtual environment
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# Run test
python examples/quick_test.py

Test MCP Server

# Test MCP server locally
python mcp_servers/sales_agent_server.py

Run Unit Tests

# Run all unit tests
pytest tests/unit/

# Run specific test
pytest tests/unit/test_sales_agent.py

📁 Cấu Trúc Project

company-agents/
├── agents/                      # Agent implementations
│   └── sales_agent/
│       ├── __init__.py
│       ├── agent.py            # Core Sales Agent logic
│       ├── tools.py            # Helper functions
│       └── config.yaml         # Agent configuration
│
├── mcp_servers/                # MCP Servers
│   └── sales_agent_server.py  # Sales Agent MCP server
│
├── data/                       # Input data files (organized by agent)
│   └── sales/
│       ├── create_sample_data.py
│       ├── sales_2024_10.xlsx
│       └── sales_2024_11.xlsx
│
├── reports/                    # Generated reports
│   ├── sales_report_10_2024.md
│   └── *.png                   # Charts
│
├── tests/                      # Unit tests
│   └── unit/
│       └── test_sales_agent.py
│
├── tools/                      # Development tools
│   ├── agent_generator.py     # Auto-generate new agents
│   └── setup/                 # Setup scripts
│       ├── setup.bat          # Windows setup
│       └── setup.sh           # Linux/Mac setup
│
├── examples/                   # Code examples
│   └── quick_test.py          # Quick test example
│
├── docs/                       # Documentation
│   ├── INDEX.md               # Documentation index
│   ├── guides/                # How-to guides
│   │   ├── agent-creation.md
│   │   ├── agent-generator.md
│   │   └── mcp-integration.md
│   └── reference/             # Reference docs
│       ├── project-structure.md
│       ├── quick-reference.md
│       └── project-summary.md
│
├── .claude/                    # Claude slash commands
│   └── commands/
│       ├── create-agent.md
│       ├── test-agent.md
│       ├── customize-agent.md
│       └── add-mcp-tool.md
│
├── requirements.txt            # Python dependencies
├── .env.example               # Environment variables template
├── QUICKSTART.md              # Quick start guide
└── README.md                  # This file

🔧 Configuration

Environment Variables (.env)

# Data directories
DATA_DIR=./data
REPORTS_DIR=./reports

# Agent settings
DEFAULT_CURRENCY=VND
DEFAULT_REGION=Vietnam

# Sales Agent specific
SALES_TOP_PRODUCTS_COUNT=5
SALES_CHART_STYLE=seaborn
SALES_FIGURE_DPI=300

Agent Config (agents/sales_agent/config.yaml)

Customize:

• File patterns
• Column mappings
• Analysis settings
• Visualization styles
• Report sections

🐛 Troubleshooting

1. "No data file found"

Nguyên nhân: Không tìm thấy file dữ liệu

Giải pháp:

• Kiểm tra tên file: sales_YYYY_MM.xlsx hoặc sales_YYYY_MM.csv
• Đảm bảo file trong folder data/
• Kiểm tra tháng/năm đúng format

2. "Missing required columns"

Nguyên nhân: Thiếu cột bắt buộc trong dữ liệu

Giải pháp:

• Đảm bảo có đủ các cột: date, product, quantity, unit_price
• Xem file config.yaml để biết các tên cột được hỗ trợ

3. MCP Server không kết nối

Nguyên nhân: Cấu hình Claude Desktop không đúng

Giải pháp:

• Kiểm tra đường dẫn trong claude_desktop_config.json
• Đảm bảo Python path đúng
• Restart Claude Desktop
• Kiểm tra logs trong Claude Desktop

4. Import errors

Nguyên nhân: Dependencies chưa được cài đặt

Giải pháp:

# Activate venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# Reinstall dependencies
pip install -r requirements.txt

📚 Tài Liệu

• Quick Start Guide - Hướng dẫn bắt đầu nhanh
• Documentation Index - Tổng hợp tài liệu
• Agent Creation Guide - Hướng dẫn tạo agent thủ công
• Agent Generator Guide - Sử dụng công cụ tạo agent tự động
• MCP Integration Guide - Tích hợp với Claude Desktop
• Project Structure - Chi tiết kiến trúc hệ thống
• Quick Reference - Cheat sheet

🎯 Roadmap

Phase 1: Sales Agent ✅

• [x] Core agent implementation
• [x] MCP server integration
• [x] Visualizations
• [x] Comprehensive reporting

Phase 2: HR Agent (Coming Soon)

• [ ] Employee data management
• [ ] Recruitment tracking
• [ ] Performance reports
• [ ] Attendance analysis

Phase 3: Finance Agent (Coming Soon)

• [ ] Financial statements
• [ ] Budget tracking
• [ ] Cash flow analysis
• [ ] Forecasting

Phase 4: Advanced Features

• [ ] Multi-agent collaboration
• [ ] Real-time data sources
• [ ] Web dashboard
• [ ] Email notifications
• [ ] Scheduled reports

🤝 Contributing

Contributions are welcome! Vui lòng:

1. Fork repository
2. Create feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add some AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Open Pull Request

📝 Code Quality

Standards

• Type hints cho tất cả functions
• Docstrings (Google style)
• Error handling với try-except
• Logging rõ ràng và informative
• Comments cho logic phức tạp

Testing

# Run tests
pytest tests/

# With coverage
pytest --cov=agents tests/

📄 License

MIT License - see LICENSE file for details

🙋 Support

Có câu hỏi hoặc gặp vấn đề?

• 📧 Email: support@yourcompany.com
• 💬 Issues:
• 📖 Docs: Documentation

🌟 Acknowledgments

• Claude Desktop: For MCP protocol support
• Anthropic: For Claude AI
• pandas: Data manipulation library
• matplotlib: Visualization library

Made with ❤️ by Your Company

*Tự động hóa công việc, tăng năng suất!*