microsoft/multi-agent-marketplace

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.