microsoft/group_ai_lab

microsoft/group_ai_lab

Description: An open-source platform for conducting behavioral experiments involving group-AI interaction.

Language: JavaScript

License: NOASSERTION

Stars: 1

Forks: 5

Open issues: 17

Created: 2026-02-17T15:50:29Z

Pushed: 2026-09-16T02:55:54Z

Default branch: main

Fork: no

Archived: no

README:

Group-AI Interaction Laboratory (GRAIL)


Overview

Group-AI Interaction Laboratory (GRAIL) is an open-source experimental platform for studying how groups of people interact with AI systems in real-time, multi-participant tasks. Built to support high-throughput, synchronous group experiments, GRAIL makes it easy to design, deploy, and analyze studies of AI-mediated collaboration—such as LLM-based facilitation—while handling the logistical complexity of live group coordination, chat interfaces, and data collection. It is designed to help researchers flexibly explore the design space of group-AI interaction without needing to build bespoke infrastructure from scratch.

What is GRAIL made for?

GRAIL enables researchers to design and run online experiments in which groups of participants interact synchronously with a shared large language model. Our accompanying [paper]() demonstrates GRAIL in use through a large-scale experimental study, illustrating the kinds of group–AI interaction research the platform is designed to support.

Intended uses

GRAIL is intended for research use in the study of group–AI interaction. It is best suited for designing and running controlled online experiments in which groups of participants interact synchronously with a shared AI system, such as studies of facilitation, moderation, coordination, or collaborative decision-making.

GRAIL is shared with the research community to support reproducibility of our published findings and to enable further exploration of how AI systems shape group processes and outcomes in interactive settings.

Findings generated using GRAIL are meant to inform research and design, rather than to directly guide operational decisions without additional validation, domain adaptation, and oversight.

Out-of-scope uses

GRAIL is not intended for direct deployment as a production system or for use in real-world, high-stakes decision-making contexts. It is released for research purposes.

Getting started

GRAIL was developed using the open-source Empirica framework (v1.12.0).

Project structure

.empirica/ # Empirica configuration (treatments, lobbies, auth)
client/ # React front-end (participant UI, intro/exit steps)
src/
intro-exit/ # Consent, introduction, surveys, and exit screens
components/ # Reusable UI components (chat, timer, player list, player-specific views)
server/ # Back-end configuration (game logic, LLM integration)
src/
callbacks.js # Core game and LLM logic
LLMConfig.js # LLM system prompts
HPTConfig.json # Task stimuli configuration

Running GRAIL locally

1. Install Empirica (v1.12.0) following the instructions here. 2. Install the client-side and server-side packages by running npm install within ./client and ./server respectively. 3. Copy ./server/.env.example to ./server/.env and fill in your LLM configuration (see [Connecting an LLM](#connecting-an-llm) below). 4. Copy .empirica/empirica.toml.example to .empirica/empirica.toml and set your own srtoken and admin password. 5. From the root project directory, run empirica to launch the server. By default, the admin panel should be accessible through your browser at localhost:3000/admin. The default username and password are configured in .empirica/empirica.toml.

Running GRAIL remotely

Follow [this guide]() for deploying Empirica experiments on Ubuntu servers.

Configuring GRAIL

Connecting an LLM

GRAIL calls the OpenAI Responses API to generate LLM facilitator messages. Configure the connection by creating a ./server/.env file with the following variables:

| Variable | Description | Default | | --- | --- | --- | | OPENAI_API_KEY | Your OpenAI API key (required) | — | | OPENAI_MODEL | Model to use (e.g., gpt-4o, gpt-5-mini) | gpt-4o | | LLM_API_ENDPOINT | API endpoint URL | https://api.openai.com/v1/responses | | LLM_MAX_OUTPUT_TOKENS | Maximum number of tokens in the LLM response | 1000 |

See ./server/.env.example for a template. Only max_output_tokens is sent as a model parameter by default. If you need to pass additional model-specific parameters (e.g., temperature, reasoning), you can add them to the data object in server/src/callbacks.js.

Any endpoint compatible with the OpenAI Responses API format can be used by changing LLM_API_ENDPOINT.

Creating and editing treatments

Within GRAIL (and Empirica, more broadly), experimental treatments are defined as combinations of factors, which are individual dimensions (e.g., group size, task duration, etc.). Treatments are defined in .empirica/treatments.yaml. The currently implemented factors are:

| Factor | Description | | --- | --- | | facilitation | Facilitation type: none, human, or LLM | | playerCount | Number of participants per game | | gameDuration | Duration of the task stage in minutes | | introDuration | Duration of the introduction stage in minutes | | llmRequestInterval | How often (in seconds) the server queries the LLM | | requireLLMMessage | Whether the LLM must respond every interval (true) or can refrain from responding (false) | | fullInfo | Whether participants receive full or partial information | | hiddenInfoCue | Whether participants are shown a cue about differing information at the beginning of the discussion|

To add or modify factors & treatments, you can edit .empirica/treatments.yaml directly, or through the "Factors" and "Treatments" tabs in the admin panel. New factors can also be added there and then referenced in server/src/callbacks.js.

Configuring task stimuli

The included task configuration demonstrates GRAIL with a *hidden profile task*, in which participants each receive partial information and must share it with the group to reach an optimal decision. However, GRAIL can be adapted to other text-based group tasks with minimal changes — simply replace the stimuli in the config file, update the intro steps and LLM system prompt to match your task, and adjust the exit...