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

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/sentient-agi-roma
Generated for open source discovery and AI-assisted research.

ROMA is a powerful meta-agent framework designed for building high-performance multi-agent systems using recursive hierarchical structures. It simplifies complex problem-solving by breaking tasks into parallelizable components, offering transparent development and proven performance. This open-source framework is extensible, allowing developers to customize agents and benefit from community-driven improvements.

GitHub: https://github.com/sentient-agi/ROMA
OSRepos URL: https://osrepos.com/repo/sentient-agi-roma

## Summary

ROMA is a powerful meta-agent framework designed for building high-performance multi-agent systems using recursive hierarchical structures. It simplifies complex problem-solving by breaking tasks into parallelizable components, offering transparent development and proven performance. This open-source framework is extensible, allowing developers to customize agents and benefit from community-driven improvements.

## Topics

- Python
- AI
- Multi-Agent Systems
- LLM Framework
- DSPy
- Open-Source
- Agent Framework
- Recursive Agents

## Repository Information

Last analyzed by OSRepos: Sun Nov 23 2025 12:01:03 GMT+0000 (Western European Standard Time)
Detail views: 7
GitHub clicks: 2

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

## 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:
1.  **Atomizer**: Decides if a request is atomic (directly executable) or requires planning.
2.  **Planner**: If planning is needed, the task is broken into smaller subtasks, which are then fed back into the Atomizer, creating a recursive process.
3.  **Executors**: Handle atomic tasks, utilizing LLMs, APIs, or other agents.
4.  **Aggregator**: Collects and integrates results from subtasks to produce the final answer for the parent task.
5.  **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](https://github.com/casey/just){:target="_blank"} 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.

bash
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:

python
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.

## Links

*   **GitHub Repository**: [sentient-agi/ROMA](https://github.com/sentient-agi/ROMA){:target="_blank"}
*   **Official Website**: [Sentient AGI](https://sentient.xyz/){:target="_blank"}
*   **Technical Blog Post**: [Recursive Open Meta-Agent](https://www.sentient.xyz/blog/recursive-open-meta-agent){:target="_blank"}
*   **Quick Start Guide**: Available within the [ROMA GitHub repository](https://github.com/sentient-agi/ROMA/blob/main/docs/QUICKSTART.md){:target="_blank"}