ROMA: Recursive Open Meta-Agents for High-Performance Multi-Agent Systems

Introduction

ROMA (Recursive Open Meta-Agents) is a powerful meta-agent framework designed to build high-performance multi-agent systems. It leverages recursive hierarchical structures to effectively solve complex problems by breaking them down into parallelizable components. This approach enables agents to tackle sophisticated reasoning challenges while maintaining transparency, making context engineering and iteration straightforward.

The core of ROMA operates on a recursive plan-execute loop:

Atomizer: Decides if a request is atomic (directly executable) or requires planning.
Planner: If planning is needed, the task is broken into smaller subtasks, which are then fed back into the Atomizer, creating a recursive process.
Executors: Handle atomic tasks, utilizing LLMs, APIs, or other agents.
Aggregator: Collects and integrates results from subtasks to produce the final answer for the parent task.
Verifier (Optional): Inspects the aggregated output against the original goal before delivery.

ROMA offers parallel problem-solving, transparent development with a clear structure for easy debugging, and proven performance, as demonstrated through its search agent's strong benchmark results. As an open-source and extensible platform, ROMA is built for community-driven development, allowing you to customize agents for specific needs.

Installation

The recommended way to set up ROMA for production-ready features, including persistence, API, and observability, is using Docker.

Prerequisites:

Docker & Docker Compose
Python 3.12+ (for local development)
Just command runner (optional, recommended)

Complete Setup with Docker:
This single command builds Docker images, starts all services (PostgreSQL, MinIO, REST API), configures the environment, and optionally sets up S3 storage or E2B code execution.

just setup

You can verify services are running by checking curl http://localhost:8000/health.
Required environment variables for LLM providers (e.g., OPENROUTER_API_KEY, OPENAI_API_KEY) are typically configured automatically by just setup or can be set manually.

Examples

ROMA's modular design allows for flexible orchestration. Here's a quick example mirroring a typical end-to-end workflow, showcasing how different modules can work with distinct models and strategies:

import dspy
from roma_dspy import Aggregator, Atomizer, Executor, Planner, Verifier, SubTask
from roma_dspy.types import TaskType

# Optional tool that the Executor may call
def get_weather(city: str) -> str:
    """Return a canned weather report for the city."""
    return f"The weather in {city} is sunny."

# Executor geared toward ReAct with a Fireworks model
executor_lm = dspy.LM(
    "fireworks_ai/accounts/fireworks/models/kimi-k2-instruct-0905",
    temperature=0.7,
    cache=True,
)
executor = Executor(
    lm=executor_lm,
    prediction_strategy="react",
    tools=[get_weather],
    context_defaults={"track_usage": True},
)

# Atomizer decides when to branch into planning
atomizer = Atomizer(
    lm=dspy.LM("openrouter/google/gemini-2.5-flash", temperature=0.6, cache=False),
    prediction_strategy="cot",
    context_defaults={"track_usage": True},
)

# Planner produces executable subtasks for non-atomic goals
planner = Planner(
    lm=dspy.LM("openrouter/openai/gpt-4o-mini", temperature=0.85, cache=True),
    prediction_strategy="cot",
    context_defaults={"track_usage": True},
)

aggregator = Aggregator(
    lm=dspy.LM("openrouter/openai/gpt-4o-mini", temperature=0.65),
    prediction_strategy="cot",
)

verifier = Verifier(
    lm=dspy.LM("openrouter/openai/gpt-4o-mini", temperature=0.0),
)

def run_pipeline(goal: str) -> str:
    atomized = atomizer.forward(goal)
    if atomized.is_atomic or atomized.node_type.is_execute:
        execution = executor.forward(goal)
        candidate = execution.output
    else:
        plan = planner.forward(goal)
        results = []
        for idx, subtask in enumerate(plan.subtasks, start=1):
            execution = executor.forward(subtask.goal)
            results.append(
                SubTask(
                    goal=subtask.goal,
                    task_type=subtask.task_type,
                    dependencies=subtask.dependencies,
                )
            )
        aggregated = aggregator.forward(goal, results)
        candidate = aggregated.synthesized_result

    verdict = verifier.forward(goal, candidate)
    if verdict.verdict:
        return candidate
    return f"Verifier flagged the output: {verdict.feedback or 'no feedback returned'}"

print(run_pipeline("Plan a weekend in Barcelona and include a packing list."))

This example demonstrates how ROMA's modules, each potentially using different Language Models and prediction strategies, can be orchestrated to achieve complex goals.

Why Use ROMA?

ROMA stands out as a robust framework for building advanced AI agents due to several key advantages:

Parallel Problem Solving: ROMA's recursive decomposition allows agents to work on different parts of complex tasks simultaneously, significantly improving efficiency and throughput.
Transparent Development: The clear, hierarchical structure of ROMA makes it easy to understand, debug, and iterate on agent behaviors, simplifying context engineering.
Proven Performance: The framework has demonstrated strong benchmark results, particularly with its search agent, across challenging datasets like SEAL-0, FRAMES, and SimpleQA, showcasing its effectiveness in fact-seeking and reasoning tasks.
Open-Source and Extensible: ROMA is designed for community-driven development, providing a flexible and customizable platform where developers can build and adapt agents to their specific needs, benefiting from collective improvements.
DSPy Integration: Built upon DSPy, ROMA leverages a declarative framework for prompting, planning, and tool integration, ensuring stable interfaces and powerful reasoning capabilities.
Comprehensive Toolkits: It includes 9 built-in toolkits for various functionalities, from file operations and code execution to crypto data and web search, making agents highly versatile.

ROMA: Recursive Open Meta-Agents for High-Performance Multi-Agent Systems

Summary

Repository Info

Tags

Introduction

Installation

Examples

Why Use ROMA?

Links