TinyTroupe

TinyTroupe is an experimental Python library open-sourced by Microsoft, with the theme of "LLM-based multi-agent persona simulation for enhanced imagination and business insight". It allows the simulation of people with specific personalities, interests, and goals. These artificial agents are called TinyPerson, and they are able to listen to the user and other agents, respond, and carry out activities in the simulated TinyWorld environment. The library generates realistic simulated behavior through large language models (especially GPT-4), thereby studying various persuasive interactions and consumer types. Its focus is on understanding human behavior, rather than directly supporting human behavior like AI assistants, so it includes some specialized mechanisms that only make sense in simulation scenarios. Unlike other gamified large language model simulation approaches, TinyTroupe is intended to inspire productivity and business scenarios, helping to enable more successful projects and products.

Main uses and application scenarios:

• Advertising: before spending money, use simulated audiences to evaluate digital ads offline (for example, Bing Ads).
• Software testing: provide test inputs to systems (such as search engines, chatbots, or Copilot), and then evaluate the results.
• Training and exploratory data: generate realistic synthetic data, which can later be used to train models or conduct opportunity analysis.
• Product and project management: read project or product proposals and give feedback from the perspective of specific roles (such as doctors, lawyers, and various knowledge workers).
• Brainstorming: simulate focus groups to obtain high-quality product feedback at lower cost.

Main capabilities and mechanisms:

• Highly customizable personas, including deeper settings such as personality traits, preferences, and beliefs, and support for defining personas through JSON files and loading them with TinyPerson.load_specification().
• Persona fragments, used to reuse persona elements across different agents.
• Large language model-based logical propositions (Propositions), used to monitor agent behavior, such as persona_adherence, hard_persona_adherence, self_consistency, fluency, and so on.
• Interventions, allowing event-based simulation modifications to be specified.
• TinyPerson's action correction mechanism, improving adherence to persona settings, self-consistency, and fluency.
• TinyPersonFactory uses a plan-based approach to generate new agents, supporting moreSampling of large-scale populations, with the ability to generate agents in parallel.
• TinyWorld runs agents in parallel at each simulation step, speeding up simulation.
• The InPlaceExperimentRunner class, which supports running controlled experiments (such as A/B testing) in a single file.
• SimulationExperimentEmpiricalValidator, which uses statistical tests (t-test, KS test) to compare simulation results with real-world empirical data to validate whether the simulation matches real human behavior.
• AgentChatJupyterWidget, which supports directly interacting and chatting with agents in a Jupyter notebook.
• Cost tracking tools at the client, environment, and agent levels, used to monitor API costs.
• Experimental, limited Ollama support for local models.
• Internal LLM usage is better supported through the LLMChat class and the @llm decorator, which can convert any standard Python function into an LLM-based function.
• The configuration mechanism has been refactored, and in addition to the static config.ini file, it also supports dynamic programmatic reconfiguration.
• The LLM API cache now uses JSON instead of pickle.
• The default model is gpt-5-mini; the GPT-5 series uses different parameters from the GPT-4 series and may require corresponding adjustments to config.ini settings. Older models (gpt-4.1-mini, gpt-4o-mini) are still supported.

Usage and prerequisites: Running this library requires Python 3.10 or higher (Anaconda is assumed, but other Python distributions can also be used), Git (for cloning the repository and installing the library via pip), and access to Azure OpenAI Service or the OpenAI GPT-4 API. For Azure OpenAI Service, the AZURE_OPENAI_KEY and AZURE_OPENAI_ENDPOINT environment variables need to be set; for OpenAI, the OPENAI_API_KEY environment variable needs to be set, for example by executing export OPENAI_API_KEY=your-key-here on Linux/macOS, and on Windows PowerSheExecute $env:OPENAI_API_KEY="your-key-here" on ll. By default, config.ini uses the OpenAI API and gpt-5-mini as the main model, and can be customized by placing a custom config.ini in the folder where the program or notebook is run; the examples/ folder provides example configuration files. To ensure that no harmful content is generated during simulation, it is strongly recommended to use content filters at the API level; if Azure OpenAI is used, it provides extensive content moderation support. If a content filter blocks an API call, the library will throw an exception and the simulation cannot continue. TinyTroupe is mainly developed for OpenAI models and compatible endpoints, in order to fully leverage the capabilities of specific models, rather than attempting to adapt to arbitrary models.

Examples:

• Customer interviews: a business consultant talks with a banker, gradually digging deeper into information until obtaining a satisfactory specific project idea.
• TV advertising evaluation: evaluate multiple online advertising options and select the best one, automatically extracting each agent's choice and calculating the overall preference.
• Product brainstorming: conduct a focus group around new AI features for Microsoft Word, by manipulating the environment to let agents interact with each other, and extracting results in a machine-readable way.
• Bottled Spanish gazpacho market research: simulate a market research questionnaire, and use statistical tests (t-test, KS test) to compare the response distributions of simulated agents and real respondents.
• AI children's storytelling market research: simulate parents evaluating and ranking different AI story devices, using Borda count and preferred share analysis to compare with real survey data. Screenshots of examples may not fully match local run results as updates occur, but the overall structure and content should be similar. Currently, simulation output visualizes better on a dark background, and it is recommended to use a dark theme in the Jupyter client.

Limitations and legal notices: TinyTroupe is still in an early stage, is an ongoing research project, is still under extensive development and needs further organization; the API will still change frequently and may break existing programs. It is for research and simulation only, and users are fully responsible for any use of the generated output; use is subject to several important additional legal considerations, and the full legal disclaimer should be read before use. Local model support is not currently a priority for the core team.

Category: ai-agent