# How the Multi-Agent System in AI Berkshire Works: Three-Layer Architecture Explained

> Explore the AI Berkshire multi-agent system's three-layer architecture. Discover how four specialized agents work in parallel, driven by financial tools, and managed by a human lead for advanced AI research. Learn more today.

- Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire)
- Tags: architecture
- Published: 2026-06-27

---

**AI Berkshire implements a multi-agent system using a three-layer architecture that orchestrates four specialized research agents to run in parallel, enforced by deterministic financial tools and aggregated by a human-led team lead.**

The `xbtlin/ai-berkshire` repository delivers a sophisticated multi-agent research framework designed for institutional-grade investment analysis. At its core, the **Investment-Team skill** instantiates a miniature research team that mirrors the decision-making processes of legendary investors like Warren Buffett and Charlie Munger. This architecture separates concerns into distinct layers while ensuring rigorous data validation through deterministic Python utilities.

## Three-Layer Architecture Overview

AI Berkshire organizes its multi-agent system into three discrete layers that separate user interaction from execution and calculation.

- **Skill Layer**: Defines high-level commands such as `/investment-team` that map user requests to concrete workflows. The command definition and execution steps live in [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md).

- **Agent Layer**: Instantiates four independent agents, each embodying a master-investor perspective. These agents execute simultaneously, performing their own web searches, data validation, and analysis before reporting back to a central orchestrator.

- **Tool Layer**: Supplies deterministic utilities via [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) that agents must invoke instead of "hand-calculating." This layer provides financial-rigor checks, cross-validation, and report-audit capabilities.

## The Four Specialized Agents

The Investment-Team skill constructs a research team of four agents, each assigned a specific analytical dimension and role model:

- **Business Analyst** (段永平 perspective): Evaluates business models, competitive moats, and user value propositions.
- **Financial Analyst** (巴菲特 perspective): Performs three-scenario valuation, ROE analysis, and market-cap verification.
- **Industry Researcher** (芒格 perspective): Analyzes industry trends, competitive positioning, and long-term market dynamics.
- **Risk Assessor** (李录 perspective): Identifies downside scenarios, regulatory risks, and counter-arguments to the investment thesis.

Each agent receives a role-specific prompt that mandates the use of `WebSearch` and `financial-data` standards, ensuring consistent research methodology across the team.

## Execution Workflow

The multi-agent system follows a rigorous seven-step execution pattern defined in [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md) (lines 34-106).

### Team Creation and Task Definition

The workflow begins with a `TeamCreate` call that establishes a named research unit:

```json
{
  "action": "TeamCreate",
  "team_name": "meituan-research",
  "agent_type": "team-lead"
}

```

Following team creation, the system generates four `TaskCreate` calls, one for each analyst role. Each task contains a specific subject and detailed description that enforces data-source rules and required analysis dimensions (business model, financials, industry, risk) according to [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md) (lines 42-92).

### Parallel Execution and Background Processing

All four `Task` objects dispatch simultaneously in a single message using the `Task` tool with `run_in_background: true`:

```json
{
  "action": "Task",
  "tasks": [
    {"name": "business-analyst", "prompt": "..."},
    {"name": "financial-analyst", "prompt": "..."},
    {"name": "industry-researcher", "prompt": "..."},
    {"name": "risk-assessor", "prompt": "..."}
  ],
  "run_in_background": true
}

```

This parallelism multiplies search coverage and analytical viewpoints, delivering research depth comparable to a real investment team while maintaining workflow reproducibility.

### Data Validation and Tool Integration

Inside each agent's prompt, the system highlights the rule: *"Financial data must come from two independent sources."* Agents must call Python utilities from [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) to embed verification results directly in their partial reports. For example:

```bash
python3 ~/ai-berkshire/tools/financial_rigor.py verify-market-cap --ticker 3690.HK

```

The [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py) module uses `decimal.Decimal` for all numeric calculations, avoiding floating-point drift and ensuring deterministic outputs across different execution environments.

### Progress Reporting and Aggregation

Agents transmit interim findings to the team lead via `SendMessage`. The lead displays a live progress table summarizing each agent's completion status and top 3-5 insights. After all four reports arrive, the lead issues a `shutdown_request` to each agent and aggregates the content into a final structured research report containing:

1. A single-sentence investment conclusion
2. A four-dimensional rating table
3. A data snapshot with verification timestamps
4. Bull-vs-bear arguments
5. A compliance checklist

The final report passes through [`report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/report_audit.py) for random-sample verification before being written to a dated markdown file. The system then removes team resources with `TeamDelete`.

## Architectural Safeguards and Quality Controls

AI Berkshire incorporates three specific mechanisms to ensure research quality:

**Information-Richness Rating**: Before execution, the system assigns an A/B/C rating that determines how aggressively agents probe for counter-evidence. This rating influences research strategy and is presented to agents in their initial prompts (lines 21-29 of [`skills/investment-team.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md)).

**Bias Mitigation**: The team lead must verify whether any agent's output simply mirrors market consensus. If detected, the lead forces a "reverse-check" to surface hidden risks and contrarian viewpoints.

**Deterministic Tooling**: All numeric calculations route through [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py), which enforces financial-rigor standards including market-cap verification and three-scenario valuation. This prevents calculation errors that could propagate through the multi-agent workflow.

## Summary

- AI Berkshire uses a **three-layer architecture** (Skills, Agents, Tools) to separate user commands from parallel execution and deterministic calculation.
- The **Investment-Team skill** orchestrates four specialized agents (Business, Financial, Industry, Risk) that run simultaneously using `run_in_background: true`.
- Agents must invoke **deterministic utilities** from [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) for all financial calculations, using `decimal.Decimal` to ensure precision.
- The workflow enforces **dual-source verification** for all financial data, with automated auditing via [`report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/report_audit.py) before final publication.
- **Bias-mitigation protocols** require the team lead to challenge consensus views and force reverse-checks when agents echo market sentiment.

## Frequently Asked Questions

### What is the three-layer architecture in AI Berkshire's multi-agent system?

The three-layer architecture separates concerns into **Skills** (user-facing commands like `/investment-team`), **Agents** (the four parallel research specialists), and **Tools** (deterministic Python utilities in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)). This separation ensures that agents focus on analysis while rigorous calculation and data validation happen through standardized, reproducible utilities.

### How do the four agents in the Investment-Team skill collaborate?

The four agents (Business Analyst, Financial Analyst, Industry Researcher, and Risk Assessor) work **in parallel rather than sequentially**, each receiving role-specific prompts that mandate independent research. They report findings to a human-led team lead via `SendMessage`, and the lead aggregates these into a unified report only after all four agents complete their analysis and pass data-verification checks.

### What ensures data accuracy in the AI Berkshire multi-agent system?

Data accuracy relies on **mandatory dual-source verification** enforced through [`skills/financial-data.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/financial-data.md) standards. Agents must call [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) functions (such as `verify-market-cap`) rather than performing calculations independently. The system uses `decimal.Decimal` for all numeric operations to prevent floating-point errors, and final reports undergo random-sample verification via [`report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/report_audit.py) before publication.

### How does the system handle bias and consensus thinking?

The team lead actively monitors for **consensus bias** by checking whether agent outputs merely reflect market sentiment rather than independent analysis. When detected, the lead triggers a "reverse-check" that forces agents to seek out contrarian evidence and hidden risks. Additionally, the **information-richness rating** (A/B/C) adjusts research depth based on the need for counter-evidence investigation.