gMAS

Build multi-agent systems whose roles and connections can change while they run.

Documentation · Quick start · API reference · Benchmarks · Releases

gMAS is an open-source Python framework for building and running graph-based multi-agent systems with LLMs. Nodes hold roles and tasks; edges carry work and context; the runner schedules model and tool calls. Budgets, memory, events, and changes to the remaining plan stay visible in the same execution model.

Project status: gMAS is an early release for developers and researchers. The public API is tested on Python 3.12 and 3.13. Pin a version for production experiments and expect some advanced APIs to evolve.

What stays explicit

Agent workflows quickly accumulate dependencies, parallel branches, tool permissions, budgets, and failure paths. gMAS keeps them in the graph and runner configuration instead of spreading them across prompt templates and callbacks:

• the team is stored in RoleGraph;
• the scheduler derives execution order and parallel groups from the graph;
• each role can have its own instructions, model, tools, and local state;
• the runner records outputs, token use, latency, errors, and topology changes;
• typed policies can stop, skip, reroute, or recover work during the same run;
• the graph can be exported for routing, pruning, and graph analysis.

Core capabilities

Install

gMAS requires Python 3.12 or 3.13.

python -m pip install frontier-ai-gmas

With uv:

uv add frontier-ai-gmas

The distribution is named frontier-ai-gmas on PyPI, while the Python import package is named gmas. Verify the installed version with:

python -c "import gmas; print(gmas.__version__)"

Install only the integrations you need:

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]"

See the installation guide for the full extras matrix and development setup.

Quick start

The runner accepts any Callable[[str], str]. This keeps the graph independent of a particular model vendor.

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="Researcher",
        description="Collect the relevant facts and assumptions.",
    ),
    AgentProfile(
        agent_id="reviewer",
        display_name="Reviewer",
        description="Check the evidence and identify weak claims.",
    ),
    AgentProfile(
        agent_id="writer",
        display_name="Writer",
        description="Produce the final concise answer.",
    ),
]

graph = build_property_graph(
    agents,
    workflow_edges=[
        ("researcher", "reviewer"),
        ("reviewer", "writer"),
    ],
    query="What would make this system safe to deploy?",
)

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 returns MACPResult, including the final answer, execution order, messages, timing, and token totals. Tools, parallel branches, memory, per-agent models, callbacks, budgets, and routing conditions can be added to the same graph.

The execution model

Execution has five stages:

1. Authored setup — define the task, roles, prompts, tools, and initial connections.
2. Live role graph — keep agents, edges, conditions, state, memory, and learned features in RoleGraph.
3. Planning and scheduling — derive the executable subgraph, dependency order, parallel groups, and final responder.
4. Agent execution — call models and tools under retry, timeout, loop, and budget policies.
5. Adaptation and results — update the remaining plan when allowed, then return the answer together with its trace and metrics.

RoleGraph remains available throughout the run; it is not discarded after the initial plan is built.

Runtime adaptation

Dynamic topology is opt-in. A topology hook observes a completed step and returns a bounded TopologyAction; the runner validates and applies it to the remaining plan.

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="The reviewer approved the current answer.",
        )
    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)

Topology actions can:

• stop execution with a recorded reason;
• skip or force selected agents;
• add or remove communication edges;
• insert recovery work into the remaining plan;
• change the final responder;
• trigger a plan rebuild after graph changes.

See Dynamic topology for hooks, early-stop conditions, conditional edges, and direct graph mutation.

Execution modes

The runner exposes blocking, async, and event-streaming interfaces:

from gmas.execution import StreamEventType

# Blocking
result = runner.run_round(graph)

# Async
result = await runner.arun_round(graph)

# Streaming
for event in runner.stream(graph):
    if event.event_type == StreamEventType.AGENT_OUTPUT:
        print(event.agent_id, event.content)

# Async streaming
async for event in runner.astream(graph):
    if event.event_type == StreamEventType.AGENT_OUTPUT:
        print(event.agent_id, event.content)

Streaming covers run and agent lifecycle events, token events, errors and retries, parallel groups, memory access, budget warnings, topology changes, pruning, fallbacks, and the final result.

Read Running agents, Streaming, and Parallel execution for details.

Models and tools

A caller factory can assign a different synchronous or asynchronous model caller to each agent. Callers may use hosted APIs, OpenAI-compatible gateways, or local models.

