Skip to main content

​
Getting Started with AgentArea

​
🎯 Welcome to AgentArea

AgentArea is a cutting-edge platform for AI agent orchestration and communication. This guide will get you up and running in under 30 minutes.

​
📋 Prerequisites

​
Required Software

  • Docker (v20.10+) or Podman (v4.0+)
  • Docker Compose (v2.0+)
  • Git (v2.30+)
  • Python (v3.11+) - for local development
  • Node.js (v18+) - for frontend development

​
System Requirements

  • RAM: 8GB minimum, 16GB recommended
  • Storage: 10GB free space
  • OS: Linux, macOS, or Windows with WSL2

​
🚀 Quick Setup (5 minutes)

​
1. Clone the Repository

git clone https://github.com/your-org/agentarea.git
cd agentarea

​
2. Environment Configuration

# Copy environment template
cp core/docs/env.example .env

# Edit configuration (optional for development)
vim .env

​
3. Start Development Environment

# Using Docker Compose
docker compose -f docker-compose.dev.yaml up -d

# Or using make (if available)
make dev-up

​
4. Verify Installation

# Check service health
curl http://localhost:8000/health

# Expected response: {"status": "healthy"}

​
🔧 Development Environment

​
Service Overview

ServicePortPurposeHealth Check
Core API8000Main application APIhttp://localhost:8000/health
MCP Manager7999MCP server managementhttp://localhost:7999/health
Traefik8080Reverse proxy dashboardhttp://localhost:8080
PostgreSQL5432DatabaseInternal
Redis6379Cache & sessionsInternal
MinIO9000Object storagehttp://localhost:9000

​
Key URLs

  • API Documentation: http://localhost:8000/docs
  • Admin Interface: http://localhost:8000/admin
  • MCP External Access: http://localhost:81/mcp/{slug}/mcp/

​
🛠️ Development Workflow

​
Daily Development

# Start services
docker compose -f docker-compose.dev.yaml up -d

# View logs
docker compose -f docker-compose.dev.yaml logs -f app

# Stop services
docker compose -f docker-compose.dev.yaml down

​
Database Operations

# Run migrations
docker compose -f docker-compose.dev.yaml run --rm app alembic upgrade head

# Create new migration
docker compose -f docker-compose.dev.yaml run --rm app alembic revision --autogenerate -m "description"

# Reset database (development only)
docker compose -f docker-compose.dev.yaml down -v
docker compose -f docker-compose.dev.yaml up -d

​
CLI Usage

# Access CLI inside container
docker compose -f docker-compose.dev.yaml exec app bash

# Run CLI commands
python -m agentarea_cli --help

# Example: Create an agent
python -m agentarea_cli agent create --name "test-agent" --type "chat"

​
🧪 Testing Your Setup

​
1. API Health Check

curl -X GET http://localhost:8000/health
# Expected: {"status": "healthy", "timestamp": "..."}

​
2. Create Your First Agent

curl -X POST http://localhost:8000/v1/agents/ \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hello-world",
    "description": "My first agent",
    "type": "chat"
  }'

​
3. Test MCP Integration

# List available MCP servers
curl http://localhost:8000/v1/mcp-servers/

# Test MCP flow
python test_mcp_flow.py

​
4. Verify Database Connection

# Check database tables
docker compose -f docker-compose.dev.yaml exec db psql -U agentarea -d agentarea -c "\dt"

​
📚 Next Steps

​
For Backend Developers

  1. System Architecture - Understand the technical implementation
  2. CLI Usage - Master the command-line interface
  3. API Documentation - Explore available endpoints
  4. Auth Implementation - Learn authentication patterns

​
For Frontend Developers

  1. Agent Chat Implementation - Chat system design
  2. API Reference - Frontend integration patterns (Coming Soon)
  3. UI Components - Reusable component library (Coming Soon)

​
For DevOps/Infrastructure

  1. Architecture Decisions - Infrastructure choices
  2. Deployment Guide - Production deployment (Coming Soon)
  3. Monitoring Setup - Observability configuration (Coming Soon)

​
For Product/Business

  1. Project Overview - Vision and roadmap
  2. Architecture Insights - High-level system design
  3. Task Assignment - Current development priorities

​
🔍 Troubleshooting

​
Common Issues

​
Services Won’t Start

# Check Docker daemon
docker info

# Check port conflicts
lsof -i :8000

# Clean restart
docker compose -f docker-compose.dev.yaml down -v
docker compose -f docker-compose.dev.yaml up -d

​
Database Connection Errors

# Check database logs
docker compose -f docker-compose.dev.yaml logs db

# Reset database
docker compose -f docker-compose.dev.yaml down -v
docker compose -f docker-compose.dev.yaml up -d db
# Wait 30 seconds, then start other services

​
Permission Errors

# Fix file permissions (Linux/macOS)
sudo chown -R $USER:$USER .

# Or run with sudo (not recommended)
sudo docker compose -f docker-compose.dev.yaml up -d

​
Module Import Errors

# Rebuild containers
docker compose -f docker-compose.dev.yaml build --no-cache
docker compose -f docker-compose.dev.yaml up -d

​
Getting Help

  1. Check Logs: docker compose -f docker-compose.dev.yaml logs -f
  2. Service Status: docker compose -f docker-compose.dev.yaml ps
  3. Health Checks: Visit health endpoints listed above
  4. Documentation: Refer to Documentation Index
  5. Team Support: Contact the development team

​
🎉 Success!

If you’ve reached this point, you should have:
  • ✅ AgentArea running locally
  • ✅ All services healthy
  • ✅ Database connected
  • ✅ First API call successful
Ready to build amazing AI agent experiences! 🚀
Last updated: January 2025 Next review: February 2025
⌘I