ConvoArena

ConvoArena is a platform for running real-time online experiments on human + LLM group conversations, in which AI agents can mediate a group discussion or privately assist individual participants.

ConvoArena is a hard fork of Deliberate Lab, developed by the Cornell TrAuSt moonshot team. It is deployed at convoarena.infosci.cornell.edu.

What's new in ConvoArena

For the general platform (experiments, stages, cohorts, agent participants and mediators), refer to the Deliberate Lab repository and documentation. ConvoArena adds the following, each pointing to where it lives in this repo:

• Private Assistants: A private assistant (also called an agent assistant) privately helps one participant during a chat, in a box below their message input, and can see what they're typing before they send it. See the docs and functions/src/assistant/.
• Control On When to Intervene: A separate should-respond prompt decides whether to speak, so researchers can tune when mediators and assistants intervene without changing what they say. Previously, one prompt did both. ConvoArena also supports auditing experiments that hide or rewrite some mediator messages. See the docs and functions/src/chat/chat.agent.ts.
• Improved Agent Customization: Prompts are built from reusable blocks and can chain several steps, start with an initialization prompt, and give agent participants an evolving character and thought history. See the docs and utils/src/structured_prompt.ts.
• Large-Scale Simulations with ConvoKit: ConvoArena allows large-scale conversation simulations via ConvoKit.

Status

ConvoArena is research software under active development. Agent assistants are in alpha, and some features (multi-step prompts, initialization, and character and thought prompts) can currently only be configured through the API. The hosted instance at convoarena.infosci.cornell.edu only lets allowlisted researchers create experiments.

Core concepts

An experiment is an ordered sequence of stages (survey, chat, ranking, and more) that a cohort of participants moves through together. Participants can be humans or LLM-driven agent participants. A mediator speaks to the whole group in a chat, while an agent assistant privately helps a single participant. See Mediators, agent participants and agent assistants for a comparison, and the Deliberate Lab docs for the underlying platform.

Repo layout

This is an npm-workspaces monorepo:

• frontend/: the web app, which includes the experiment builder, the experimenter dashboard and the participant views.
• functions/: Firebase Cloud Functions, including the REST/callable endpoints, Firestore triggers, and the agent, mediator and assistant LLM logic.
• utils/: shared types, validation schemas and stage logic (@deliberation-lab/utils), used by both frontend/ and functions/.
• scripts/: the deliberate_lab Python client, demo scripts, and local dev tooling.
• docs/: the ConvoArena docs site (new features and setup; links to the Deliberate Lab docs for the core platform).

Getting started

Prerequisites

• Node.js 22+ (nvm use picks the right version)
• Java, required by the Firebase emulators
• uv, for the Python client and demo scripts
• A Gemini API key, if you want to run the demo experiment

Run locally

From the repo root:

nvm use
npm install     # run only from the repo root, never inside a workspace
./run_locally.sh

run_locally.sh builds utils and functions in watch mode, starts the Firebase emulators with test data, starts the frontend, and seeds a local DL_API_KEY for the Python client.

When it's running, open http://localhost:4201 and log in as experimenter@google.com. That test profile is already on the allowlist, so you can create experiments right away (not-experimenter@google.com is a second profile without access). The emulator dashboard is at http://localhost:4000.

To also create and run a demo experiment, copy .env.example to .env (it's gitignored), fill in GEMINI_API_KEY, and run ./run_locally.sh --startup. Without the key, the demo's agents can't respond.

To run each piece manually, see docs/developers/run-locally.md. npm run doctor checks your environment for common setup problems.

Deployment

ConvoArena's backend runs on Firebase (Firestore, Realtime Database, Storage and Cloud Functions). The frontend is a static build that you can host anywhere. If you don't have a Firebase project yet, see Create a Firebase project. Then deploy the backend:

npx firebase login
npx firebase deploy

See Deploying for deploying only some parts (--only functions, --only firestore, etc.), building and hosting the frontend, and giving researchers access through the allowlist.

Python client

scripts/ contains a fully typed Pydantic client for the REST API, for creating experiments, running simulations and exporting data from code. See scripts/README.md.

Citation

ConvoArena is a fork of Deliberate Lab. If you use it in your work, please cite:

@misc{qian2025deliberatelab,
  author={Crystal Qian and Vivian Tsai and Michael Behr and Nada Hussein and Léo Laugier and Nithum Thain and Lucas Dixon},
  title={Deliberate Lab: A Platform for Real-Time Human-AI Social Experiments},
  url={https://arxiv.org/abs/2510.13011},
  year={2025},
}

See also CITATION.cff, or "Cite this repository" in the GitHub sidebar for APA format.

License

Licensed under the Apache License, Version 2.0. See LICENSE. Portions copyright 2024 DeepMind Technologies Limited.