Osprey Framework Documentation#
An agentic interface to scientific control systems.
The Osprey Framework is an agentic interface and harness for scientific facilities managing complex technical infrastructure, such as particle accelerators. The harness is the layer that stands between the agent and the machine. Osprey runs Claude Code as its agent and wraps it in an operator-facing safety policy, a hook-based approval chain, and an MCP-server multiplexer (MCP, the Model Context Protocol, is how the agent calls tools).
The model behind the agent is a configuration choice, and the code specific to Claude Code sits in one adapter package. The current reference implementation is a browser-based operator workstation; other surfaces (control-room consoles, chat clients, headless services) are possible.
Osprey addresses challenges specific to control systems:
semantic addressing across large channel namespaces;
protocol-agnostic integration with control stacks: EPICS, DOOCS, TANGO and the built-in simulator ship in-tree, and LabVIEW and other stacks are supported via custom connectors;
logbook search across facility electronic logbooks;
mandatory human oversight for safety-critical operations.
A short demo of the operator workstation:
Recorded on the OSPREY demo, which runs a simulated accelerator rather than a real facility. To reproduce it, follow the demo tutorial.
One unedited session of several minutes. The agent's working time is sped up (marked ⏩ with its factor); typing, clicks and the approval play in real time. The clock in the corner shows the real elapsed time.
For the system design, see Architecture.
Documentation Structure#
Install Osprey, create your first project, and deploy the demo with a coding agent and MCP servers.
Task-oriented recipes for adding connectors, configuring providers, deploying projects, and customising MCP servers.
Core concepts: agentic orchestration, MCP servers, connectors, human-in-the-loop safety, and the runtime API.
The exact keys, shapes, and commands: the CLI, every configuration file, and the contracts services exchange.
Development setup, coding standards, testing guidelines, and the contribution workflow.
Citation
If you use the Osprey Framework in your research or projects, please cite our paper:
@article{10.1063/5.0306302,
author = {Hellert, Thorsten and Montenegro, João and Sulc, Antonin},
title = {Osprey: Production-ready agentic AI for safety-critical control systems},
journal = {APL Machine Learning},
volume = {4},
number = {1},
pages = {016103},
year = {2026},
month = {02},
doi = {10.1063/5.0306302},
url = {https://doi.org/10.1063/5.0306302},
}