Osprey Framework Documentation#
🚧 Early Access Documentation
Current Release: v0.9.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 provides a production-ready architecture for building domain-specific agentic systems. Built on LangGraph’s StateGraph foundation, it implements a structured pipeline that transforms natural language inputs into reliable, orchestrated execution plans.
The framework addresses common challenges in agentic system development: tool management at scale, structured orchestration without hallucination, and seamless integration of human oversight workflows.
Core Architecture#
Our framework provides a domain-agnostic architecture for safety-critical systems, turning natural-language requests into reliable action through a four-stage pipeline—Task Extraction, Classification, Orchestration, and Execution with checkpointing and artifact tracking:
Task Extraction → Convert conversational context into structured, actionable objectives
Classification → Dynamically select relevant capabilities from your domain-specific toolkit
Orchestration → Generate complete execution plans with explicit dependencies and human oversight
Execution → Execute capabilities with checkpointing, artifact management, and safety controls
Production Deployment Example: This diagram illustrates the framework architecture using capabilities from the ALS Accelerator Assistant - our production deployment at Lawrence Berkeley National Laboratory’s Advanced Light Source particle accelerator.#
The framework provides:
Capability-Based Architecture: Modular agent construction with selective capability activation based on task requirements
Orchestrator-First Design: Complete execution planning prior to capability invocation, eliminating iterative tool-calling patterns
Secure Python Execution: Containerized code generation and execution with static analysis, human approval, and flexible deployment environments
Registry-Based Discovery: Convention-driven component loading enables seamless integration of capabilities, data sources, and services across applications
Control System Abstraction: Pluggable connectors for control systems (EPICS, LabVIEW, Tango, Mock) enable development without hardware and seamless migration to production through configuration
External Data Integration: Automatic retrieval from databases and knowledge bases during task understanding and capability execution for data-driven responses
LangGraph Integration: Native StateGraph workflows with checkpoints, interrupts, and persistent state management
Human-in-the-Loop Integration: Transparent execution plans with approval workflows for high-stakes operational environments
Domain Abstraction: Framework patterns applicable across diverse infrastructure, from simple agents to complex production control systems
Documentation Structure#
Complete implementation guide from environment setup to production deployment, including tutorial applications.
Architectural concepts and implementation patterns for building sophisticated agentic systems.
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},
}