Osprey Framework Documentation#
🚧 Early Access Documentation
Current Release: v0.10.6 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 execution plans 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, plan-first orchestration with hardware-write detection, protocol-agnostic integration with control stacks (EPICS, LabVIEW, Tango), 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#
Plan-First Orchestration: Complete execution planning with explicit dependencies before any hardware interaction, enabling operator review of all proposed control system operations
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
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 hundreds 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:
@misc{hellert2025osprey,
title={Osprey: A Scalable Framework for the Orchestration of Agentic Systems},
author={Thorsten Hellert and João Montenegro and Antonin Sulc},
year={2025},
eprint={2508.15066},
archivePrefix={arXiv},
primaryClass={cs.MA},
url={https://arxiv.org/abs/2508.15066},
}