ursa-ai 0.15.9

Agents for science at LANL

URSA - The Universal Research and Scientific Agent

The flexible agentic workflow for accelerating scientific tasks. Composes information flow between agents for planning, code writing and execution, and online research to solve complex problems.

The original ArXiv paper is here.

Installation

You can install ursa via pip or uv. Installing ursa in a clean environment with python 3.11-3.12 may be necessary. (Some ursa dependencies currently do not support python>=3.13.)

uv

uv init -p 3.12  # or 3.11
uv add ursa-ai

pip

pip install ursa-ai

conda with pip install

conda create -y -n ursa-env python=3.12  # or 3.11
conda run --live-stream -n ursa-env python -m pip install ursa-ai

How to use this code

Better documentation will be incoming, but for examples in the examples/ folder demonstrates how to set up some basic problems. They also should give some idea of how to pass results from one agent to another. I will look to add things with multi-agent graphs, etc. in the future.

Documentation for each URSA agent:

• Planning Agent
• Execution Agent
• ArXiv Agent
• DSI Agent
• Web Search Agent
• Hypothesizer Agent

Documentation for combining agents:

• ArXiv -> Execution for Materials
• ArXiv -> Execution for Neutron Star Properties

Command Line Usage

You can install ursa as a command line app with pip install; or with uv via

uv tool install ursa-ai

To use the command line app, run

ursa --llm_model.model openai:gpt-5.2

This will start a REPL in your terminal.

  __  ________________ _
 / / / / ___/ ___/ __ `/
/ /_/ / /  (__  ) /_/ /
\__,_/_/  /____/\__,_/

For help, type: ? or help. Exit with Ctrl+d.
ursa>

Within the REPL, you can get help by typing ? or help.

You can chat with an LLM by simply typing into the terminal.

ursa> How are you?
Thanks for asking! I’m doing well. How are you today? What can I help you with?

You can run various agents by typing the name of the agent. For example,

ursa> plan
plan: Write a python script to do linear regression using only numpy.

Or by prepending the agent name to the query:

ursa> plan Write a python script to do linear regression using only numpy.

If you run subsequent agents, the last output will be appended to the prompt for the next agent.

So, to run the Planning Agent followed by the Execution Agent:

ursa> plan
plan: Write a python script to do linear regression using only numpy.

...

ursa> execute
execute: Execute the plan.

You can get a list of available command line options via

ursa --help

Web Dashboard

The URSA web interface can be launched with:

ursa-dashboard

or with

ursa-dashboard --host 127.0.0.1 --port 8080

This requires installing with the optional [dashboard] dependencies.

Configuring URSA

See the example configuration file and documentation for more details.

URSA MCP Server

You can connect ursa as an Model Context Protocol Server to other agentic frameworks or interfaces. To start the MCP server, run:

ursa mcp-server --transport streamable-http

This will start an MCP server on localhost on port 8000.

[!WARNING] The MCP Server does not isolate sessions from one another. As such, using the server in a multi-user context is not recommended.

MCP Inspector

After installing the MCP Inspector, you can test the Ursa MCP server by running:

npx @modelcontextprotocol/inspector \
    uv run ursa mcp-server

Or by connecting to an existing MCP server using the streamable-http transport by running:

npx @modelcontextprotocol/inspector \
    --transport http \
    --server-url http://localhost:8000/mcp

You can test the server using curl from another terminal:

The MCP server configuration options can be seen with:

ursa mcp-server --help

The served instance of ursa can be configured via a configuration file (ursa --config config.yaml mcp-server...) or command line arguments (ursa --llm_model.model openai:gpt-5 ... mcp-server ...).

Sandboxing

The Execution Agent is allowed to run system commands and write/run code. Being able to execute arbitrary system commands or write and execute code has the potential to cause problems like:

• Damage code or data on the computer
• Damage the computer
• Transmit your local data

The Web Search Agent scrapes data from urls, so has the potential to attempt to pull information from questionable sources.

Some suggestions for sandboxing the agent:

• Creating a specific environment such that limits URSA's access to only what you want. Examples:
  • Creating/using a virtual machine that is sandboxed from the rest of your machine
  • Creating a new account on your machine specifically for URSA
• Creating a network blacklist/whitelist to ensure that network commands and webscraping are contained to safe sources

You have a duty for ensuring that you use URSA responsibly.

Container image

To enable limited sandboxing insofar as containerization does this, you can run the following commands:

Docker

# Pull the image
docker pull ghcr.io/lanl/ursa

# Run script from host system
mkdir -p scripts
echo "import ursa; print('Hello from ursa')" > scripts/my_script.py
docker run -e "OPENAI_API_KEY"=$OPENAI_API_KEY \
    --mount type=bind,src=$PWD/scripts,dst=/mnt/workspace \
    ghcr.io/lanl/ursa \
    bash -c "uv run /mnt/workspace/my_script.py"

Charliecloud

Charliecloud is a rootless alternative to docker that is sometimes preferred on HPC. The following commands replicate the behaviors above for docker.

# Pull the image
ch-image pull ghcr.io/lanl/ursa ursa

# Convert image to sqfs, for use on another system
ch-convert ursa ursa.sqfs

# Run script from host system (if wanted, replace ursa with /path/to/ursa.sqfs)
mkdir -p scripts
echo "import ursa; print('Hello from ursa')" > scripts/my_script.py
ch-run -W ursa \
    --unset-env="*" \
    --set-env \
    --set-env="OPENAI_API_KEY"=$OPENAI_API_KEY \
    --bind ${PWD}/scripts:/mnt/workspace \
    --cd /mnt/workspace \
    -- bash -c \
    "uv run --no-sync my_script.py"

Development Dependencies

• uv

  • uv is an extremely fast python package and project manager, written in Rust. Follow installation instructions here

• ruff

  • An extremely fast Python linter and code formatter, written in Rust.
  • After installing uv, you can install ruff with uv tool install ruff

• just

  • A modern way to save and run project-specific commands
  • After installing uv, you can install just with uv tool install rust-just

Development Team

URSA has been developed at Los Alamos National Laboratory as part of the ArtIMis project.

Notice of Copyright Assertion (O4958):

This program is Open-Source under the BSD-3 License. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.