Content
# 🧠 a2a-protocol-demo6: Integrated Agent Architecture
> **"The Convergence"** - The ultimate example of integrating the A2A Protocol, multi-agent orchestration, and intelligent memory management.
This project is the culmination of the **Agent Architecture Learning Series**. It no longer demonstrates a single technical point but organically combines the three pillars of **Communication**, **Memory**, and **Orchestration** to build an intelligent system with production-level design principles.
## 🎯 Core Value: What Problem Does It Solve?
In previous demos, we addressed:
* **Demo 1-3**: How to enable communication between Client and Server? (A2A Protocol)
* **Demo 4**: What to do when chat history is too long and token overflow occurs? (Memory Funnel)
* **Demo 5**: How to execute data collection and weather checking in parallel? (Multi-Agent Workflow)
**Demo 6 addresses the problem:**
> When **Agent A (Researcher)** retrieves 5000 words of information and **Agent B (Weather Agent)** retrieves 20 words of weather data, how does the orchestrator safely deliver this heterogeneous data to **Agent C (Writer)** without exceeding the context window of the LLM?
## 🏗️ Architecture Design Diagram (The Big Picture)
This system adopts a **"Memory-Centric Orchestration"** model.
```
graph TD
%% External Interaction
Client[Client] -->|1. JSON-RPC Request| Server[Gateway]
Server -->|2. Dispatch| Workflow[🧠 Workflow Engine]
%% Stage One: Input Processing
Workflow -->|3. Create User Slot| Memory[(📚 Memory Store)]
%% Stage Two: Concurrent Execution Tools
subgraph "Parallel Execution Layer"
Workflow -->|4. Call| Research[🔎 Research Agent]
Workflow -->|4. Call| Weather[🌤️ Weather Agent]
end
%% Stage Three: Data Backflow and Compression
Research -->|5. Return Massive Data (Raw Data)| Memory
Weather -->|5. Return Structured Data| Memory
%% Key Link: Funnel Compression
Memory -.->|6. Read Context| Funnel[📉 Context Funnel]
Funnel -->|7. Compression Strategy (Discard/Summary)| Prompt[Concise Prompt]
%% Stage Four: Final Generation
Prompt -->|8. Input| Writer[✍️ Writer Agent]
Writer -->|9. Generate Reply Slot| Memory
Writer -->|10. Return Result| Client
```
## 📂 Project Code Structure
* `protocol.py`: **[Cornerstone]** Defines the universal `Slot` data structure and `JSONRPC` protocol package for the entire system.
* `memory.py`: **[Hippocampus]** Responsible for storing Slots. It includes a **Context Funnel** that automatically executes a "slimming" algorithm during reads.
* `workflow.py`: **[Commander]** The core logic layer. It controls when Agents run, where results are stored, and when writing is triggered.
* `agents.py`: **[Executor]** Pure business logic (collection, querying, writing), unconcerned with the length of the context, just focused on the task.
* `algorithms.py`: **[Toolbox]** Simulates embedding calculations and LLM compression algorithms.
* `server.py` / `client.py`: **[Gateway]** Standard HTTP interface layer.
## 🚀 Quick Start
### 1. Environment Setup
```bash
# No complex dependencies are required, just the basic FastAPI suite
pip install fastapi uvicorn httpx pydantic numpy
```
### 2. Start the Server
```bash
python server.py
```
> You will see the message `🚀 Server started`.
### 3. Run the Client
Open a new terminal window:
```bash
python client.py
```
## 🧐 Observe the Logs (Learning by Logging)
After running, pay close attention to the **[Funnel]** related logs output in the server console, as this is the essence of Demo 6:
```text
# 1. Data stored normally
💾 [Memory] Stored Slot: Type=tool_log, Role=Researcher, Len=600 <-- Note! This data is quite large
# 2. Automatically trigger a check before calling the Writer Agent
⚖️ [Funnel] Current total memory length: 663 tokens (Max: 150)
✂️ [Funnel] Triggering compression! Discarding unimportant Tool Logs...
# 3. Compression successful, protecting downstream Agents
✅ [Funnel] Length after compression: 120 tokens
✍️ [Writer] Received Prompt (length 120), thinking...
```
## 📝 Key Takeaways
1. **Slot is a Universal Container**: Whether it's a user's request, JSON returned by tools, or replies from the LLM, everything is encapsulated into a `Slot`.
2. **Memory is Not a Trash Can**: It cannot just take in without outputting. A **Funnel** mechanism must be mounted on the read path.
3. **Decoupled Design**:
* The `Researcher` does not know about the existence of the `Writer`.
* They exchange information indirectly through `Memory`.
* The `Workflow` is responsible for coordinating their sequence.
## License
MIT
