# microsoft/multi-agent-marketplace architecture

> Architecture diagram of the GitHub repository microsoft/multi-agent-marketplace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/multi-agent-marketplace
- Repository: https://github.com/microsoft/multi-agent-marketplace

## Overview

1. **Overall shape**
   - This is a Python monorepo for simulating two-sided marketplaces driven by LLM agents.
   - The center of gravity is the `magentic-marketplace` Python package; everything else supports data generation, experimentation, visualization, or documentation.

2. **Core simulation domain**
   - The `marketplace` package contains the simulation logic: buyer/seller agent behavior, marketplace actions, message passing, proposal/history storage, and the search/protocol layer.
   - This is the main business boundary for “how a marketplace works” versus “how it is served or analyzed.”

3. **Agent layer**
   - Agents are split into **customer** and **business** roles under `marketplace/agents/...`.
   - Each role has its own prompts, response models, and agent implementation, which indicates role-specific LLM interaction rather than one generic agent abstraction.
   - Shared base classes and storage modules suggest agents persist conversational state and proposals across turns.

4. **Protocol and search subsystem**
   - `marketplace/protocol` defines the interaction contract for discovery and messaging: fetch messages, send messages, search, and protocol orchestration.
   - The search layer includes multiple strategies such as lexical, filtered, optimal, simple, and RNR variants, implying the marketplace can be configured with different retrieval/matching behavior.
   - This subsystem is important because it mediates which businesses customers see and in what order, affecting experimental outcomes like position bias and welfare.

5. **LLM abstraction layer**
   - `marketplace/llm` provides a model-agnostic wrapper with concrete client integrations for **OpenAI**, **Anthropic**, and **Gemini**.
   - There is a functional/common layer and config module, so model calls are centralized behind a provider boundary rather than scattered through the simulation.
   - This makes provider choice an architectural concern: experiments can swap models without changing marketplace logic.

6. **Platform layer: server, client, and databases**
   - The `platform` package is the runtime/service boundary around the core marketplace logic.
   - It includes:
     - a server with routes for agents, actions, logs, and health,
     - a client SDK for talking to that server,
     - database abstractions with both **SQLite** and **PostgreSQL** backends,
     - auth dependencies/service, and a launcher/logger.
   - This suggests the simulation can run as a service with persisted state and a programmatic API, not only as a local script.

7. **Data model and persistence**
   - The platform and marketplace each have `models.py`/`shared` modules, indicating a structured domain model that crosses process boundaries.
   - Database query modules are separated by concern (`agents`, `actions`, `logs`), which implies the persistent store is organized around marketplace events and agent state.
   - Logs are first-class: LLM calls, actions, and agent interactions are intended to be queried after a run, not just printed.

8. **Experiment execution and analysis**
   - The `experiments` subpackage under `magentic_marketplace` provides CLI-facing orchestration for running experiments, exporting results, listing experiments, analytics, and audit/tracing.
   - The repo also contains standalone experiment scripts under `experiments/` for specific studies such as competitive, malicious, position bias, and consideration set size.
   - This split suggests two levels: reusable experiment infrastructure in the package, and research-specific notebooks/scripts at the repo root.

9. **Data sets and scenario families**
   - The `data/` directory is the primary experiment input space.
   - It contains many scenario families: `mexican_*`, `contractors_*`, `competitive_description`, `malicious_description`, and `position_bias`.
   - Each scenario has separate `businesses/` and `customers/` YAML files, plus `baseline_utilities.json` in many datasets, so the simulation inputs are declarative and file-based.

10. **Data generation pipeline**
    - `data/data_generation_scripts` contains scripts for generating people, items, customers/businesses, baseline utilities, and validators.
    - This is an offline content-generation boundary: it produces the YAML/JSON experiment assets consumed by the simulation, rather than participating in runtime behavior.
    - The presence of “contractors” and “mexican” generation variants suggests the repo supports multiple domain templates and scale tiers.

11. **Visualization/UI**
    - There are two UI layers:
      - a Python-served UI in `packages/magentic-marketplace/src/magentic_marketplace/ui`,
      - a separate TypeScript/Vite app in `packages/marketplace-visualizer`.
    - The visualizer consumes database-backed data and renders businesses, customers, conversations, and panels, which means it is primarily an inspection/debugging tool for simulation output.
    - The UI is not the source of truth; it reads from the persisted marketplace state/logs.

