Add a Broadsea-based integrated Docker deployment for StudyAgent + slash-ohdsi R clients

Motivation

StudyAgent currently has a lightweight Docker deployment for the Python ACP and MCP services. This works well for Python-only functionality, but several StudyAgent MCP workflows invoke native R/HADES functionality through Rscript. The current StudyAgent container does not include R or a HADES runtime, so these workflows cannot run inside the existing container without either:

1. building and maintaining a complete R/HADES environment in the StudyAgent image, or
2. introducing a separate R execution service and remote-execution interface.

For deployments that already need the OHDSI HADES stack, neither approach is ideal.

OHDSI Broadsea already provides a maintained Broadsea-Hades image containing R, HADES, JDBC support, RStudio Server, and supporting system dependencies. A better long-term deployment model may therefore be to build a StudyAgent-enabled image derived from Broadsea-Hades and integrate it with Broadsea.

This would provide a reproducible container environment containing:

• StudyAgent MCP
• StudyAgent ACP
• R and HADES
• slashOhdsiAcpClient
• slashOhdsiStrategusAssistant
• the R dependencies required by the StudyAgent R-backed MCP tools

while preserving the current lightweight/native deployment options.

Proposed approach

Create an experimental Broadsea-based StudyAgent deployment, initially maintained through forks or feature branches of the relevant repositories.

The likely implementation direction is to extend OHDSI/Broadsea-Hades rather than expand the current StudyAgent Alpine image.

Broadsea-Hades already provides:

• R/RStudio
• HADES packages installed from an official HADES release renv.lock
• DatabaseConnector/JDBC support
• Python and Python virtual-environment tooling
• Rserve
• Supervisor-based process management

StudyAgent would add its Python ACP/MCP runtime and its two R-side integration packages to that environment.

Repositories involved

OHDSI/StudyAgent

Install the StudyAgent Python package and expose the existing services:

• study-agent-mcp
• study-agent-acp

The integrated image should continue using the existing versioned config.yaml plus external secret configuration model.

ACP and MCP should remain independently addressable services/processes even if initially hosted within a common image.

OHDSI/Broadsea-Hades

Use Broadsea-Hades as the base runtime rather than recreating the HADES/R environment in the current StudyAgent Dockerfile.

Extend the image build to install:

• StudyAgent Python runtime
• slashOhdsiAcpClient
• slashOhdsiStrategusAssistant

and any additional R dependencies not already present in the selected HADES release.

The implementation should preserve Broadsea-Hades's existing HADES versioning/lockfile mechanism rather than independently constructing another HADES R environment.

OHDSI/Broadsea

Add an experimental StudyAgent profile/service definition that can be enabled independently, for example:

docker compose --profile study-agent up -d

The exact service structure should be determined during implementation. Possible approaches include:

1. one StudyAgent-enabled HADES image running RStudio, MCP, and ACP under Supervisor; or
2. multiple services using the same StudyAgent-enabled HADES image but separate ACP/MCP commands.

The second model may give cleaner process isolation while avoiding multiple independently maintained images.

OHDSI/SlashOhdsiAcpClient

Install the package into the image as the supported R client for ACP.

No major architectural change should be required because this package is intentionally a thin HTTP client.

Add container-level smoke testing demonstrating that R code inside the image can reach the ACP service.

OHDSI/SlashOhdsiStrategusAssistant

Install the package and its required HADES dependencies into the same R environment.

Validate the major workflows currently exposed by the package, including those that call ACP while executing deterministic Strategus/HADES operations locally.

The container should provide the same R package/runtime environment to both interactive RStudio users and R processes spawned by StudyAgent MCP.

Configuration model

Preserve the current StudyAgent configuration split:

• config.yaml: validated, non-secret configuration
• environment/Docker secrets: credentials and database connection strings

Container-specific values should be expressed through a StudyAgent docker or Broadsea-specific profile rather than embedded into source code.

Examples include:

• ACP/MCP bind addresses
• ACP-to-MCP internal URL
• phenotype-index path
• R executable/library path
• LLM and embedding service URLs
• host/container network rewriting

Database credentials, API keys, and OMOP_DB_ENGINE must remain outside config.yaml.

R runtime requirements

A major goal of this work is to guarantee that StudyAgent MCP and interactive R/HADES execution use the same tested R runtime.

The image should therefore have an explicit and testable contract for:

