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.

pip install frontier-ai-gmas

With uv:

uv add frontier-ai-gmas

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.