<div align="center">

# 🌀 Nexus

**Python 多智能体编排框架**

*3 种编排模式 · 100+ LLM 提供商 · 内置工具调用与 MCP*

[![PyPI](https://img.shields.io/pypi/v/nexus-agents.svg)](https://pypi.org/project/nexus-agents/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![CI](https://github.com/songtianye/nexus/actions/workflows/ci.yml/badge.svg)](https://github.com/songtianye/nexus/actions)

[English](./README.md) | [中文](./README_CN.md) | [示例](./examples/)

</div>

---

## 为什么选 Nexus？

大多数 Agent 框架都在让你二选一：**简单好用**（Swarm）还是**功能强大**（LangGraph）。Nexus 两手都要 —— 5 行代码启动，按需扩展到复杂 DAG 工作流、LLM 智能路由、自组织 Agent 团队。

```python
import asyncio
from nexus import Team

async def main():
    async with Team(model="gpt-4o", api_key="sk-...") as team:
        team.add_agent("coder", instructions="你负责编写 Python 代码。")
        team.add_agent("writer", instructions="你负责撰写文章。")
        result = await team.run("用 Python 实现二分查找")
        print(result)  # → 自动路由到 'coder'

asyncio.run(main())
```

### ✨ 核心亮点

| | 特性 | 说明 |
|-|------|------|
| 🔀 | **3 种编排模式** | 静态 **Graph**（DAG）· 动态 **Router**（LLM 分诊）· **Adaptive**（Embedding 匹配） |
| 🌍 | **100+ LLM 提供商** | OpenAI、Anthropic、Groq、Deepseek、通义千问、Ollama、Azure、Bedrock、Vertex AI… 通过 [LiteLLM](https://docs.litellm.ai/) |
| 🔧 | **工具调用** | ReAct 循环（思考 → 行动 → 观察 → 重复），自动从 Python 类型提示提取 JSON Schema |
| 🔌 | **协议原生** | [MCP](https://modelcontextprotocol.io/) 工具协议 · [A2A](https://google.github.io/A2A/) Agent 发现协议 |
| 💬 | **多轮对话 & 流式输出** | `chat()` 对话记忆 · `stream()` 实时流式输出 |
| 🛡️ | **生产级** | Token 预算 · 检查点恢复 · 重试/降级策略 · 分布式追踪 · 指标监控 |

---

## 安装

```bash
# 推荐 — 解锁 100+ LLM 提供商
pip install nexus-agents[litellm]

# 或选择特定提供商
pip install nexus-agents[openai]       # 仅 OpenAI
pip install nexus-agents[anthropic]    # 仅 Anthropic

# 全部安装（所有提供商 + MCP + 可观测性）
pip install nexus-agents[all]
```

---

## 快速开始

### 多 Agent 自动路由

```python
import asyncio
from nexus import Team

async def main():
    async with Team(model="gpt-4o", api_key="sk-...") as team:
        team.add_agent("coder", instructions="你负责编写代码。")
        team.add_agent("writer", instructions="你负责撰写文章。")
        team.add_agent("analyst", instructions="你负责数据分析。")

        # 路由器自动为每个任务选择最佳 Agent
        await team.run("用 Python 实现快速排序")     # → coder
        await team.run("写一篇关于 AI Agent 的博客")  # → writer

asyncio.run(main())
```

### 工具调用（ReAct 循环）

把普通 Python 函数定义为工具 —— Nexus 自动提取 JSON Schema：

```python
def calculate(expression: str) -> str:
    """计算数学表达式。示例：'2**32 - 1'"""
    return str(eval(expression))

def get_current_time() -> str:
    """获取当前 UTC 时间。"""
    from datetime import datetime, timezone
    return datetime.now(timezone.utc).isoformat()

async with Team(model="gpt-4o", api_key="sk-...") as team:
    team.add_agent(
        "assistant",
        instructions="使用工具精确回答问题。",
        tools=[calculate, get_current_time],
    )
    result = await team.run("2^32 - 1 等于多少？")
    # 🔧 Agent 调用 calculate("2**32 - 1") → "4294967295"
    # ✨ Agent 回复："2³² - 1 = 4,294,967,295"
```

### 多轮对话

```python
async with Team(model="gpt-4o", api_key="sk-...") as team:
    team.add_agent("assistant", instructions="你是一个有帮助的助手。")

    r1 = await team.chat("什么是斐波那契数列？")
    r2 = await team.chat("给我前 10 个数")  # 自动保持上下文
    team.reset_conversation()  # 清空历史
```

### 流式输出

```python
async with Team(model="gpt-4o", api_key="sk-...") as team:
    team.add_agent("storyteller", instructions="你擅长讲引人入胜的故事。")

    async for chunk in team.stream("讲一个关于时间旅行机器人的故事"):
        print(chunk, end="", flush=True)
```

> **📂 更多示例 →** 查看 [`examples/`](./examples/) 目录获取可运行的完整 demo：
> 工具调用、MCP 集成、Graph/Router/Adaptive 三种编排模式，以及更多。
>
> ```bash
> # 克隆并运行
> git clone https://github.com/songtianye/nexus.git && cd nexus
> pip install -e '.[all]'
> cp examples/.env.example examples/.env  # 填入你的 API Key
> python examples/demo_tools.py simple    # 试试工具调用
> python examples/demo_modes.py graph     # 试试图编排
> ```

---

## 三种编排模式

### 🔷 Graph — 静态 DAG 工作流

适用于步骤确定的流水线：

```python
from nexus.orchestration.graph import GraphOrchestrator, START, END

graph = GraphOrchestrator()
graph.add_node("research", research_fn)
graph.add_node("write", write_fn)
graph.add_node("review", review_fn)

graph.add_edge(START, "research")
graph.add_edge("research", "write")
graph.add_edge("write", "review")
graph.add_conditional_edge(
    "review",
    lambda state: "write" if state.get("needs_revision") else END
)

result = await graph.execute({"topic": "AI Agents"})
```

### 🔶 Router — 动态 LLM 路由

分诊 Agent 分析每个请求，自动选择最佳专家：

```python
from nexus.orchestration.topology import TopologyMode

async with Team(model="gpt-4o", mode=TopologyMode.ROUTER) as team:
    team.add_agent("coder", instructions="你负责写代码。")
    team.add_agent("writer", instructions="你负责写文章。")
    await team.run("用 Python 实现快排")  # → 路由到 coder
```

### 🔴 Adaptive — Embedding 能力匹配

基于能力向量的余弦相似度自动匹配最优 Agent —— Nexus 独创：

```python
from nexus import AgentCapability
from nexus.orchestration.topology import TopologyMode

async with Team(
    model="gpt-4o",
    mode=TopologyMode.ADAPTIVE,
    embedding_model="text-embedding-3-small",
) as team:
    team.add_agent("coder", capabilities=AgentCapability(coding=1.0, reasoning=0.8))
    team.add_agent("writer", capabilities=AgentCapability(creativity=1.0, language=0.9))
    await team.run("写一首关于递归的诗")  # → 能力匹配 → writer
```

---

## 100+ LLM 提供商

换一个字符串就能切换模型，零代码改动：

```python
Team(model="gpt-4o")                                    # OpenAI
Team(model="anthropic/claude-sonnet-4-20250514")      # Anthropic
Team(model="groq/llama-3.1-70b-versatile")              # Groq（极速推理）
Team(model="deepseek/deepseek-chat")                     # Deepseek
Team(model="vertex_ai/gemini-1.5-pro")                   # Google Vertex AI
Team(model="bedrock/anthropic.claude-3-sonnet")          # AWS Bedrock
Team(model="ollama/llama3.1")                            # 本地运行（Ollama）

# 任何 OpenAI 兼容端点
Team(model="openai/my-model", api_base="https://my-api.com/v1", api_key="sk-...")

# 不同 Agent 用不同模型
async with Team(model="gpt-4o") as team:
    team.add_agent("fast", model="groq/llama-3.1-70b-versatile")   # 速度优先
    team.add_agent("smart", model="anthropic/claude-sonnet-4-20250514") # 质量优先
```

完整列表 → [LiteLLM Providers](https://docs.litellm.ai/docs/providers)

---

## MCP 协议集成

连接任意 [MCP](https://modelcontextprotocol.io/) 工具服务器：

```python
from nexus.protocol.mcp import MCPToolProvider

# 本地 MCP 服务器（stdio）
async with MCPToolProvider("npx", ["-y", "@modelcontextprotocol/server-filesystem", "."]) as mcp:
    tools = await mcp.get_tools()
    team.add_agent("file_agent", tools=tools)

# 远程 MCP 服务器（HTTP/SSE）
async with MCPToolProvider(url="https://mcp-server.example.com/sse") as mcp:
    tools = await mcp.get_tools()
    team.add_agent("web_agent", tools=tools)
```

---

## 架构

```
┌─────────────────────────────────────────────────────┐
│  开发者 API                                          │
│  Team · CLI · @tool 装饰器 · YAML 配置              │
├─────────────────────────────────────────────────────┤
│  可观测性                                            │
│  分布式追踪 · 指标监控 · Token 计量                  │
├─────────────────────────────────────────────────────┤
│  编排引擎                                            │
│  🔷 Graph  ·  🔶 Router  ·  🔴 Adaptive             │
├─────────────────────────────────────────────────────┤
│  运行时                                              │
│  执行引擎 · 检查点恢复 · 重试 / 降级                │
│  Token 预算 · 自动降档策略                           │
├─────────────────────────────────────────────────────┤
│  协议 + 核心                                         │
│  Agent · Task · Handoff · Message                    │
│  A2A 协议 · MCP 协议 · Discovery 发现服务           │
├─────────────────────────────────────────────────────┤
│  模型提供商                                          │
│  OpenAI · Anthropic · Ollama · LiteLLM (100+)       │
└─────────────────────────────────────────────────────┘
```

## 项目结构

```
nexus/
├── api.py                  # Team — 高级 API
├── cli.py                  # CLI: init / run / chat / inspect
├── core/                   # Agent, Task, Handoff, Message, State
├── models/                 # OpenAI, Anthropic, Ollama, LiteLLM
├── orchestration/          # Graph, Router, Adaptive, TopologyEngine
├── protocol/               # A2A, MCP, MessageBus, Discovery
├── runtime/                # Engine, Checkpoint, Budget, Policies
└── observability/          # Tracing, Metrics
```

---

## 横向对比

| 特性 | Nexus | LangGraph | CrewAI | Swarm |
|------|:-----:|:---------:|:------:|:-----:|
| 图工作流 | ✅ | ✅ | — | — |
| 动态 LLM 路由 | ✅ | — | ⚠️ | ✅ |
| 自适应匹配 | ✅ | — | — | — |
| 100+ 提供商 (LiteLLM) | ✅ | — | — | — |
| MCP 协议 | ✅ | — | — | — |
| A2A 协议 | ✅ | — | — | — |
| 工具调用 | ✅ | ✅ | ✅ | ✅ |
| 流式输出 | ✅ | ✅ | — | — |
| Token 预算 | ✅ | — | — | — |
| 检查点恢复 | ✅ | ✅ | — | — |
| 极简 API（5 行） | ✅ | — | ✅ | ✅ |

> **注：** "—" 表示未内置。部分功能可通过插件或自定义代码实现。

---

## 路线图

- [x] 核心原语 (Agent + Task + Handoff)
- [x] 3 种编排模式 (Graph / Router / Adaptive)
- [x] LiteLLM 集成 (100+ 提供商)
- [x] 工具调用 + ReAct 循环
- [x] MCP 协议集成
- [x] A2A 协议支持
- [x] 流式响应
- [x] 多轮对话
- [x] Token 预算管理
- [x] 检查点 / 恢复
- [x] 可观测性 (追踪 + 指标)
- [x] CLI (init / run / chat / inspect)
- [ ] Agent 记忆 (长期 RAG)
- [ ] OpenTelemetry 导出
- [ ] Web UI 仪表盘
- [ ] 多模态 (视觉、音频)
- [ ] 分布式执行

---

## 参与贡献

欢迎贡献！参见 [CONTRIBUTING.md](./CONTRIBUTING.md) 了解详情。

```bash
git clone https://github.com/songtianye/nexus.git
cd nexus
uv venv --python 3.12 .venv && uv pip install --python .venv/bin/python -e ".[all,dev]"
.venv/bin/python tests/test_smoke.py  # 验证一切正常
```

## 开源协议

[MIT](./LICENSE) © 2025–2026 Nexus Contributors

---

<div align="center">

**⭐ 如果 Nexus 对你有帮助，请点个 Star — 帮助更多人发现这个项目！**

[示例](./examples/) · [Issues](https://github.com/songtianye/nexus/issues) · [Discussions](https://github.com/songtianye/nexus/discussions)

</div>
