Squad - AI Agent Management Platform

Squad is a platform for creating, managing, and evaluating AI agents with human-in-the-loop capabilities. It provides tools for agent orchestration, task management, and performance analytics.

Repository Structure

squad/
├── apps/
│   ├── web/              # React frontend application
│   └── docs/             # Documentation site (future)
│
├── packages/
│   ├── core/             # Core types and evaluation framework
│   │   ├── src/
│   │   │   ├── evaluation/  # Evaluation framework
│   │   │   └── types/      # Shared type definitions
│   │   └── tests/
│   │
│   ├── agents/           # Agent implementations
│   │   ├── src/
│   │   │   ├── base-agent.ts
│   │   │   └── task-agent/
│   │   └── tests/
│   │
│   └── integrations/     # External integrations
│       ├── src/
│       │   └── supabase/   # Supabase client & repositories
│       └── tests/
│
├── supabase/
│   ├── functions/        # Edge Functions
│   ├── migrations/       # Database migrations
│   └── seed/            # Initial data
│
└── .ai/                  # AI development context
    ├── context/          # Project documentation
    └── sessions/         # Development session logs

Architecture Overview

System Architecture

graph TB
    subgraph Frontend["Frontend (React + Vite)"]
        UI[Web Interface]
        Monitoring[Monitoring Dashboard]
        Config[Agent Configuration]
    end

    subgraph Core["Core Services"]
        AgentMgr[Agent Manager]
        TaskOrch[Task Orchestrator]
        Eval[Evaluation Engine]
        VectorOps[Vector Operations]
    end

    subgraph Supabase["Supabase Infrastructure"]
        DB[(PostgreSQL + pgvector)]
        Auth[Authentication]
        Edge[Edge Functions]
        Storage[File Storage]
        Realtime[Realtime Updates]
    end

    subgraph AI["AI Development"]
        Codex[.ai/CODEX.md]
        Patterns[.ai/context/*]
        Sessions[.ai/sessions/*]
    end

    UI --> AgentMgr
    UI --> TaskOrch
    Monitoring --> Eval
    Config --> AgentMgr

    AgentMgr --> DB
    TaskOrch --> DB
    Eval --> DB
    VectorOps --> DB

    AgentMgr --> Edge
    TaskOrch --> Edge

    Edge --> AI
    AI --> Edge

    DB --> Realtime --> UI

Agent Workflow

sequenceDiagram
    participant U as User
    participant AM as Agent Manager
    participant TO as Task Orchestrator
    participant A as Agent
    participant E as Evaluator
    participant DB as Database

    U->>AM: Create Agent
    AM->>DB: Store Configuration
    U->>TO: Submit Task
    TO->>DB: Create Task Record
    TO->>AM: Request Agent
    AM->>A: Initialize Agent
    A->>DB: Update Status
    loop Task Execution
        A->>DB: Get Task Details
        A->>A: Process Task
        A->>DB: Update Progress
        A->>E: Request Evaluation
        E->>DB: Store Results
    end
    A->>TO: Complete Task
    TO->>U: Notify Completion

Data Flow

flowchart LR
    subgraph Input
        T[Task] --> P[Processor]
        K[Knowledge Base] --> P
    end

    subgraph Processing
        P --> V[Vector Store]
        P --> A[Agent]
        V --> A
    end

    subgraph Evaluation
        A --> E[Evaluator]
        E --> M[Metrics]
    end

    subgraph Output
        M --> R[Results]
        A --> R
        R --> F[Feedback Loop]
        F --> K
    end

Infrastructure (Supabase)

Squad leverages Supabase as its primary infrastructure platform, providing:

Vector Operations & AI Features

interface SupabaseAICapabilities {
  vectorStore: {
    storage: pgvector // Built-in pgvector support
    indexes: {
      ivfflat: IVFIndex // For larger datasets
      hnsw: HNSWIndex // For faster retrieval
    }
  }
  integrations: {
    langchain: LangChainVectorStore
    llamaindex: LlamaIndexVectorStore
    openai: OpenAIIntegration
    huggingface: HuggingFaceIntegration
  }
}

Runtime & Compute

interface SupabaseCompute {
  edgeFunctions: {
    runtimes: {
      deno: DenoRuntime // For Edge Functions
      python: PythonRuntime // Via Python Client
    }
    features: {
      websockets: boolean // Real-time capabilities
      backgroundTasks: boolean
      streaming: boolean
    }
  }
}

Storage & Database

interface SupabaseStorage {
  database: {
    postgres: PostgreSQL
    realtime: RealtimeSubscriptions
    rls: RowLevelSecurity
  }
  storage: {
    buckets: StorageBucket[]
    cdn: CDNIntegration
  }
}

Core Architecture

The platform is built around these key components:

Agent Framework

interface AgentDefinition {
  type: string
  capabilities: AgentCapability[]
  tools: Tool[]
  knowledgeBase?: {
    documents?: Document[]
    embeddings?: Embedding[]
    vectorStore?: VectorStore
  }
  prompts: {
    system?: string
    task?: string
    error?: string
  }
  constraints: {
    maxTokens?: number
    temperature?: number
    costLimit?: number
    timeLimit?: number
  }
}

Task Management

interface TaskDefinition {
  type: string
  requirements: {
    capabilities: string[]
    tools: string[]
    priority?: 'low' | 'medium' | 'high'
    deadline?: Date
  }
  workflow?: {
    steps?: TaskStep[]
    fallback?: TaskStep[]
    validation?: ValidationRule[]
  }
}

Evaluation Framework

interface EvaluationCriteria {
  accuracy: number
  relevance: number
  businessValue: {
    costEfficiency: number
    timeEfficiency: number
    qualityScore: number
  }
  domainAccuracy: {
    technicalPrecision: number
    industryCompliance: number
  }
}

Testing Framework

The platform includes a robust testing framework for agents:

Test Runner

# Test an agent (auto-discovers location)
pnpm test:agent sales-prospecting

# Test with explicit domain
pnpm test:agent sales-agents/sales-prospecting

# Test an orchestrator
pnpm test:orchestrator task-manager

Test Structure

// In {{agent-dir}}/__tests__/local.ts
import { YourAgent } from '..'

// Define test data
const TEST_DATA = `Your test content`

// Export test function
export default async function runLocalTest() {
  // Initialize agent
  const agent = new YourAgent(config)

  // Run test cases with different configurations
  const result1 = await agent.process({
    input: testInput1,
    options: { mode: 'brief' },
  })

  const result2 = await agent.process({
    input: testInput2,
    options: { mode: 'detailed' },
  })
}

Test Runner Features

Progress tracking with elapsed time
Automatic agent discovery in domain directories
Structured error handling and reporting
Support for different agent types (domain, orchestrator)

Best Practices

Place tests in __tests__/local.ts within agent directory
Test multiple configurations per agent
Use realistic test data
Validate both success and error cases
Keep test output clear and structured

Database Schema

Our database is designed to support vector operations and efficient agent management:

-- Agent configuration and state
CREATE TABLE agents (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name TEXT NOT NULL,
    type TEXT NOT NULL,
    model TEXT NOT NULL,
    parameters JSONB NOT NULL DEFAULT '{}',
    metadata JSONB
);

-- Vector storage for agent knowledge
CREATE TABLE agent_embeddings (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    agent_id UUID NOT NULL REFERENCES agents(id),
    content TEXT NOT NULL,
    embedding vector(1536),
    metadata JSONB
);

-- Task management
CREATE TABLE tasks (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    title TEXT NOT NULL,
    status TEXT NOT NULL,
    priority TEXT NOT NULL,
    agent_id UUID REFERENCES agents(id),
    metadata JSONB
);

Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

Node.js >= 18
pnpm (recommended) or npm
Supabase CLI
Docker (for local Supabase development)

Environment Setup

Clone the repository:

git clone https://github.com/yourusername/squad.git
cd squad

Install dependencies:
```
pnpm install
```

Set up Supabase:

# Initialize Supabase
supabase init

# Start Supabase services
supabase start

# Apply database migrations
supabase db reset

# Load sample data (optional)
supabase db reset --seed

Configure environment variables:

# Copy the example env file
cp .env.example .env

# Update with your Supabase credentials (shown after supabase start)
# SUPABASE_URL=your_supabase_url
# SUPABASE_ANON_KEY=your_anon_key
# SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

Start the development servers:

# Start all services
pnpm dev

# Or start specific services
pnpm --filter web dev        # Start web UI
pnpm --filter docs dev       # Start documentation site

Development Workflow

Running Tests

# Run all tests
pnpm test

# Run tests for specific package
pnpm --filter @squad/core test
pnpm --filter @squad/agents test

# Run tests in watch mode
pnpm test:watch

Building Packages

# Build all packages
pnpm build

# Build specific package
pnpm --filter @squad/core build

Code Quality

# Run linting
pnpm lint

# Fix linting issues
pnpm lint:fix

# Type checking
pnpm type-check

Project Structure

Each package in the monorepo has its own development workflow:

Core Package

cd packages/core
pnpm dev        # Watch mode for development
pnpm build      # Build the package
pnpm test       # Run tests

Agents Package

cd packages/agents
pnpm dev        # Watch mode for development
pnpm build      # Build the package
pnpm test       # Run tests

Web Application

cd apps/web
pnpm dev        # Start development server
pnpm build      # Build for production
pnpm preview    # Preview production build

Supabase Development

Database Management

# Reset database to a clean state
supabase db reset

# Apply new migrations
supabase db push

# Create a new migration
supabase db diff -f my_migration_name

# Start database GUI
supabase studio

Edge Functions

# Create a new edge function
supabase functions new my-function

# Deploy edge functions
supabase functions deploy my-function

# Test edge functions locally
supabase functions serve

Common Issues & Troubleshooting

Port Conflicts
- The web application runs on port 51926 by default
- Supabase services use ports 54321-54326
- Ensure these ports are available or update the configuration

Database Connection Issues

# Verify Supabase is running
supabase status

# Reset Supabase if needed
supabase stop && supabase start

Package Dependencies

# Clean and reinstall dependencies
pnpm clean
pnpm install

IDE Setup

VS Code

We provide recommended VS Code settings and extensions:

Install the recommended extensions when prompted
Use the workspace TypeScript version
Enable ESLint and Prettier integrations

Other IDEs

Ensure your IDE supports:

TypeScript
ESLint
Prettier
Tailwind CSS
PostCSS

Documentation

The following documentation is available:

Core Documentation

System Architecture - Detailed system design and components
Installation Guide - Setup and configuration instructions
Troubleshooting Guide - Common issues and solutions
Contributing Guidelines - How to contribute to the project

AI Development

AI Development Codex - AI development guidelines and code generation process
Agent Development - Agent patterns and best practices
Memory Systems - Memory management and storage patterns
Edge Functions - Edge function deployment and optimization
Testing Strategies - Testing patterns and quality assurance

Development Workflow

graph TD
    A[New Feature/Task] --> B[Create Session]
    B --> C[.ai/sessions/YYYY-MM-DD_task_name.md]
    C --> D{Development Process}
    D --> E[Define Specifications]
    D --> F[Document Decisions]
    D --> G[Implement & Test]
    E --> H[Review & Iterate]
    F --> H
    G --> H
    H --> I[Integration]

Key Features

Agent Management
- Create and configure AI agents
- Monitor agent status and performance
- Scale agent instances dynamically
Task Orchestration
- Define complex workflows
- Automatic task routing
- Priority-based scheduling
Evaluation Framework
- LangChain integration for evaluation
- Business metrics tracking
- Quality assurance
Vector Operations
- Efficient similarity search
- Knowledge base management
- Embedding storage and retrieval

Contributing

Fork the repository
Create your feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

License

MIT License

Name		Name	Last commit message	Last commit date
.ai		.ai
.husky		.husky
.vscode		.vscode
apps		apps
docs		docs
packages		packages
scripts		scripts
supabase		supabase
test		test
.env.example		.env.example
.env.test.example		.env.test.example
.gitignore		.gitignore
.npmrc		.npmrc
.prettierrc		.prettierrc
DEVELOPMENT.md		DEVELOPMENT.md
README.md		README.md
eslint.config.js		eslint.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
turbo.json		turbo.json
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation

Squad - AI Agent Management Platform

Repository Structure

Architecture Overview

System Architecture

Agent Workflow

Data Flow

Infrastructure (Supabase)

Core Architecture

Testing Framework

Database Schema

Getting Started

Prerequisites

Environment Setup

Development Workflow

Running Tests

Building Packages

Code Quality

Project Structure

Core Package

Agents Package

Web Application

Supabase Development

Database Management

Edge Functions

Common Issues & Troubleshooting

IDE Setup

VS Code

Other IDEs

Documentation

Core Documentation

AI Development

Development Workflow

Key Features

Contributing

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages