agent-platform｜轻量多智能体注册与互调路由平台

access：来源确认 · git clone https://github.com/Ace-li521/agent-platform.git cd agent-platform pip install -r requirements.txt python main.py

project_type：来源确认 · A lightweight multi-agent collaboration platform

<p align="center">
  <h1 align="center">🤖 Agent Platform</h1>
  <p align="center">
    <strong>A lightweight multi-agent collaboration platform — the "Address Book + Post Office" for your AI agents.</strong>
  </p>
  <p align="center">
    <a href="#quick-start">Quick Start</a> •
    <a href="#features">Features</a> •
    <a href="#api-reference">API</a> •
    <a href="#integration-guide">Integration</a> •
    <a href="#architecture">Architecture</a>
  </p>
  <p align="center">
    <img src="https://img.shields.io/badge/python-3.11+-blue?logo=python&logoColor=white" alt="Python 3.11+"/>
    <img src="https://img.shields.io/badge/FastAPI-0.110+-009688?logo=fastapi&logoColor=white" alt="FastAPI"/>
    <img src="https://img.shields.io/badge/protocol-HTTP+JSON-orange" alt="HTTP+JSON"/>
    <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License"/>
    <img src="https://img.shields.io/docker/image-size/agent-platform/latest?label=docker" alt="Docker"/>
  </p>
</p>

---

## 💡 Why Agent Platform?

In enterprise environments, different teams build their own AI agents (Ops, R&D, Finance, HR…). But these agents live in silos — they can't talk to each other.

**Agent Platform** solves this with a dead-simple approach:

```
┌─────────────┐         ┌──────────────────┐         ┌─────────────┐
│  Ops Agent  │────────▶│  Agent Platform  │◀────────│  R&D Agent  │
└─────────────┘         │                  │         └─────────────┘
                        │  • Registry      │
┌─────────────┐         │  • Routing       │         ┌─────────────┐
│  HR Agent   │────────▶│  • Tracing       │◀────────│  Biz Agent  │
└─────────────┘         └──────────────────┘         └─────────────┘
```

**One API call** and any agent can ask any other agent. No SDK, no message queue, no vendor lock-in.

---

## ✨ Features

| Feature | Description |
|---------|-------------|
| 🔌 **Language Agnostic** | Pure HTTP + JSON — Python, Go, Java, Rust, anything works |
| 📋 **Service Discovery** | `GET /agents` returns all registered agents for LLM-based routing |
| 🔀 **Smart Routing** | Route requests by agent name with full message history |
| 🔍 **Distributed Tracing** | Auto-generated `trace_id` for cross-agent call tracking |
| 📝 **Dynamic Registration** | Agents register/deregister at runtime, zero downtime |
| 🐳 **Docker Ready** | One-line deployment with Docker |
| ⚡ **Async & Fast** | Built on FastAPI + httpx async, handles concurrent requests efficiently |
| 🧩 **Stateless Design** | Platform stores nothing — callers own their context |

---

## 🚀 Quick Start

### Option 1: Run directly

```bash
git clone https://github.com/Ace-li521/agent-platform.git
cd agent-platform
pip install -r requirements.txt
python main.py
```

Server runs at `http://localhost:9000` 🎉

### Option 2: Docker

```bash
docker build -t agent-platform .
docker run -d -p 9000:9000 agent-platform
```

### Verify it works

```bash
curl http://localhost:9000/agents
```

---

## 📖 API Reference

### `GET /agents` — List all agents

Returns agent metadata for LLM-based routing decisions.

```json
[
  {
    "name": "ops-agent",
    "description": "Operations: monitoring, logs, service restarts, on-call schedules",
    "examples": ["Server is returning 500", "Who's on-call today?"]
  }
]
```

### `POST /ask` — Route a request to an agent

```bash
curl -X POST http://localhost:9000/ask \
  -H "Content-Type: application/json" \
  -d '{
    "target": "ops-agent",
    "messages": [{"role": "user", "content": "What is the CPU usage of order-service?"}],
    "from_agent": "gateway-bot",
    "real_user": "zhangsan",
    "trace_id": "optional-trace-id"
  }'
```

