QUICKSTART.md

🚀 Quick Start — gMAS

This brief guide will help you get started with the framework in 5 minutes.

Installation

pip install rustworkx>=0.13 pydantic>=2.0 pydantic-settings>=2.0 torch>=2.0 loguru>=0.7
pip install sentence-transformers>=2.0  # optional, for embeddings

Step 1: Create Agents

from core import AgentProfile

# Each agent has a unique agent_id and a description of its role
# Embeddings and state are stored inside AgentProfile (decentralized)
agents = [
    AgentProfile(
        agent_id="researcher",
        display_name="Researcher",
        description="Searches for information and collects facts",
        tools=["search", "browse"],
    ),
    AgentProfile(
        agent_id="analyst",
        display_name="Analyst",
        description="Analyzes data and draws conclusions",
        tools=["calculate", "compare"],
    ),
    AgentProfile(
        agent_id="writer",
        display_name="Writer",
        description="Formulates the final answer",
    ),
]

Step 2: Build the Graph

from builder import build_property_graph

# Define connections: researcher -> analyst -> writer
workflow_edges = [
    ("researcher", "analyst"),
    ("analyst", "writer"),
]

# Build the graph with a task
graph = build_property_graph(
    agents,
    workflow_edges=workflow_edges,
    query="What technologies will be important in 2025?",
)

print(f"Graph: {graph.num_nodes} nodes, {graph.num_edges} edges")

Step 3: Configure LLM

# Example with OpenAI
import openai

def my_llm_caller(prompt: str) -> str:
    response = openai.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": prompt}],
    )
    return response.choices[0].message.content

# Example with local Ollama
import requests

def ollama_caller(prompt: str) -> str:
    response = requests.post(
        "http://localhost:11434/api/generate",
        json={"model": "llama3", "prompt": prompt, "stream": False},
    )
    return response.json()["response"]

Step 4: Run Execution

from execution import MACPRunner

runner = MACPRunner(llm_caller=my_llm_caller)
result = runner.run_round(graph)

print("=" * 50)
print(f"Execution order: {result.execution_order}")
print(f"Tokens used: {result.total_tokens}")
print(f"Time: {result.total_time:.2f} sec")
print("=" * 50)
print(f"\n📝 Final answer:\n{result.final_answer}")

Step 5: Streaming (optional)

from execution import StreamEventType

# Get results in real time
for event in runner.stream(graph):
    if event.event_type == StreamEventType.AGENT_START:
        print(f"\n🤖 {event.agent_name} started...")
    elif event.event_type == StreamEventType.AGENT_OUTPUT:
        print(f"✅ {event.agent_name}: {event.content[:100]}...")
    elif event.event_type == StreamEventType.RUN_END:
        print(f"\n🏁 Completed in {event.total_time:.2f} sec")

---

Useful Patterns

Parallel Processing

# Multiple agents work in parallel
edges = [
    ("planner", "researcher_1"),
    ("planner", "researcher_2"),
    ("researcher_1", "synthesizer"),
    ("researcher_2", "synthesizer"),
]

from execution import RunnerConfig

config = RunnerConfig(enable_parallel=True, max_parallel_size=3)
runner = MACPRunner(llm_caller=my_llm, config=config)

Dynamic Graph Modification

# Add a new agent on the fly
new_agent = AgentProfile(agent_id="fact_checker", display_name="Fact Checker")
graph.add_node(new_agent, connections_to=["writer"])
graph.add_edge("analyst", "fact_checker", weight=0.8)

Asynchronous Execution

async def async_llm(prompt: str) -> str:
    # Your async LLM call
    return await call_llm_async(prompt)

runner = MACPRunner(async_llm_caller=async_llm)
result = await runner.arun_round(graph)

---

Next Steps

📚 Read the full documentation for:

• Memory and agent embedding configuration (stored inside AgentProfile)
• GNN routing
• Adaptive execution with pruning and fallback
• PyTorch Geometric integration
• Configuration via environment variables

💡 Explore the examples in the examples/ folder:

• basic_usage.py — basic operations
• gnn_routing.py — GNN routing
• streaming_example.py — streaming execution