Common Ground: Multi-Agent Collaboration That Actually Works

Common Ground streamlines complex research and analysis by facilitating human-AI collaboration without the typical friction. The framework’s core architecture mirrors a professional consulting firm: a Partner agent manages the user interface, a Principal agent handles planning and task decomposition, and Associate agents execute the specific workloads.

Agents are designed declaratively using clean YAML files. This approach allows users to define behaviors, prompts, and tool access within readable configuration files, requiring minimal to no custom code.

The system provides full visibility into the AI's workflow. Common Ground offers real-time Flow, Kanban, and Timeline views, allowing you to monitor every decision, tool call, and state change as it occurs. This eliminates the need to debug via manual console output.

Tool integration is handled via the Model Context Protocol (MCP), making it simple to plug in custom Python tools or external APIs. Once a tool is connected, it becomes available to any agent in the system.

The framework is model-agnostic, utilizing LiteLLM for backend operations. Default Docker images include a pre-configured bridge specifically optimized for Google Gemini.

Installation (Recommended: Docker)

The Docker deployment initializes the complete system, including the gemini-cli-bridge required for multi-agent functionality.

Prerequisites

• Docker and Docker Compose
• Git

Steps

1. Clone the repository

   git clone https://github.com/Intelligent-Internet/CommonGround
   cd CommonGround
   

2. Initialize Git submodules (This retrieves the gemini-cli-mcp-openai-bridge)

   git submodule update --init --recursive
   

3. Navigate to the deployment directory

   cd deployment
   

4. Authenticate with Google (Initial OAuth setup for Gemini CLI)

   Skip this step if you have previously configured the Gemini CLI on your host machine.

   docker compose run --rm --service-ports login
   

   Follow the on-screen prompts to select a theme and sign-in method. Use the provided authorization link to complete the process. Credentials will be saved to ~/.gemini/ on your host machine. Use ctrl+c or type /quit to exit the CLI once finished.

   The "Sign in with Google" option utilizes the code-assist subscription, which is free for personal use as of July 2025.

   Troubleshooting GOOGLE_CLOUD_PROJECT errors

   If you encounter the message "Login failed. Message: This account requires the GOOGLE_CLOUD_PROJECT environment variable to be set," you must provide your Google Cloud project ID.

   Locate your project ID in the Google Cloud Console. Open deployment/docker-compose.yaml and find the bridge service. Uncomment the GOOGLE_CLOUD_PROJECT environment variable and replace the placeholder with your ID:

   services:
     bridge:
       environment:
         - GOOGLE_CLOUD_PROJECT=your_google_cloud_project_id_here
   

   Save the file and execute the login command again.

   If you prefer not to use automatic OAuth, install and configure gemini-cli directly on your host. Point the bridge to your local .gemini directory and comment out the login service in docker-compose.yaml.

   To use API key authentication instead of OAuth, set the relevant environment variables within the bridge service configuration.

5. Launch the system

   docker compose up
   

   To rebuild from source: docker compose up --build

   To run in the background: docker compose up --build -d

6. Access the application

   Open your browser to http://localhost:8000

Developer Setup (Local)

Follow these steps if you intend to modify the core engine or utilize a different LLM provider.

Prerequisites

• Python 3.12+
• Node.js and npm/yarn
• uv (install via pip install uv for high-performance Python package management)

Steps

1. Initialize the backend

   cd core
   uv venv
   uv sync
   cp env.sample .env
   # Modify .env if using non-default LLM settings
   uv run run_server.py
   

   The backend will run at http://localhost:8000.

2. Initialize the frontend

   cd frontend
   cp .env.example .env.local
   npm install
   npm run dev
   

   The frontend will run at http://localhost:3000.

Customization and Extension

Common Ground is designed to be extensible without requiring modifications to the core engine.

• Define agent behavior: Create or edit YAML files in core/agent_profiles/profiles/ to establish roles, thought processes (flow_decider), and tool access policies (tool_access_policy).

• Add new tools: Add Python files to core/agent_core/nodes/custom_nodes/. Subclass BaseToolNode and apply the @tool_registry decorator; the framework will automatically discover and integrate the new tool.

• Configure LLMs: Manage providers and models in core/agent_profiles/llm_configs/. You can assign different models to specific agents and handle API keys through environment variables.

• Create handover protocols: For sophisticated interactions—such as a Principal assigning specific tasks to Associates—define data-passing rules in core/agent_profiles/handover_protocols/.

Architecture Overview

The framework processes tasks through a structured, hierarchical workflow:

graph TD
    User["User (via Web UI)"] -- "1: Submit research question" --> PartnerAgent["Partner Agent"]
    PartnerAgent -- "2: Converse, plan, create work blocks" --> PrincipalAgent["Principal Agent"]
    PrincipalAgent -- "3: Assign blocks to" --> AssociateAgents["Associate Agents (parallel)"]
    AssociateAgents -- "4: Execute specific tasks (search, analysis)" --> AssociateAgents
    AssociateAgents -- "5: Return results" --> PrincipalAgent
    PrincipalAgent -- "6: Review, synthesize, produce final report" --> FinalReport["Final Report"]

    subgraph "Real-time Communication (WebSocket)"
        PartnerAgent -- "Status and thoughts" --> WSServer["Server"]
        PrincipalAgent -- "Status and thoughts" --> WSServer
        AssociateAgents -- "Status and thoughts" --> WSServer
        WSServer -- "Streaming updates" --> User
    end

Common Ground prioritizes transparency. By allowing you to see, debug, and govern agent activities in real time, the framework ensures you maintain full control over the research process.