ToolRegistry owns the tools available to a run. Built-in and optional tools cover shell execution, code interpretation, file search, web search and fetch, browser actions, MCP, and computer use. Python functions can also be registered as typed tools and converted to OpenAI-compatible schemas.

• Multi-model support
• Tools and custom tool registration
• API reference: tools

Memory, budgets, and reliability

RunnerConfig holds execution policy outside agent prompts. It configures:

• per-run timeouts, retry count, delay, and exponential backoff;
• total token and time budgets;
• maximum tool and loop iterations;
• continue, retry, fallback, or raise behavior for failures;
• local working memory, long-term memory, and shared-memory access;
• hidden-state channels and embedding propagation;
• parallelism and routing policy.

Budget stops and recovery paths appear in the result and event stream.

See Memory, Error handling, and the MACPRunner guide.

Observability

MACPResult includes the final answer, final agent, execution order, per-agent messages, step results, token and timing totals, errors, fallbacks, pruned agents, budget information, hidden states, early-stop details, and the number of topology modifications.

Lifecycle callbacks make the same information available while the run is in progress. Built-in handlers support terminal output, metrics collection, and file traces; custom sync and async handlers can integrate application logging, telemetry, or UI updates.

See Callbacks and Reproducibility.

Graph learning and research workflows

RoleGraph can expose the live multi-agent system as numerical graph data:

• adjacency and weighted-edge tensors;
• node and edge attributes;
• role embeddings and hidden states;
• PyTorch Geometric Data export;
• scheduler hooks for learned routing and pruning.

These interfaces support experiments that learn routing or prune a graph. They are optional; ordinary graph execution does not require PyTorch Geometric.

Start with GNN routing and the GNN example.

Benchmarks and reproducibility

Benchmark code is kept separate from product examples. Each evaluation track has its own directory, entry point, input notes, and output contract under benchmarks/.

Reported results, statistical tests, limitations, and reproduction notes live together in the benchmark documentation. Comparative numbers are intentionally kept out of the front page so that results are read with their scope and caveats.

Scope

gMAS fits workflows that need to:

• model a team with explicit dependencies and parallel branches;
• inspect or visualize how work moves between roles;
• change the remaining workflow based on intermediate results;
• enforce tool, token, time, or iteration budgets centrally;
• mix models or tool permissions across agents;
• collect reproducible traces and per-agent metrics;
• train or evaluate routing and graph-pruning policies.

A direct function chain is usually simpler for a fixed one-model pipeline. For durable checkpointing and human-in-the-loop resume, review the trade-offs in gMAS and LangGraph.

Ecosystem

gMAS is a standalone framework. flowMAS is a separate downstream application that consumes the SDK without changing the core library.

Documentation

The complete documentation is published at frontier-ai-next.github.io/gMAS.

Repository layout

gmas/
├── .github/        # CI, Pages, releases, and contribution templates
├── src/gmas/       # library code
├── tests/          # unit and integration tests
├── examples/       # focused runnable examples
├── benchmarks/     # evaluation harnesses and data contracts
├── docs/           # guides, API reference, and reported results
└── pyproject.toml  # package metadata and optional dependencies

examples/ contains small API demonstrations. benchmarks/ contains evaluation entry points and their run contracts; benchmark configuration is not part of the public library API.

Development

Install the development environment:

git clone https://github.com/frontier-ai-next/gmas.git
cd gmas
uv sync --all-extras --group test --group lint --group typecheck --group docs

Run the release checks:

uv run tox -e lint,quick
uv run --group docs mkdocs build --strict

The test matrix covers Python 3.12 and 3.13. Type checking is currently an advisory check while known type debt is reduced.

See CONTRIBUTING.md for branch, style, test, and pull-request guidance. Release maintainers should also review the release checklist.

Contributing

Open an issue for bugs, missing documentation, new adapters, or API proposals. Discuss larger changes before implementation when they affect graph semantics or public interfaces.

When contributing code:

1. keep changes focused and add tests for observable behavior;
2. preserve typed boundaries around graphs, runners, tools, and results;
3. update the relevant guide when a public API changes;
4. do not commit credentials, benchmark outputs, or provider-specific secrets;
5. use Conventional Commits so release tooling can calculate version changes.

License

gMAS is released under the MIT License.