• R version
• HADES release
• Rscript location
• R library location
• slashOhdsiStrategusAssistant version/commit
• slashOhdsiAcpClient version/commit
• StudyAgent version/commit

StudyAgent's mcp.r.rscript and mcp.r.library configuration should point to paths that are intrinsic to the image rather than bind-mounted host installations.

Architecture support

Broadsea currently has services that remain pinned to linux/amd64, including the HADES service.

An important part of this work should be evaluating ARM64 compatibility because StudyAgent deployments may run on AWS Graviton or Apple Silicon.

At minimum:

• document whether the integrated image is initially AMD64-only;
• test whether Broadsea-Hades itself can build natively on ARM64;
• identify any HADES/R dependencies that prevent multi-architecture builds;
• avoid silently relying on emulation where it creates significant performance or compatibility problems.

A multi-architecture linux/amd64 + linux/arm64 image would be preferred if feasible.

Process management

Broadsea-Hades already uses Supervisor.

Evaluate using Supervisor to manage:

• RStudio/Rserve as currently configured
• StudyAgent MCP
• StudyAgent ACP

Alternatively, run ACP and MCP as separate Compose services based on the same image.

Whichever approach is chosen should provide:

• independent health checks
• clear service logs
• automatic restart on failure
• predictable startup ordering
• ability to invoke ACP and MCP without requiring RStudio

Networking

The integrated deployment should support at least:

• ACP → MCP communication within the Broadsea Docker network
• StudyAgent → OpenAI-compatible LLM endpoint
• StudyAgent → embedding endpoint
• StudyAgent/Keeper → OMOP database
• R client → ACP
• MCP → local Rscript

The deployment should work both when dependencies are other Broadsea services and when LLM/database services are external.

Build reproducibility

Prefer pinned/versioned inputs rather than installing current main branches without provenance.

The resulting image should record or otherwise make discoverable:

• StudyAgent commit/version
• SlashOhdsiAcpClient commit/version
• SlashOhdsiStrategusAssistant commit/version
• Broadsea-Hades version
• HADES release
• R version

Where practical, the image build should fail if these components cannot be installed consistently.

Testing / acceptance criteria

Initial acceptance criteria:

• Integrated image builds reproducibly.
• StudyAgent MCP starts successfully.
• StudyAgent ACP starts successfully.
• ACP health endpoint succeeds.
• MCP health/initialization succeeds.
• ACP can invoke MCP over the container network.
• MCP can invoke the image's native Rscript.
• R can load slashOhdsiAcpClient.
• R can load slashOhdsiStrategusAssistant.
• R client can call an ACP health/simple flow endpoint.
• A StudyAgent MCP operation requiring R can execute successfully.
• A minimal Strategus Assistant workflow can communicate with StudyAgent ACP.
• OMOP DB connectivity can be supplied exclusively through external secret configuration.
• LLM and embedding endpoints can be configured externally.
• Logs are available through normal Docker/Broadsea mechanisms.
• Existing Broadsea profiles continue to work without StudyAgent enabled.
• Existing native StudyAgent deployment remains supported.
• Architecture support (amd64, and preferably arm64) is documented and tested.

Non-goals for the first iteration

The first implementation does not need to:

• replace native StudyAgent installation;
• make StudyAgent mandatory for normal Broadsea deployments;
• merge the three repositories;
• redesign ACP/MCP APIs;
• move HADES execution out of R;
• replace Broadsea's existing R/HADES dependency management.

The goal is to establish a reproducible optional deployment in which the Python orchestration layer and the R/HADES execution environment coexist correctly.

Suggested implementation sequence

1. Build a proof-of-concept image derived from Broadsea-Hades with StudyAgent installed.
2. Add slashOhdsiAcpClient and slashOhdsiStrategusAssistant.
3. Verify local MCP → R execution.
4. Run ACP and MCP in the image and establish health checks.
5. Add a small end-to-end R → ACP → MCP → R smoke test.
6. Add an experimental Broadsea study-agent profile.
7. Test database, LLM, and embedding service configuration.
8. Evaluate native ARM64 build support.
9. Add CI image-build and smoke tests.
10. Document versioning, configuration, secrets, and upgrade procedures.

Rationale

The main architectural principle is to bring StudyAgent into an existing reproducible HADES runtime rather than attempt to graft a host R installation onto a Python-first container.

That should reduce duplicated dependency management, make the R-backed MCP tools portable, and provide a clearer path to distributing a complete StudyAgent/HADES environment to OHDSI users.