12. **Repository tooling and automation**
    - The repo uses `uv` for Python dependency management, `docker-compose` for the database service, and GitHub Actions for tests, linting, type checking, and docs deployment.
    - Docs are built with VitePress under `docs/`, and the repository includes scripts for env generation and basic repo hygiene checks.
    - These tools support the architecture by enforcing consistency across simulation code, data assets, and experiment reproducibility.

13. **Typical end-to-end flow**
    - A user selects a dataset in `data/...`, runs the CLI or an experiment script, the simulation loads business/customer YAML plus baseline utilities, agents interact through the protocol and LLM layer, and the platform persists actions/logs in SQLite or PostgreSQL.
    - After execution, analytics/export tools read those persisted traces and produce result summaries, plots, or UI views.

14. **Key boundaries to draw in an architecture diagram**
    - Separate **offline asset generation** from **online simulation execution**.
    - Separate **core marketplace logic** from **LLM providers** and from **platform/persistence**.
    - Treat the **UI/visualizer** as a consumer of stored results, not part of the simulation engine.
    - Treat **experiments** as orchestration around the core engine rather than core domain code.

Main entry points: [`packages/magentic-marketplace/src/magentic_marketplace/platform`](https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/platform) (Platform), [`packages/magentic-marketplace/src/magentic_marketplace/platform/database`](https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/platform/database) (Databases), [`packages/magentic-marketplace/src/magentic_marketplace/marketplace`](https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/marketplace) (Marketplace), [`packages/magentic-marketplace/src/magentic_marketplace/platform/server`](https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/platform/server) (Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_core["Core engine"]
  node_n_marketplace["Marketplace<br/>simulation core"]
  node_n_agents["Agents"]
  node_n_protocol["Protocol<br/>interaction contract"]
  node_n_search["Search<br/>retrieval strategies"]
  node_n_llm["LLM layer<br/>provider wrapper"]
  node_n_shared_models["Shared models<br/>domain models<br/>[models.py]"]
end

subgraph group_g_platform["Platform"]
  node_n_platform["Platform<br/>runtime service"]
  node_n_server["Server"]
  node_n_client["Client SDK<br/>api client"]
  node_n_db[("Databases<br/>persistence backends")]
  node_n_platform_models["Platform models<br/>service models<br/>[models.py]"]
end

subgraph group_g_research["Research"]
  node_n_cli["CLI<br/>entrypoint<br/>[cli.py]"]
  node_n_exp_pkg["Experiments<br/>orchestration"]
  node_n_exp_scripts["Study scripts<br/>research scripts"]
end

subgraph group_g_data["Data assets"]
  node_n_data_assets["Scenario data<br/>dataset inputs"]
  node_n_data_gen["Data gen<br/>asset generation"]
end

subgraph group_g_ui["Inspection UI"]
  node_n_python_ui["Python UI<br/>served UI"]
  node_n_visualizer["Visualizer<br/>typescript app"]
end

subgraph group_g_docs["Docs and tooling"]
  node_n_docs_site["Docs site<br/>documentation"]
  node_n_repo_tooling["Repo tooling<br/>automation"]
end

node_n_cli -->|"runs"| node_n_marketplace
node_n_cli -->|"orchestrates"| node_n_exp_pkg
node_n_exp_pkg -->|"drives"| node_n_marketplace
node_n_exp_scripts -->|"uses"| node_n_exp_pkg
node_n_exp_scripts -->|"loads"| node_n_data_assets
node_n_data_gen -->|"produces"| node_n_data_assets
node_n_marketplace -->|"contains"| node_n_agents
node_n_marketplace -->|"coordinates"| node_n_protocol
node_n_protocol -->|"uses"| node_n_search
node_n_agents -->|"calls"| node_n_llm
node_n_agents -->|"reads/writes"| node_n_shared_models
node_n_protocol -->|"queries"| node_n_db
node_n_db -->|"stores"| node_n_platform_models
node_n_server -->|"persists"| node_n_db
node_n_server -->|"serves"| node_n_platform_models
node_n_client -->|"consumes"| node_n_server
node_n_platform -->|"includes"| node_n_server
node_n_platform -->|"includes"| node_n_client
node_n_platform -->|"includes"| node_n_db
node_n_platform -->|"shares"| node_n_shared_models
node_n_python_ui -->|"renders"| node_n_platform
node_n_visualizer -->|"reads"| node_n_db
node_n_docs_site -->|"documents"| node_n_exp_pkg
node_n_docs_site -->|"documents"| node_n_platform
node_n_repo_tooling -->|"deploys"| node_n_docs_site
node_n_repo_tooling -->|"validates"| node_n_platform
node_n_repo_tooling -->|"checks"| node_n_data_assets

click node_n_cli "https://github.com/microsoft/multi-agent-marketplace/blob/main/packages/magentic-marketplace/src/magentic_marketplace/cli.py"
click node_n_exp_pkg "https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/experiments"
click node_n_marketplace "https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/marketplace"
click node_n_agents "https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/marketplace/agents"
click node_n_protocol "https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/marketplace/protocol"
click node_n_search "https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/marketplace/protocol/search"
click node_n_llm "https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/marketplace/llm"
click node_n_shared_models "https://github.com/microsoft/multi-agent-marketplace/blob/main/packages/magentic-marketplace/src/magentic_marketplace/marketplace/shared/models.py"
click node_n_platform "https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/platform"
click node_n_server "https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/platform/server"
click node_n_client "https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/platform/client"
click node_n_db "https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/platform/database"
click node_n_platform_models "https://github.com/microsoft/multi-agent-marketplace/blob/main/packages/magentic-marketplace/src/magentic_marketplace/platform/shared/models.py"
click node_n_data_assets "https://github.com/microsoft/multi-agent-marketplace/tree/main/data"
click node_n_data_gen "https://github.com/microsoft/multi-agent-marketplace/tree/main/data/data_generation_scripts"
click node_n_exp_scripts "https://github.com/microsoft/multi-agent-marketplace/tree/main/experiments"
click node_n_python_ui "https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/ui"
click node_n_visualizer "https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/marketplace-visualizer/src"
click node_n_docs_site "https://github.com/microsoft/multi-agent-marketplace/tree/main/docs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_marketplace,node_n_agents,node_n_protocol,node_n_search,node_n_llm,node_n_shared_models toneBlue
class node_n_platform,node_n_server,node_n_client,node_n_db,node_n_platform_models toneAmber
class node_n_cli,node_n_exp_pkg,node_n_exp_scripts toneMint
class node_n_data_assets,node_n_data_gen toneRose
class node_n_python_ui,node_n_visualizer toneIndigo
class node_n_docs_site,node_n_repo_tooling toneTeal
```

## Components

### Core engine

Marketplace simulation and LLM abstractions

- [Marketplace](https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/marketplace): simulation core · Core marketplace simulation domain and behavior · `packages/magentic-marketplace/src/magentic_marketplace/marketplace`
- [Agents](https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/marketplace/agents): role agents · Customer and business agent implementations with prompts and response models · `packages/magentic-marketplace/src/magentic_marketplace/marketplace/agents`
- [Protocol](https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/marketplace/protocol): interaction contract · Discovery, search, fetch-message, and send-message orchestration · `packages/magentic-marketplace/src/magentic_marketplace/marketplace/protocol`
- [Search](https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/marketplace/protocol/search): retrieval strategies · Lexical, filtered, optimal, simple, and RNR search variants · `packages/magentic-marketplace/src/magentic_marketplace/marketplace/protocol/search`
- [LLM layer](https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/marketplace/llm): provider wrapper · Model-agnostic LLM abstraction and provider clients · `packages/magentic-marketplace/src/magentic_marketplace/marketplace/llm`
- [Shared models](https://github.com/microsoft/multi-agent-marketplace/blob/main/packages/magentic-marketplace/src/magentic_marketplace/marketplace/shared/models.py): domain models · Cross-boundary marketplace data models · `packages/magentic-marketplace/src/magentic_marketplace/marketplace/shared/models.py`

### Platform

Service layer, persistence, client, and shared runtime models

- [Platform](https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/platform): runtime service · Server, client, database, auth, launcher, and logger around the marketplace core · `packages/magentic-marketplace/src/magentic_marketplace/platform`
- [Server](https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/platform/server): api server · HTTP server and routes for agents, actions, logs, and health · `packages/magentic-marketplace/src/magentic_marketplace/platform/server`
- [Client SDK](https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/platform/client): api client · Programmatic client for the platform server · `packages/magentic-marketplace/src/magentic_marketplace/platform/client`
- [Databases](https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/platform/database): persistence backends · SQLite and PostgreSQL storage implementations plus queries · `packages/magentic-marketplace/src/magentic_marketplace/platform/database`
- [Platform models](https://github.com/microsoft/multi-agent-marketplace/blob/main/packages/magentic-marketplace/src/magentic_marketplace/platform/shared/models.py): service models · Runtime-facing platform data models and converters · `packages/magentic-marketplace/src/magentic_marketplace/platform/shared/models.py`

### Research

Reusable experiment orchestration and study-specific scripts

- [CLI](https://github.com/microsoft/multi-agent-marketplace/blob/main/packages/magentic-marketplace/src/magentic_marketplace/cli.py): entrypoint · Package entrypoint for running marketplace workflows · `packages/magentic-marketplace/src/magentic_marketplace/cli.py`
- [Experiments](https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/experiments): orchestration · Reusable experiment commands for run, export, analytics, audit, and trace extraction · `packages/magentic-marketplace/src/magentic_marketplace/experiments`
- [Study scripts](https://github.com/microsoft/multi-agent-marketplace/tree/main/experiments): research scripts · Standalone experiment runners, analysis, and plots for named studies · `experiments`

### Data assets

Declarative scenario inputs and offline generation pipeline

- [Scenario data](https://github.com/microsoft/multi-agent-marketplace/tree/main/data): dataset inputs · Declarative business/customer datasets and baseline utilities · `data`
- [Data gen](https://github.com/microsoft/multi-agent-marketplace/tree/main/data/data_generation_scripts): asset generation · Offline scripts for generating customers, businesses, items, and baselines · `data/data_generation_scripts`

### Inspection UI

Python UI and standalone visualizer for stored runs

- [Python UI](https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/magentic-marketplace/src/magentic_marketplace/ui): served UI · Package-served UI for inspecting marketplace state · `packages/magentic-marketplace/src/magentic_marketplace/ui`
- [Visualizer](https://github.com/microsoft/multi-agent-marketplace/tree/main/packages/marketplace-visualizer/src): typescript app · Standalone Vite app for browsing stored marketplace runs · `packages/marketplace-visualizer/src`

### Docs and tooling

Documentation, CI, and repo automation

- [Docs site](https://github.com/microsoft/multi-agent-marketplace/tree/main/docs): documentation · VitePress concepts and usage documentation · `docs`
- **Repo tooling**: automation · CI workflows, environment scripts, compose config, and dependency locks

## Connections

- CLI → Marketplace: runs · CLI invokes the simulation engine
- CLI → Experiments: orchestrates · CLI exposes experiment commands
- Experiments → Marketplace: drives · Reusable experiment logic runs marketplace simulations
- Study scripts → Experiments: uses · Research scripts wrap the reusable experiment package
- Study scripts → Scenario data: loads · Study scripts consume declarative scenario data
- Data gen → Scenario data: produces · Generation scripts create dataset YAML and baseline JSON assets
- Marketplace → Agents: contains · Core simulation includes buyer and seller agent roles
- Marketplace → Protocol: coordinates · Marketplace behavior is mediated through the interaction protocol
- Protocol → Search: uses · Protocol relies on retrieval and ranking strategies
- Agents → LLM layer: calls · Agents use the shared LLM provider boundary
- Agents → Shared models: reads/writes · Agents persist shared marketplace state and proposals
- Protocol → Databases: queries · Protocol actions are backed by database access
- Databases → Platform models: stores · Persistence layer maps platform runtime models
- Server → Databases: persists · Server routes read and write marketplace state through the database
- Server → Platform models: serves · API exposes platform runtime models
- Client SDK → Server: consumes · Client SDK talks to the server API
- Platform → Server: includes · Platform package includes the server runtime
- Platform → Client SDK: includes · Platform package includes the client SDK
- Platform → Databases: includes · Platform package includes persistence backends
- Platform → Shared models: shares · Runtime and core share common models across boundaries
- Python UI → Platform: renders · Served UI sits on top of platform data and runtime
- Visualizer → Databases: reads · Visualizer consumes persisted run data
- Docs site → Experiments: documents · Docs explain CLI and experiment workflows
- Docs site → Platform: documents · Docs cover platform concepts and usage
- Repo tooling → Docs site: deploys · Repo tooling includes docs deployment automation
- Repo tooling → Platform: validates · CI and scripts validate the package and platform code
- Repo tooling → Scenario data: checks · Automation helps keep data assets and experiments consistent