HydraR: Stateful Agentic Orchestration for R
HydraR: Stateful Agentic Orchestration for R |
|
HydraR is a lightweight orchestrator for building autonomous AI workflows natively in R. It allows researchers to design complex, multi-step processesβsuch as data cleaning, analysis, and report generationβthat are driven by Large Language Models (LLMs) while maintaining the rigorous auditability and reproducibility expected in scientific research.
Think of an "Agent" as an AI-powered assistant that can perform specific tasks. Instead of just "chatting" with an AI, HydraR allows you to link multiple assistants together into a Workflow.
You create a "blueprint" (a visual map) of your research tasks. HydraR then manages the execution: it gives each assistant its own isolated workspace, remembers every step they take (checkpointing), and allows them to "loop back" and fix mistakes if a task fails. This makes AI research reliable, auditable, and automated.
Standard agentic frameworks often rely heavily on brittle API wrappers and volatile state. HydraR addresses three fundamental challenges in scientific AI orchestration:
HydraR creates temporary, isolated project branches for each agent working in parallel. This prevents file corruption and race conditions when multiple tasks run simultaneously.HydraR separates the workflow's design from the code that runs it. This text-based blueprint acts as an "OpenAPI for Agents"βa shareable format that is easy to audit and version-control.To help researchers from different backgrounds, here are the key technical terms used in HydraR:
HydraR to create a separate, temporary version of your project for an agent to work in, preventing them from overwriting your main files accidentally.HydraR is a stateful orchestrator, not a low-level API wrapper. While many excellent packages focus on the communication layer, HydraR focuses on the lifecycle, state, and file-system isolation of multi-agent workflows.
HydraR can use ellmer as a backend driver for individual agents within a larger managed graph.HydraR is designed for more complex research pipelines that require memory, branching logic, and error recovery.HydraR is built for reproducible, non-interactive pipelines and automation that can run independently of the RStudio IDE.HydraR provides a native R alternative that integrates directly with R's statistical and visualization ecosystems without the "translation cost" of using reticulate for core logic.AgentDAG with support for parallel execution (furrr) and conditional loops.AgentState provides a single source of truth for all nodes, with support for complex reducers and history management.Checkpointer (supporting SQLite/DuckDB).You can install the development version from GitHub:
# install.packages("devtools")
devtools::install_github("apaf-bioinformatics/HydraR")
HydraR drives external AI tools via their CLI interfaces. To use the full suite of drivers, ensure your chosen tools are installed and configured.
The Gemini CLI (npm install -g @google/gemini-cli) is provided as an example. You'll then have to start the tool by typing gemini in the terminal and log into your Google account using the /auth command. You can choose to login using your Google account or provide an API key. Other CLI and API offerings have a similar setup; please refer to the manuals of those providers for information on how to set them up.
To use the API-based drivers, store your API keys in a .Renviron file in your project root to keep them secure and accessible to HydraR:
# .Renviron
GOOGLE_API_KEY="your_google_api_key"
GEMINI_API_KEY="your_gemini_api_key"
ANTHROPIC_API_KEY="your_anthropic_api_key"
OPENAI_API_KEY="your_openai_api_key"
[!IMPORTANT] Ensure
.Renvironis added to your.gitignore,.Rbuildignore, and any AI ignore files (e.g.,.agentignore,.claudeignore) to prevent accidental exposure of your secrets during agentic development.
[!TIP] New to HydraR? The primary resource for learning is the Complete Instruction Manual.
AgentDriver for local LLMs or proprietary APIs.targets package.Visit the HydraR Documentation Website for the full API reference and rendered vignettes.
For deep technical dives into the orchestration engine and developer tools, refer to the following manuals:
targets: Best practices for cached, interrupt-safe agentic pipelines.HydraR supports both document-first (YAML/Mermaid) and code-first (R6 classes) orchestration.
This is the most "portable" way to build. Define your graph in a YAML file and load it directly.
# workflow.yml
graph: |
graph LR
A["Research Assistant | type=llm | role_id=analyst"]
B["Quality Auditor | type=logic | logic_id=verify_stats"]
A --> B
B -- "fail" --> A
library(HydraR)
wf <- load_workflow("workflow.yml")
dag <- spawn_dag(wf)
results <- dag$run()
Perfect for developers who want full programmatic control over node logic.
library(HydraR)
# 1. Define a simple logic node
node_hello <- AgentLogicNode$new(
id = "hello_world",
logic_fn = function(state) {
input_text <- state$get("input")
list(status = "SUCCESS", output = list(message = paste("Hello", input_text)))
}
)
# 2. Build the orchestrator
dag <- AgentDAG$new()
dag$add_node(node_hello)
dag$compile()
# 3. Execute
results <- dag$run(initial_state = list(input = "Hydra"))
print(results$results$hello_world$output$message)
# [1] "Hello Hydra"
HydraR includes a powerful visualization engine that goes beyond static DAGs. You can generate status-colored plots after a run to identify bottlenecks and failures.
We recommend using the DiagrammeR package to render your DAGs:
library(HydraR)
library(DiagrammeR)
# Green = Success, Red = Failure, Blue = Active path
DiagrammeR::mermaid(dag$plot(status = TRUE))
HydraR is provider-agnostic. You can extend the framework by creating custom R6 classes that inherit from AgentDriver. This allows you to drive:
httr2.Refer to the Creating Custom Drivers guide for implementation details.
This project was developed at the Australian Proteome Analysis Facility (APAF), Macquarie University. We acknowledge funding from Bioplatforms Australia, enabled by the National Collaborative Research Infrastructure Strategy (NCRIS). APAF is accredited by the National Association of Testing Authorities (NATA) for compliance with the international standard ISO/IEC 17025 (accreditation number 20344).
From the APAF Bioinformatics team at Macquarie University.
This project adheres to the APAF Bioinformatics standards for agentic reproducibility and software hardness. All development followed a "Human-in-the-loop" pattern for AI-assisted contributions.