Infrastructure for AI agents¶

The LUMI AI Factory develops software infrastructure that supports the use of AI agents for LUMI-related tasks. The current offering comprises a containerized agent environment for using the OpenCode coding agent on LUMI and an MCP server that provides agents access to relevant user documentation.

Agent environment¶

The LUMI AI Factory agent environment is a containerized environment for running AI coding agents on LUMI in a more secure manner. Currently, we provide a container for using the open-source, terminal-based OpenCode AI coding agent. For more information on OpenCode, see the LUMI AI Factory blog post on connecting OpenCode to a vLLM instance running on LUMI. The source code of the agent environment is available in a public GitHub repository.

Responsibility for running AI agents

The user is always responsible for the actions of their AI agents. Understand that any command run by your agent is executed under your personal user account. As a LUMI user, you must always follow the LUMI Terms of Use.

Read also the LUMI AI agent guide and the below must read section.

Must read¶

Please ensure you understand the following points before using the agent environment:

Data privacy: OpenCode uses the third-party OpenCode Zen model endpoint by default, which is hosted by Anomaly Innovations Inc., the company that maintains OpenCode. If you use models from this endpoint, be aware that any data that you enter or is read from your working directory will be sent to the company hosting the endpoint. Consider configuring OpenCode to use a different endpoint, for example a custom endpoint.
Data security: Your current working directory ($PWD) and any subdirectories are accessible inside the environment. Your home directory is not accessible, with the exception of certain directories, where OpenCode looks for configuration files and stores data.
Tool use: The default configuration file included in the environment enforces prompting the user for permission to use any tools, including reading and writing, except for the LUMI AIF MCP server.
Experimental status: The agent environment is experimental and may evolve rapidly. It is recommended to check the GitHub repository for any changes to agent capabilities and permissions before use.

How to use¶

The default OpenCode Zen model endpoint does not require the user to authenticate, but free usage is limited. It is recommended to use OpenCode with a custom endpoint.

# Load relevant modules
module load Local-LAIF lumi-aif-agents

# Start opencode
#
# NB! This gives OpenCode access to your current
# working directory, as well as any subdirectories.
#
opencode

Your home directory, as well as any project directories under, e.g, /scratch, are not mounted in the container environment by default. If you wish OpenCode to have access to directories that are not under your current working directory, you can bind mount them by appending them to the SINGULARITY_BIND environment variable.

# Bind mount additional directories (optional)
export SINGULARITY_BIND=$SINGULARITY_BIND,/path/to/dir1,/path/to/dir2

opencode /path/to/dir1

To find out more about accessing directories inside containers, see the SingularityCE documentation on bind paths and mounts.

Capabilities and limitations¶

OpenCode has the following capabilities and limitations inside the agent environment:

Mounted directories can be read and written to, but the default configuration file shipped with the container enforces prompting for permission before executing any commands.
OpenCode has access to the LUMI AI Factory MCP Server for retrieving context information that helps it write code that takes into account LUMI's computing environment.
The AGENTS.md file that ships with the container provides basic runtime context, such as the limitations of login nodes and the Lustre file system.
Slurm commands are not available inside the container. We are working on implementing this feature in a secure manner.

Using a custom endpoint¶

You can configure a custom model endpoint by creating an opencode.json configuration file, e.g., in your current working directory. See OpenCode's config precedence order for more information.

The agent environment container ships with a default configuration. You can find documentation on how to write your own opencode.json in the OpenCode documentation.

Store your opencode.json in a mounted directory

The opencode.json file needs to be in a directory accessible inside the environment. It is recommended to store the file either in the current directory (project-specific) or under ~/.config/opencode/ (global), both of which are mounted in the environment and searched by OpenCode by default.

MCP server¶

The LUMI AI Factory provides a public Model Context Protocol (MCP) server, which can be found at https://lumi-aif-agents.2.rahtiapp.fi/mcp. The server features a tool called retrieve_docs, which allows agents to search a regularly-updated knowledge base of LUMI documentation. The search functionality is implemented using an embedding model that is run locally on the MCP server host.

Access to this tool allows AI agents to, e.g., answer questions about LUMI with more accuracy and write code that takes into account LUMI's particular system architecture and software environment.

The knowledge base is comprised of the following sources:

LUMI Docs (this site)
LUMI AI Guide

Test the server¶

To understand how the server works, it is possible to test it manually using, e.g., the FastMCP CLI.

# Install FastMCP Python package
pip install fastmcp

# List available tools
fastmcp list https://lumi-aif-agents.2.rahtiapp.fi/mcp

# Call the retrieve_docs tool with query string
# "how to use pytorch on lumi" and return top 2 matches
fastmcp call https://lumi-aif-agents.2.rahtiapp.fi/mcp \
    retrieve_docs 'query=how to use pytorch on lumi' 'k=2'

Connect a client¶

MCP servers can be used with a variety of platforms, such as IDEs (e.g., VS Code), CLI coding assistants (e.g., OpenCode) and web-based chat interfaces (e.g., Claude Web).

An example opencode.json config file is provided for using the LUMI AIF MCP server in OpenCode.

{
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
        "lumi-aif-server": {
            "type": "remote",
            "url": "https://lumi-aif-agents.2.rahtiapp.fi/mcp"
        }
    }
}