Content
# 🏢 Enterprise Agent Platform (EAP)
> **The Ultimate Protocol-Driven Architecture for Production-Ready Agents.**
>
> An enterprise-level multi-agent development scaffold that integrates **Service Governance**, **Full-Link Monitoring**, and **Smart Memory**.
   
## 📖 Project Introduction
**Enterprise Agent Platform (EAP)** is a standardized architecture solution for Agent systems. It abandons simple script-based calls and adopts **Domain-Driven Design (DDD)** principles, aiming to address three core pain points in enterprise applications:
1. **Unobservable**: When requests are sent out, it is unclear which Agent they are stuck on and how long they take.
2. **Uncontrollable**: A failure in a downstream Agent can cause the entire link to collapse.
3. **Memory Bloat**: Long conversations lead to token overflow and uncontrolled costs.
This architecture achieves millisecond-level tracking and governance of Agent behavior by introducing **TraceContext** and **Sidecar Monitor**.
## 🏗️ System Architecture
```mermaid
graph TD
User[User] --> API[Gateway Entry]
API --> Pipeline[Task Orchestration]
subgraph "Infrastructure"
Registry[Registry Center]
Breaker[Circuit Breaker]
Monitor[Monitoring System]
end
subgraph "Runtime"
Trace[TraceContext]
Memory[Smart Memory]
end
subgraph "Business Agents"
AgentA[Researcher]
AgentB[Writer]
end
Pipeline --> |1. Generate TraceID| Trace
Pipeline --> |2. Get Handler| Registry
Registry --> |3. Check Circuit| Breaker
AgentA -.-> |Report Span/Metrics| Monitor
AgentB -.-> |Report Span/Metrics| Monitor
AgentA --> |Access Context| Memory
```
## 📂 Directory Structure (Fusion Edition)
This project adopts a **"Flat yet Complete"** design, balancing development efficiency and architectural depth:
```text
enterprise-agent-platform/
├── src/
│ ├── protocol.py # [Core Protocol] Defines Slot, TaskPackage, TraceContext (including link tracking ID)
│ ├── monitor.py # [Full-Link Monitoring] Metrics collection, Span recording, Duration statistics
│ ├── governance.py # [Service Governance] ServiceRegistry (Registry Center), CircuitBreaker
│ ├── memory.py # [Memory Engine] Smart Eviction (priority-based memory eviction algorithm)
│ ├── agents.py # [Business Units] BaseAgent (automatic instrumentation base class) and specific business implementations
│ └── workflow.py # [Task Orchestration] Pipeline logic
├── main.py # [Entry Point] Simulates the calling link in a production environment
├── requirements.txt # Dependency list
└── README.md # This document
```
## 🌟 Core Features
### 1. 🔍 Full-Link Observability
Integrates `monitor.py` with `TraceContext`.
* **Trace ID**: A unique `trace_id` is generated for each user request, spanning all Agents.
* **Span Recording**: Automatically records each Agent's `start_time`, `duration`, and `status`.
* **Metrics**: Real-time statistics on success rates and throughput (QPS).
### 2. 🛡️ Automatic Circuit Breaking and Degradation
* **Circuit Breaker**: When a certain Agent (e.g., `ResearchAgent`) fails consecutively beyond a threshold (default 3 times), the system automatically cuts off its traffic to prevent cascading failures.
* **Failover**: Supports configuration of degradation strategies (Fallback) to ensure the main process is uninterrupted.
### 3. 🧠 Smart High-Fidelity Memory
* **Priority-based GC**: When memory is full, it prioritizes retaining `SYSTEM` instructions and key `RAG` information, automatically discarding `USER` casual chats.
* **Zero-Copy**: Slot objects are passed between Agents, reducing serialization overhead.
### 4. 🧩 Minimal Business Development
Business developers only need to inherit `BaseAgent` and implement `_run_logic`, **without worrying about monitoring and circuit-breaking code**, which the system will automatically inject:
```python
class MyAgent(BaseAgent):
def _run_logic(self, task):
# Pure business logic, monitoring code is executed automatically in the parent class
return [Slot(...)]
```
## 🚀 Quick Start
### 1. Installation
```bash
# No complex database dependencies, ready to use out of the box
pip install -r requirements.txt
```
### 2. Run Demo
```bash
python main.py
```
### 3. Observe Console Output
You will see structured logs displaying the complete calling link:
```text
=== System Started ===
🔗 TraceID: 8a3f-2b1c-4d5e... <-- Globally unique tracking ID
🤖 [Researcher] Working on: Tell me about AI trends.
®️ [Registry] Status: OK
✅ [Researcher] Success (0.203s)
🧹 [Memory] Cleaned up context. Current size: 5
🤖 [Writer] Working on: Write summary
✅ [Writer] Success (0.101s)
📊 [Monitor Report] <-- Automatically generated monitoring dashboard
{
"metrics": {"success": 2, "fail": 0},
"recent_spans": [
{"agent": "Researcher", "duration": 0.203, "trace_id": "..."},
{"agent": "Writer", "duration": 0.101, "trace_id": "..."}
]
}
```
## 🔧 Advanced Configuration
Modify `src/monitor.py` to integrate with external monitoring systems:
* **Prometheus**: Add `prometheus_client` instrumentation in the `record()` method.
* **Jaeger/Zipkin**: Send `spans` data via the OpenTelemetry SDK.
## 📄 License
MIT License