### `POST /register` — Register an agent

```bash
curl -X POST http://localhost:9000/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "finance-agent",
    "description": "Finance: invoices, budgets, expense reports",
    "endpoint": "http://10.0.1.30:8080/chat",
    "owner": "finance-team",
    "examples": ["What is this month spend?", "Approve my expense report"]
  }'
```

### `DELETE /agents/{name}` — Deregister an agent

```bash
curl -X DELETE http://localhost:9000/agents/finance-agent
```

---

## 🔗 Integration Guide

### As a Provider (let others call your agent)

Expose a single `POST /chat` endpoint:

```python
# Any framework, any language — just handle this contract
@app.post("/chat")
async def chat(request):
    messages = request["messages"]      # Full conversation history
    from_agent = request["from"]        # Who's calling
    real_user = request["real_user"]    # The actual human user
    trace_id = request["trace_id"]     # For distributed tracing

    answer = your_llm_logic(messages)

    return {"message": {"role": "assistant", "content": answer}}
```

Then register yourself:
```bash
curl -X POST http://platform:9000/register \
  -d '{"name":"my-agent","description":"I do X","endpoint":"http://my-host:8080/chat"}'
```

**Done.** Other agents can now reach you.

### As a Consumer (call other agents)

Give your LLM two tools:

```python
# Tool 1: Discover available agents
def list_agents():
    return httpx.get("http://platform:9000/agents").json()

# Tool 2: Ask a peer agent
def ask_peer_agent(target: str, question: str):
    return httpx.post("http://platform:9000/ask", json={
        "target": target,
        "messages": [{"role": "user", "content": question}],
        "from_agent": "my-agent",
        "real_user": current_user
    }).json()
```

Your LLM reads the agent list, picks the right one, and calls it. **That's the entire integration.**

---

## 🏗 Architecture

```
                    ┌─────────────────────────────────┐
                    │        Agent Platform            │
                    │                                  │
  Register ──────▶ │  ┌───────────┐  ┌────────────┐  │
                    │  │ Registry  │  │  Router    │  │
  GET /agents ───▶ │  │ (JSON)    │  │  (httpx)   │  │
                    │  └───────────┘  └────────────┘  │
  POST /ask ─────▶ │         │              │         │
                    │         ▼              ▼         │
                    │  ┌──────────────────────────┐   │
                    │  │   Lookup + Forward        │   │
                    │  └──────────────────────────┘   │
                    └──────────────┬──────────────────┘
                                   │
                    ┌──────────────┼──────────────┐
                    ▼              ▼              ▼
              ┌──────────┐  ┌──────────┐  ┌──────────┐
              │ Agent A  │  │ Agent B  │  │ Agent C  │
              │ (Python) │  │  (Go)    │  │ (Java)   │
              └──────────┘  └──────────┘  └──────────┘
```

### Design Principles

- **Platform is stateless** — only routes, never stores conversations
- **Agents are stateless** — callers manage their own context window
- **Protocol is universal** — HTTP + JSON, works everywhere
- **No vendor lock-in** — swap LLM providers, frameworks, languages freely

---

## 🗺 Roadmap

- [ ] Health check & heartbeat (auto-remove dead agents)
- [ ] Authentication & rate limiting
- [ ] Agent capability matching (semantic routing)
- [ ] Web UI dashboard for monitoring
- [ ] Pub/Sub mode for async tasks
- [ ] Agent-to-agent streaming support

---

## 🤝 Contributing

Contributions are welcome! Feel free to:

1. Fork the repo
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## 📄 License

MIT License — use it however you want.

---

<p align="center">
  <strong>If this helps you build multi-agent systems, give it a ⭐️!</strong>
</p>

Python 3.11+ 与 FastAPI 0.110+（README 徽章标注）；需通过 requirements.txt 安装依赖；运行端口默认 9000。是否需要额外 API Key 由接入的智能体与大模型自行决定，平台本身未说明。费用、境外依赖与网络可用性待核验。