Osprey Framework Documentation#
🚧 Early Access Documentation
Current Release: v0.11.5 Early Access
This documentation is part of an early access release and is under active development. Many sections are still being written, edited, or reorganized. Expect inconsistencies, missing content, outdated references, and broken cross-links.
We welcome feedback! If you find issues or have suggestions, please open an issue on our GitHub page.
What is Osprey Framework?#
The Osprey Framework is a production-ready architecture for deploying agentic AI in large-scale, safety-critical control system environments. Built on LangGraph’s StateGraph foundation, it transforms natural language inputs into transparent, auditable multi-step workflows designed for operational safety and reliability.
Developed for scientific facilities managing complex technical infrastructure such as particle accelerators, fusion experiments, beamlines, and large telescopes, Osprey addresses control-specific challenges: semantic addressing across large channel namespaces, flexible orchestration (plan-first and reactive modes) with hardware-write detection, protocol-agnostic integration with control stacks (EPICS, LabVIEW, Tango), intelligent logbook search across facility electronic logbooks, and mandatory human oversight for safety-critical operations.
Osprey provides agentic orchestration with human-in-the-loop safety review, translating natural language requests into approved, isolated execution on facility control systems. For a detailed view of the pipeline workflow and component interactions, see Understanding Osprey.#
Key Features#
Dual-Mode Orchestration: Plan-first and reactive (ReAct) execution modes — create complete plans upfront or decide one step at a time — with operator review, explicit dependencies, and full audit trails
Control-System Awareness: Pattern detection and static analysis identify hardware writes; PV boundary checking validates setpoints against facility-defined limits before execution
Protocol-Agnostic Integration: Pluggable connectors for EPICS, LabVIEW, Tango, and mock environments enable development without hardware and seamless production migration through configuration
Scalable Capability Management: Dynamic classification selects relevant capabilities from large inventories, preventing prompt explosion as facilities expand toolsets
Secure Code Execution: Containerized Python generation and execution with read-only and write-enabled environments, static analysis, and mandatory approval for hardware-interacting scripts
Facility Data Integration: Automatic retrieval from archiver appliances, channel databases, and knowledge bases with intelligent downsampling for large time-series datasets
Logbook Search (ARIEL): Intelligent search over facility electronic logbooks with keyword, semantic, RAG, and agentic retrieval modes, pluggable ingestion adapters for any facility, and a built-in web interface
LangGraph Foundation: Native StateGraph workflows with checkpoints, interrupts, and persistent state management
Safety-First Design: Transparent execution plans with human approval workflows and network-level isolation for control room deployment
Proven in Production: Deployed at Lawrence Berkeley National Laboratory’s Advanced Light Source managing tens of thousands of control channels across accelerator operations
Documentation Structure#
Complete implementation guide from environment setup to production deployment, including tutorial applications.
Architectural concepts and implementation patterns for deploying agentic AI in control system environments.
Complete technical reference for all framework components and interfaces.
Reference implementations demonstrating framework usage across different domains.
Framework internals, development guidelines, and contribution workflows.
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},
}