内容
# gMAS
**构建多智能体系统，其角色和连接可以在运行时更改。**
[](https://github.com/frontier-ai-next/gMAS/actions/workflows/ci.yml)
[](https://frontier-ai-next.github.io/gMAS/)
[](https://github.com/frontier-ai-next/gMAS/releases)
[](https://www.python.org/)
[](LICENSE)
[文档](https://frontier-ai-next.github.io/gMAS/) ·
[快速开始](https://frontier-ai-next.github.io/gMAS/getting-started/quickstart/) ·
[API 参考](https://frontier-ai-next.github.io/gMAS/api/core/) ·
[基准测试](https://frontier-ai-next.github.io/gMAS/benchmarks/) ·
[发布版本](https://github.com/frontier-ai-next/gMAS/releases)
gMAS 是一个开源的 Python 框架，用于构建和运行基于图的
多智能体系统与大型语言模型。节点持有角色和任务；边传递工作和
上下文；运行器调度模型和工具调用。预算、内存、事件和
对剩余计划的更改在同一执行模型中可见。
> **项目状态：** gMAS 是针对开发者和研究人员的早期版本。
> 公共 API 在 Python 3.12 和 3.13 上经过测试。为生产
> 实验固定版本，并期望一些高级 API 会演变。
## 显式内容
智能体工作流快速积累依赖项、并行分支、工具
权限、预算和失败路径。gMAS 将它们保留在图中
和运行器配置中，而不是将它们分散在提示模板和
回调中：
- 团队存储在 `RoleGraph` 中；
- 调度器从图中派生执行顺序和并行组；
- 每个角色可以有自己的指令、模型、工具和本地状态；
- 运行器记录输出、令牌使用、延迟、错误和拓扑更改；
- 类型策略可以在同一运行期间停止、跳过、重定向或恢复工作；
- 图可以导出用于路由、剪枝和图分析。
## 核心能力
| 领域 | gMAS 提供的内容 |
| --- | --- |
| 图模型 | 智能体、任务节点、加权通信边、条件、执行边界、节点状态和图特征 |
| 执行 | 同步、异步、流式、顺序和图派生的并行执行 |
| 运行时控制 | 早期停止、跳过/强制、条件路由、边编辑、恢复链、计划重建和最终响应者更改 |
| 模型 | 简单的可调用接口、OpenAI 兼容的端点和每智能体调用者选择 |
| 工具 | 基于注册的工具、自定义函数工具、Shell、代码、文件搜索、网络搜索、MCP 和可选的计算机使用集成 |
| 上下文 | 每智能体状态、隐藏通道、工作和长期内存以及可选的共享内存 |
| 可靠性 | 超时、重试、回退、错误策略、令牌/时间预算和循环限制 |
| 可观察性 | 类型生命周期事件、回调、流式传输、指标、JSONL 跟踪和完整执行结果 |
| 图机器学习 | 邻接和边张量、嵌入、剪枝钩、GNN 路由和 PyTorch Geometric 导出 |
## 安装
gMAS 需要 Python 3.12 或 3.13。
```bash
pip install frontier-ai-gmas
```
使用 `uv`:
```bash
uv add frontier-ai-gmas
```
仅安装您需要的集成：
```bash
pip install "frontier-ai-gmas[web-search]"
pip install "frontier-ai-gmas[mcp]"
pip install "frontier-ai-gmas[embeddings,pyg]"
pip install "frontier-ai-gmas[viz]"
```
| 额外 | 目的 |
| --- | --- |
| `web-search` / `web-fast` | 搜索和快速 HTML 提取 |
| `selenium` | 浏览器支持的网络交互 |
| `mcp` | 模型上下文协议工具 |
| `embeddings` | 句子转换器嵌入 |
| `pyg` | PyTorch Geometric 图导出和 GNN 工作流 |
| `viz` | Graphviz 和 Matplotlib 可视化 |
| `computer-use-*` | 平台特定的屏幕和计算机使用支持 |
参见 [安装指南](docs/getting-started/installation.md) 以获取完整的
额外矩阵和开发设置。
## 快速开始
运行器接受任何 `Callable[[str], str]`。这使得图独立于特定的
模型供应商。
```python
import os
from openai import OpenAI
from gmas.builder import build_property_graph
from gmas.core import AgentProfile
from gmas.execution import MACPRunner
client = OpenAI(
api_key=os.environ["LLM_API_KEY"],
base_url=os.environ.get("LLM_BASE_URL"),
)
def call_llm(prompt: str) -> str:
response = client.responses.create(
model=os.environ["LLM_MODEL"],
input=prompt,
)
return response.output_text
agents = [
AgentProfile(
agent_id="researcher",
display_name="研究者",
description="收集相关事实和假设。",
),
AgentProfile(
agent_id="reviewer",
display_name="审查者",
description="检查证据并识别弱势主张。",
),
AgentProfile(
agent_id="writer",
display_name="撰写者",
description="生成最终的简洁答案。",
),
]
graph = build_property_graph(
agents,
workflow_edges=[
("researcher", "reviewer"),
("reviewer", "writer"),
],
query="如何使该系统安全部署？",
)
result = MACPRunner(llm_caller=call_llm).run_round(graph)
print(result.final_answer)
print(result.execution_order)
print(result.total_tokens, result.total_time)
```
`run_round` 返回 `MACPResult`，包括最终答案、执行顺序、
消息、时间和令牌总数。工具、并行分支、内存、每智能体
模型、回调、预算和路由条件可以添加到同一个图中。
## 执行模型
执行有五个阶段：
1. **作者设置** — 定义任务、角色、提示、工具和初始
连接。
2. **实时角色图** — 在 `RoleGraph` 中保持智能体、边、条件、状态、内存和
学习到的特征。
3. **规划和调度** — 推导出可执行的子图、依赖项
顺序、并行组和最终响应者。
4. **智能体执行** — 在重试、超时、循环和
预算策略下调用模型和工具。
5. **适应和结果** — 在允许时更新剩余计划，然后
返回答案及其跟踪和指标。
`RoleGraph` 在整个运行过程中保持可用；它不会在初始计划构建后被丢弃。
## 运行时适配
动态拓扑是可选的。拓扑钩观察已完成的步骤并
返回一个有界的 `TopologyAction`；运行器验证并将其应用于
剩余的计划。
```python
from gmas.execution import MACPRunner, RunnerConfig, StepContext, TopologyAction
def stop_after_approval(ctx: StepContext, graph) -> TopologyAction | None:
if ctx.agent_id == "reviewer" and "APPROVED" in (ctx.response or ""):
return TopologyAction(
early_stop=True,
early_stop_reason="审查者已批准当前答案。",
)
return None
config = RunnerConfig(
enable_dynamic_topology=True,
topology_hooks=[stop_after_approval],
)
runner = MACPRunner(llm_caller=call_llm, config=config)
result = runner.run_round(graph)
```
拓扑操作可以：
- 使用记录的理由停止执行；
- 跳过或强制选择智能体；
- 添加或删除通信边；
- 将恢复工作插入到剩余计划中；
- 更改最终响应者；
- 在图更改后触发计划重建。
参见 [动态拓扑](docs/user-guide/advanced/dynamic-topology.md) 以获取钩子、
早期停止条件、条件边和直接图突变。
## 执行模式
运行器公开阻塞、异步和事件流接口：
```python
from gmas.execution import StreamEventType
# 阻塞
result = runner.run_round(graph)
# 异步
result = await runner.arun_round(graph)
# 流式传输
for event in runner.stream(graph):
if event.event_type == StreamEventType.AGENT_OUTPUT:
print(event.agent_id, event.content)
# 异步流式传输
async for event in runner.astream(graph):
if event.event_type == StreamEventType.AGENT_OUTPUT:
print(event.agent_id, event.content)
```
流式传输涵盖运行和智能体生命周期事件、令牌事件、错误和
重试、并行组、内存访问、预算警告、拓扑更改、
剪枝、回退和最终结果。
阅读 [运行智能体](docs/user-guide/execution/running.md)、
[流式传输](docs/user-guide/execution/streaming.md) 和
[并行执行](docs/user-guide/execution/parallel.md) 以获取详细信息。
## 模型和工具
调用者工厂可以为每个智能体分配不同的同步或异步模型
调用者。调用者可以使用托管的 API、OpenAI 兼容的网关或
本地模型。
`ToolRegistry` 拥有运行中可用的工具。内置和可选工具
涵盖 Shell 执行、代码解释、文件搜索、网络搜索和获取、
浏览器操作、MCP 和计算机使用。Python 函数也可以注册
为类型化的工具并转换为 OpenAI 兼容的模式。
- [多模型支持](docs/user-guide/advanced/multi-model.md)
- [工具和自定义工具注册](docs/user-guide/tools.md)
- [API 参考：工具](docs/api/tools.md)
## 内存、预算和可靠性
`RunnerConfig` 持有执行策略，在智能体提示之外。它配置：
- 每运行超时、重试次数、延迟和指数退后；
- 总令牌和时间预算；
- 最大工具和循环迭代次数；
- 失败的继续、重试、回退或引发行为；
- 本地工作内存、长期内存和共享内存访问；
- 隐藏状态通道和嵌入传播；
- 并行性和路由策略。
预算停止和恢复路径出现在结果和事件流中。
参见 [内存](docs/user-guide/memory.md)、
[错误处理](docs/user-guide/advanced/error-handling.md) 和
[`MACPRunner` 指南](docs/user-guide/core/macp-runner.md)。
## 可观察性
`MACPResult` 包括最终答案、最终智能体、执行顺序、每智能体
消息、步骤结果、令牌和时间总数、错误、回退、
剪枝智能体、预算信息、隐藏状态、早期停止详细信息和
拓扑修改次数。
生命周期回调在运行期间提供相同的信息。内置处理程序支持
终端输出、指标收集和文件跟踪；自定义同步和异步处理程序
可以集成应用程序日志、遥测或 UI 更新。
参见 [回调](docs/user-guide/callbacks.md) 和
[可复制性](docs/benchmarks/reproducibility.md)。
## 图学习和研究工作流
`RoleGraph` 可以将实时多智能体系统暴露为数值图数据：
- 邻接和加权边张量；
- 节点和边属性；
- 角色嵌入和隐藏状态；
- PyTorch Geometric `Data` 导出；
- 用于学习路由和剪枝的调度器钩。
这些接口支持学习路由或剪枝图的实验。它们是可选的；
普通的图执行不需要 PyTorch Geometric。
从 [GNN 路由](docs/user-guide/advanced/gnn-routing.md) 和
[GNN 示例](docs/examples/gnn-routing.md) 开始。
## 基准测试和可复制性
基准测试代码与产品示例分开。每个评估轨道
都有自己的目录、入口点、输入说明和输出合约在
[`benchmarks/`](benchmarks/README.md) 下。
| 轨道 | 评估内容 |
| --- | --- |
| 匹配拓扑 | gMAS 和 LangGraph 在匹配角色、提示、模型和图形状下的表现 |
| 运行时控制 | 早期停止、禁用节点、可达性、适配、隐藏通道和多模型执行 |
| GAIA | 工具启用的问答在固定工具预算下的表现 |
| AgentPrune | 在 MultiAgentBench 研究创意轨道上的学习图剪枝 |
| Terminal-Bench | 单智能体和条件团队终端任务套件 |
报告的结果、统计测试、局限性和复制说明
一起在 [基准文档](docs/benchmarks/index.md) 中。比较
数字故意不放在首页，以免结果被其范围和注意事项所限制。
## 作用范围
gMAS 适用于需要：
- 建模具有明确依赖和并行分支的团队；
- 检查或可视化工作如何在角色之间移动；
- 根据中间结果更改剩余工作流；
- 集中强制工具、令牌、时间或迭代预算；
- 在智能体之间混合模型或工具权限；
- 收集可复制的跟踪和每智能体指标；
- 训练或评估路由和图剪枝策略。
直接函数链对于固定的一模型管道通常更简单。对于
可持久检查点和人工介入恢复，请查看 [gMAS 和 LangGraph](docs/comparisons/langgraph.md) 中的权衡。
## 生态系统
| 项目 | 角色 |
| --- | --- |
| **gMAS** | 此仓库：Python 图引擎、智能体、运行器、工具、内存和评估套件 |
| [flowMAS](https://github.com/frontier-ai-next/flowMAS) | 视觉工作流工作室、演示 API 和自托管的可观察性，基于 gMAS SDK |
gMAS 是一个独立的框架。flowMAS 是一个单独的下游应用程序，
它使用 gMAS SDK 而不会更改核心库。
## 文档
完整的文档发布在
[frontier-ai-next.github.io/gMAS](https://frontier-ai-next.github.io/gMAS/)。
| 目标 | 从这里开始 |
| --- | --- |
| 安装 gMAS 及其额外功能 | [安装](docs/getting-started/installation.md) |
| 构建第一个智能体图 | [快速开始](docs/getting-started/quickstart.md) |
| 了解数据模型 | [关键概念](docs/user-guide/key-concepts.md) |
| 配置运行器 | [MACPRunner](docs/user-guide/core/macp-runner.md) |
| 添加工具和回调 | [工具](docs/user-guide/tools.md) · [回调](docs/user-guide/callbacks.md) |
| 在执行过程中更改图 | [动态拓扑](docs/user-guide/advanced/dynamic-topology.md) |
| 将进度流式传输到应用程序 | [流式传输](docs/user-guide/execution/streaming.md) |
| 复制报告的结果 | [基准测试](docs/benchmarks/index.md) |
| 审查框架的权衡 | [gMAS 和 LangGraph](docs/comparisons/langgraph.md) |
| 浏览 Python API | [API 参考](docs/api/core.md) |
## 仓库布局
```text
gmas/
├── .github/ # CI、Pages、发布和贡献模板
├── src/gmas/ # 库代码
├── tests/ # 单元和集成测试
├── examples/ # 关注的 runnable 示例
├── benchmarks/ # 评估入口点和数据合约
├── docs/ # 指南、API 参考和报告的结果
└── pyproject.toml # 包元数据和可选依赖
```
`examples/` 包含小的 API 演示。`benchmarks/` 包含评估
入口点及其运行合约；基准配置不是公共库 API 的一部分。
## 开发
安装开发环境：
```bash
git clone https://github.com/frontier-ai-next/gmas.git
cd gmas
uv sync --all-extras --group test --group lint --group typecheck --group docs
```
运行发布检查：
```bash
uv run tox -e lint,quick
uv run --group docs mkdocs build --strict
```
测试矩阵涵盖 Python 3.12 和 3.13。类型检查目前是一个
咨询检查，同时减少已知类型债务。
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取分支、样式、测试和
拉取请求指导。发布维护人员还应查看
[发布检查清单](docs/contributing/releasing.md)。
## 贡献
对于 bug、缺失的文档、新适配器或 API 提案，请打开问题。
在实施影响图语义或公共接口之前，请讨论较大的更改。
贡献代码时：
1. 保持更改的焦点并为可观察的行为添加测试；
2. 在图、运行器、工具和结果周围保留类型边界；
3. 在公共 API 更改时更新相关指南；
4. 不要提交凭证、基准输出或提供者特定的秘密；
5. 使用 Conventional Commits 以便发布工具可以计算版本更改。
## 许可证
gMAS 在 [MIT License](LICENSE) 下发布。
连接信息
猜你喜欢
暂无推荐服务器