An agentic framework for functional RNA design, combining diffusion-based generation, structure prediction, evaluation, and candidate filtering in a task-oriented workflow.
- Key Features
- Installation
- Agent Skills
- Quick Start
- Project Structure
- Supported Task Types
- Core Components
- Evaluation Metrics
- Checkpoint Ensemble Behavior
- Tool-Call Confirmation Policy
- Dependencies
- Citation
- License
- Task-oriented RNA design: the agent first asks the user to choose a task type, then loads the matching workflow.
- Motif sampling and constrained sequence design: ribozyme tasks support Mode 1 (fully locked fixed motif) and Mode 2 (motif sampling / unlock) via RDiff_seq partial sampling; iterative workflows can also run seed-based partial diffusion for local resampling while keeping key motifs fixed.
- Checkpoint-ensemble design tools: backbone, scaffolding, and sequence design tools can split a requested sample count across all checkpoints in configured checkpoint directories.
- Ribozyme and aptamer scaffolding workflows:
- secondary-structure-conditioned ribozyme design
- subsequence-conditioned ribozyme design
- limited-prior Hovlinc optimization
- Broccoli/Pepper single-motif scaffolding
- Broccoli-Pepper FRET dual-motif scaffolding
- Scaffolding-specific evaluation: WT motif gate, backbone-AF3 self-consistency, C1'-lDDT, compactness, motif-scaffold contacts, and length-aware candidate filtering.
- Two-mode first-round filtering:
standard: sequence recovery, GC, sequence similarity,ss_f1score >= 0.9when available, TM-score rankingscaffolding: backbone-AF3 consistency, compactness, and length-aware selection
- Python 3.9 or higher
- Conda (recommended for environment management)
- RDiff repository:
Please refer to the RDiff repository.
- Clone the repository:
git clone <repository-url>
cd RhoAgent- Create and activate conda environment:
conda create -n RhoAgent python=3.9
conda activate RhoAgent- Install dependencies:
pip install -e .- Configure environment variables:
Create a
.envfile in the project root (or set shell exports) before running the agent. Do not commit real API keys.
RDiff design tools read paths from .env. You must configure the RDiff_str and RDiff_seq
repository directories, the Python interpreter for the RDiff conda environment, and the checkpoint
directories used by each design tool.
export DEFAULT_MODEL="your-model-name"
export DEFAULT_API_BASE="https://your-openai-compatible-endpoint/v1"
export DEFAULT_API_KEY="your-api-key"
# Optional but recommended for evaluation
export DEFAULT_USALIGN_BIN="/path/to/USalign"
# Required: RDiff code repositories
# RDiff_str: structure diffusion (backbone design + motif scaffolding)
export RDIFF_STR_CODE_DIR="/path/to/RDiff_str"
# RDiff_seq: sequence design on generated backbones
export RDIFF_SEQ_CODE_DIR="/path/to/RDiff_seq"
# Python executable from the RDiff conda environment
export PYTHON_CONDA_RDIFF="/path/to/ribodiffusion/bin/python"
# Required: checkpoint directories for ensemble design
# Each directory may contain one or more .pth checkpoints.
# The requested num_samples is split across all checkpoints in the directory.
export RDIFF_BACKBONE_CHECKPOINT_DIR="/path/to/RDiff_str/backbone_checkpoints"
export RDIFF_SCAFFOLDING_CHECKPOINT_DIR="/path/to/RDiff_str/scaffolding_checkpoints"
export RDIFF_SEQUENCE_CHECKPOINT_DIR="/path/to/RDiff_seq/checkpoints"Optional: set RHOAGENT_ROOT or WORKSPACE_ROOT if your .env file lives outside the repo root.
The agent also searches ./.env and <repo-root>/.env automatically.
The skills in skills/ provide an alternative way to use this
repository through another agent, alongside the built-in RhoAgent interface.
They guide the agent through the same design workflows, including local setup,
tool execution, evaluation, and output tracking.
| Skill | Supported workflows |
|---|---|
| Ribozyme design | Motif-constrained design, subsequence-constrained design, and limited-prior iterative optimization. |
| Aptamer design | Single-motif Broccoli/Pepper scaffolding and dual-motif BroccoliβPepper FRET scaffold design. |
Follow the original workflows or ask your agent to add, remove, replace, or reorder steps. The skills check downstream input requirements and record workflow changes.
To get started, ask your agent:
Install the rhoagent-ribozyme-design skill from the skills folder of https://github.com/ml4bio/RhoAgent. Help me install the required tools and configure local paths, then use the original workflow with my RNA sequence, secondary structure, and fixed-motif constraints.
You can also customize a run:
Use my existing structure predictions instead of running AF3, insert my candidate-filter script before evaluation, and omit final LLM ranking.
Install each complete skill folder, including its supporting files. Scientific software and model checkpoints are installed separately; the skills guide prerequisite checks and local path adaptation. See the skills installation and usage guide for details.
The simplest way to start using RhoAgent is through the interactive entry point:
conda activate RhoAgent
python run_agent.pyThe agent will first ask you to choose one task:
- Ribozyme Design
- Subsequence-Conditioned Ribozyme Design
- Hovlinc Limited-Prior Iterative Optimization
- Single-Motif Fluorogenic Aptamer Scaffolding
- Dual-Motif Broccoli-Pepper FRET Scaffold Design
After task selection, the agent collects only the required inputs for that task and asks for parameter confirmation. It must also ask for confirmation before every individual tool call.
from rhoagent.agents.rhoagent_pipeline import build_rna_design_pipeline_agent
# Configure LLM
llm_cfg = {
'model': 'Qwen3-235B-A22B',
'model_server': 'https://dashscope.aliyuncs.com/compatible-mode/v1',
'api_key': 'your-api-key'
}
# Create agent
agent = build_rna_design_pipeline_agent(llm=llm_cfg)
# Run interactive session
messages = [{
'role': 'user',
'content': '''
I want to design a functional RNA structure. Task 1.
- wildtype_seq: ACACCCACCUGUUACAAGUCAGGACAGAAGCAGAGUAACGGUUGCUUACGCAACCGGUAAUGCUACUGGGUGU
- target_ss: (((((((((((.[[[..{{)))).....((((..]]].(((((((....)))))))....))))}})))))))
- fixed_motif: -----------UUACAA---------------G-GUA--------------------UAA-------------
- work_dir: /path/to/output
'''
}]
for response in agent.run(messages=messages):
print(response)RhoAgent/
βββ rhoagent/ # Main package
β βββ agents/ # Agent implementations
β β βββ rhoagent_pipeline.py # RNA Design Pipeline Agent (main)
β β βββ assistant.py # Base assistant agent
β β βββ fncall_agent.py # Function calling agent
β β βββ user_agent.py # User interaction agent
β β βββ doc_qa/ # Document Q&A agents
β β β βββ basic_doc_qa.py
β β β βββ parallel_doc_qa.py
β β β βββ ...
β β βββ keygen_strategies/ # Keyword generation strategies
β βββ tools/ # Tool implementations
β βββ llm/ # LLM integration
β βββ memory/ # Memory management
β β βββ memory.py
β βββ utils/ # Utility functions
β β βββ utils.py
β β βββ output_beautify.py
β β βββ parallel_executor.py
β βββ agent.py # Base agent class
β βββ settings.py # Configuration settings
β βββ multi_agent_hub.py # Multi-agent coordination
βββ examples/ # Example scripts
β βββ rhoagent_example.py # Example usage
β βββ resource/ # Example resources
βββ tests/ # Test files
β βββ agents/ # Agent tests
β βββ llm/ # LLM tests
β βββ tools/ # Tool tests
β βββ pipeline_test_output*/ # Test output directories
βββ run_agent.py # Main entry point
βββ setup.py # Package configuration
βββ MANIFEST.in # Package manifest
βββ LICENSE # Apache 2.0 License
βββ README.md # This file
For Twister-P3, CPEB3, Hammerhead, and related ribozymes.
Typical flow:
- Confirm
wildtype_seq,target_ss,fixed_motif, and work directory. - Run
rdiff_3d_backbone_design_tool. - Run
backbone_filter. - Run
rdiff_seq_design_tool. - Run
seq_filter. - Run
af3_prediction_pipeline. - Run
eval_rna_struct_batch. - Run
first_round_filtering(filter_mode="standard"). - Run
llm_weighted_filter.
Same core flow as Task 1, but the user also provides a subsequence that must be preserved. The subsequence is merged into the fixed motif constraints before sequence design.
For Hovlinc-like cases with limited structural priors.
The agent can infer secondary structure and pocket constraints using AF3, RNApolis, and find_pocket.
Round 2 refinement is possible when wet-lab feedback is available.
For Broccoli or Pepper motif scaffolding.
Uses rdiff_scaffolding_design_tool, not the generic secondary-structure backbone design tool.
Typical inputs:
- motif/reference PDB
- contig template
- scaffold length range
- ligand/ion context for AF3 when needed
Primary evaluation uses scaffolding_structure_eval.
For one-chain Broccoli-Pepper FRET constructs. Uses a dual-motif PDB and a dual-motif contig such as:
10+/A3-16/15+/A29-47/10+/E3-22/15+/E35-47/10+
Primary evaluation uses scaffolding_structure_eval with both Broccoli and Pepper motif specs.
- RNA Design Pipeline Agent (
rhoagent/agents/rhoagent_pipeline.py): Main agent that orchestrates the complete design pipeline - Assistant (
rhoagent/agents/assistant.py): Base assistant with tool usage and file reading capabilities - FnCallAgent (
rhoagent/agents/fncall_agent.py): Function calling agent - UserAgent (
rhoagent/agents/user_agent.py): User interaction agent - Document Q&A Agents (
rhoagent/agents/doc_qa/): Document question-answering agents (basic and parallel)
- RDiff3DBackboneDesignTool (
rdiff_3d_backbone_design_tool): Secondary-structure-conditioned backbone generation with RDiff_str.- Requires
RDIFF_STR_CODE_DIRandPYTHON_CONDA_RDIFFin.env. - Reads checkpoints from
RDIFF_BACKBONE_CHECKPOINT_DIRunlesscheckpoint_dirorcheckpoint_pathsis passed. - Splits total
num_samplesacross all checkpoints.
- Requires
- RDiffScaffoldingDesignTool (
rdiff_scaffolding_design_tool): Motif scaffolding using RDiff_strrna_scaffolding_training+scaffolding_iter.- Requires
RDIFF_STR_CODE_DIRandPYTHON_CONDA_RDIFFin.env. - Reads checkpoints from
RDIFF_SCAFFOLDING_CHECKPOINT_DIR. - Inputs include
target_pdb_path,contigs, length range, and totalnum_samples. - Merges shard outputs into
output_dir/inference_name.
- Requires
- RDiffSeqDesignTool (
rdiff_seq_design_tool): Sequence design on filtered backbones with RDiff_seq.- Requires
RDIFF_SEQ_CODE_DIRandPYTHON_CONDA_RDIFFin.env. - Reads checkpoints from
RDIFF_SEQUENCE_CHECKPOINT_DIR. - Splits total
num_samplesacross all sequence checkpoints.
- Requires
- AF3PredictionPipelineTool: Batch structure prediction using AlphaFold3
- ExtractSSTool: Extract secondary structure (dot-bracket) from PDB/CIF files
- FindPocketTool: Identify functional pocket regions from structure and seed positions
- Mxfold2PredictTool: Predict secondary structure from sequence
- AnalyzeRNAStructureTool: Analyze RNA structure and return chain, residue, and base pair statistics
- EvalRNAStructBatchTool: Batch evaluation of predicted structures
- TM-score and RMSD (structural similarity)
- Sequence recovery rate and sequence similarity
- Secondary structure F1-score (ss_f1score)
- Functional core F1-score (functional_core_f1score)
- Canonical pair ratios (
ss_pairs_ratio,designed_pseudoknot_canonical_pairs_ratio)
- ScaffoldingStructureEvalTool: Scaffolding-specific AF3 evaluation
- WT motif gate
- motif RMSD/TM only when WT motif gate passes
- backbone-AF3 TM/RMSD/lDDT
- compactness and motif-scaffold contact metrics
- FirstRoundFilterTool: First-round filtering based on multiple criteria
filter_mode="standard"for ribozyme/general evalsfilter_mode="scaffolding"for length-aware scaffolding selection
- LLMWeightedFilterTool: LLM-determined weighted filtering for final candidate selection
- PipelineCriticTool: Quality evaluation and decision-making for pipeline steps
- BackboneFilterTool: Filter backbone structures based on secondary structure matching
- SeqFilterTool: Filter FASTA records using GC, homopolymer, duplicate, optional repeated subsequence, and optional recovery-rate criteria
The evaluation system provides comprehensive metrics for RNA design assessment:
- TM-score: Structural similarity score (0-1, higher is better)
- RMSD: Root mean square deviation (lower is better)
- seq_rec_rate: Sequence recovery rate (percentage of identical positions)
- seq_similarity: Sequence similarity using local alignment (0-1)
- ss_f1score: F1-score for secondary structure prediction (0-1)
- functional_core_f1score: F1-score for fixed motif regions (0-1)
- ss_pairs_ratio: Ratio of canonical pairs (AU+GC+GU) in target structure
- designed_pseudoknot_canonical_pairs_ratio: Ratio of canonical AU/GC/GU pairs in designed/predicted pseudoknot regions
- backbone_af3_tm_score / backbone_af3_rmsd: AF3 prediction self-consistency against generated backbone
- backbone_af3_lddt: C1'-based lDDT after backbone alignment
- rg_norm / end_to_end_dist_norm: Length-normalized compactness metrics
- non_motif_long_range_contact_density: Contacts among non-motif scaffold residues
- isolated_scaffold_fraction: Fraction of weakly connected scaffold residues
- motif_scaffold_contact_count: Potential unintended long-range motif-scaffold contacts
- motif_rmsd / motif_tm_score: Used only when the WT motif gate indicates AF3 can reproduce the wild-type motif
The design tools support running multiple checkpoints automatically. The requested num_samples
is treated as the total number of samples and split approximately evenly across checkpoints in the
configured directory.
Example:
export RDIFF_SEQUENCE_CHECKPOINT_DIR=/path/to/RDiff_seq/checkpointsIf that directory contains four .pth files and the tool receives num_samples=100,
each checkpoint is assigned about 25 samples. Exact allocation uses integer round-robin splitting.
You can override the .env directory per call using:
checkpoint_dircheckpoint_paths
The pipeline agent is intentionally conservative. Before any tool call, it must show:
- the exact registered tool name
- the exact JSON parameters
- a prompt asking the user to confirm or modify the call
The agent should not call the tool until the user confirms the parameters.
dashscope>=1.11.0: Alibaba Cloud DashScope APIpydantic>=2.3.0: Data validationopenai: OpenAI-compatible API supportrequests,json5,jsonschema: HTTP and JSON handlingBio: Biopython for biological data processingnumpy,pandas: Numerical computing and data manipulation
run_agent.py: Main entry point for running the RNA design agent interactivelysetup.py: Package configuration and dependenciesMANIFEST.in: Files to include in package distribution.gitignore: Git ignore patterns
If you use RhoAgent in your research, please cite the associated paper:
@article{rhoagent,
title = {Programmable functional RNA design with a virtual scientist},
author = {Han Huang, Tianqing Zhang, Liang Hong, Ziqian Lin, Dongchen He, Jiuming Wang, Tian-Ying Wu, Huimin Li, Da Han, Le Yu, Jiyue Jiang, Yimin Fan, Yanruisheng Shao, Irwin King, Pengan Chen, Chun Kit Kwok, James J. Collins, and Yu Li},
journal = {Nature Biotechnology},
year = {2026},
doi = {10.1038/s41587-026-03362-3}
}RhoAgent is released under the Apache License 2.0.