A Python frameworkfor state-graph agents.
Alcyoneus OS is a Python framework for composing LLM-enabled and tool-using agents as explicit state-graph workflows. The package includes graph execution, optional persistence, policy and guardrail components, streaming, and integration adapters.
Reported test result, pinned to its release snapshot.
3,159 passed · 13 skipped · 31 warnings · GitHub v1.1.0
A full local pytest run of the v1.1.0 tag checkout under Python 3.12.3 reported 3,172 collected tests with 3,159 passed, 13 skipped, and 31 warnings. The source package declared version 1.1.0 at that tag; GitHub now publishes v1.2.0 and PyPI currently lists v1.2.0 (Apache-2.0). The run result is reported, not independently reproduced.
Reported full run at the v1.1.0 tag; not a v1.2.0 result
Tests collected in the reported local run at v1.1.0
Test-like Python source files under the v1.1.0 audit predicate; not a test count
Project-documented areas; not independent certification
Latest public source release; v1.1.0 tag holds the reported run state
Current published package (Apache-2.0)
GitHub repo, PyPI, and HEAD; v1.1.0 README stated MIT
Integration surfaces documented by the framework
EVIDENCE_NOTE:: The reported pytest run is from the v1.1.0 tagged checkout, not the current v1.2.0 release. It is not a CI result, was not independently reproduced in this portfolio review, and does not establish production reliability.
v1.2.0 is a published Python package release. This case study describes source components, not a production deployment or independent security validation. Optional integrations require their dependencies, credentials, infrastructure, and application-level configuration. PyPI currently shows no provenance attestation for the v1.2.0 files.
Agent control flow should be explicit in code.
Agent applications need explicit state, controlled transitions, recovery choices, tool permissions, and execution signals. Alcyoneus OS provides framework components for these concerns; each application still chooses and configures the pieces it uses.
Keep state, routing, and execution controls explicit.
A graph makes control flow inspectable: state moves through named nodes and edges, with conditional routing and optional tool calls. Checkpointing, policy, telemetry, and external protocol adapters attach at explicit boundaries rather than being implied by the graph alone.
Define the graph. Configure its runtime. Follow each transition.
This architecture view follows the Python graph API and compiled runtime. Stores, policies, model providers, and protocols are optional integrations; a workflow uses only the pieces its application configures.
Pydantic state, Python node functions, edges, conditional routes, and optional subgraphs or handoffs.
Validates the graph and accepts optional checkpointer, store, media, interrupt, and callback configuration.
Runs through invoke/async paths or streams graph events, depending on the caller.
Initial state and optional thread/config values enter the compiled graph.
A node updates state; an Agent node may call its configured model provider.
Application routing chooses the next node, a tool path, a handoff, or an end route.
When routed there, ToolNode runs selected tools and returns results to graph state for the next transition.
Not every graph uses an LLM or ToolNode. A tool may run in-process or through a configured backend; the graph API alone does not isolate it.
Agent calls pass through an adapter to a configured local or hosted model service.
Opt-in. Restart durability depends on selecting and configuring a persistent backend.
Components are available; applications must attach them to exposed actions.
Streaming and telemetry need a caller and, for exporters, configured services.
MCP, A2A, and ACP are separate interfaces that require their own setup.
A tool call follows graph edges, not hidden prompt logic.
The repository's examples/react/react_sync.py shows an Agent node, a conditional route, a ToolNode, and an explicit return edge. The graph is compiled and then invoked with a thread ID and recursion limit.
The Agent node receives conversation state and may return a tool call.
A conditional function sends tool calls to TOOL; a normal response follows the graph's end route.
ToolNode runs the selected Python tool and appends its result to workflow state.
An edge sends TOOL back to MAIN so the Agent can continue with the tool result.
The example compiles with InMemoryCheckpointer, then invokes with a thread_id and recursion limit.
Scope of this example: it uses an in-memory checkpointer, so it does not demonstrate restart-durable recovery. Its sample weather function returns hard-coded text; it is not a live weather integration. The route function also has a MAIN return branch that is absent from the shown path map, so confirm that branch before relying on the example unchanged.
The system beneath the agent.
A programmable execution model
StateGraph, MessageGraph, nodes, edges, conditional routing, subgraphs, compiled graphs, remote graph serving, and inline Command routing define an inspectable execution path. Persistence and runtime controls are attached when configured.
Prebuilt patterns for real work
The package includes ReactAgent, RAGAgent, SwarmAgent, SupervisorTeamAgent, PlanActReflectAgent, RouterAgent, StructuredOutputAgent, AudioAgent, handoffs, and dynamic prompts. Providers, dependencies, and external services still need configuration.
Provider choice without graph rewrites
Adapters cover OpenAI and Responses, Google Gemini and Vertex AI, Anthropic, LiteLLM, and AnyLLM. Retry and fallback behavior is available through the configured provider path; credentials, network access, and provider limits remain external dependencies.
Tools with bounded capability
The package contains tool implementations and extension points for search, browser, shell, code, files, image generation, calendars, schedulers, subagents, memory, and computer use. Execution boundaries vary by tool and selected backend.
From working context to durable memory
Graph checkpoints have in-memory, SQLite, and PostgreSQL implementations. Separate stores and optional integrations cover Qdrant and Mem0 retrieval; durability and namespace behavior depend on the selected backend and configuration.
Text, audio, image, and live interaction
Streaming events, SSE heartbeats, response granularity, Gemini Live, OpenAI Realtime, Azure Realtime, local Whisper plus TTS, barge-in, WebRTC frame broadcast, media storage, and resolver policies cover interactive products.
Capabilities are useful only when the boundary is explicit.
Alcyoneus provides components for separating model output from tool execution. Guardrails, policy decisions, identity, secrets, and tenant scope affect runtime behavior only when the application configures and connects them to its graph and exposed actions.
Input components include PII and prompt-injection checks, length limits, validators, and tripwires; an application must call them on its request path.
Output components include schema checks, blocked-word checks, length limits, and tripwires; they constrain results when the application wires them into execution.
Tool input/output guardrails can apply allow, deny, ask-user, validation, and rate-limit decisions where those hooks are configured.
A nine-priority policy engine provides allow, deny, ask-user, tenant-scope, workspace-only, and confirmation rules; applications must connect policies to the actions they expose.
The framework includes RBAC, tenant, JWT/JWKS, mTLS, RFC 7662 introspection, API-key, and protocol-auth components. A deployment must configure and apply the relevant middleware and identity provider.
Vault and cloud key-vault integrations plus a composite provider are available; secret access policy and deployment configuration remain the application's responsibility.
One runtime, several ways to connect.
Sandbox strength depends on the selected backend.
The package includes local, container, cluster, and micro-VM adapters, but the graph does not isolate a tool automatically. Effective isolation depends on backend configuration, host privileges, mounts, credentials, and the code path the tool uses.
Container and pod backends are present; actual isolation depends on daemon or cluster configuration, privileges, mounts, and resource limits.
A micro-VM adapter is included, but it requires a compatible host and configured hypervisor environment.
Runs a process on the host. A PTY provides process control, not a security boundary against hostile code.
Several provider adapters are conditional integrations. Some missing-configuration paths return synthetic success output instead of executing remotely; verify the real service path before use.
X11, Wayland, headless, VNC, remote-desktop, and accessibility integrations require the matching display/session backend and permissions.
In the v1.2.0 source, several remote sandbox adapter fallback branches return exit_code=0 with synthetic output when the real client or configuration is unavailable. That fallback is not remote execution. Treat those adapters as unverified until checked against the configured service.
The operational loop is part of the framework.
OpenTelemetry decorators for graphs, nodes, LLM calls, tools, guardrails, handoffs, tasks, and custom spans; Prometheus metrics for requests, latency, tokens, errors, and sessions; structured JSON logs with W3C trace propagation.
The alc CLI creates, runs, validates, visualizes, debugs, replays, traces, lists, and tests graphs and tools, with Mermaid, Graphviz, and interactive HTML output for architecture review.
QuickTest, TestAgent, MockLLM, MockToolRegistry, MockMCPClient, TestContext, AgentEvaluator, factual accuracy, hallucination, safety, trajectory, rubric, and simulator-based evaluation make behavior measurable.
Seventeen areas in the project hardening record.
This is the project's own hardening record. It is not an independent security audit, certification, or proof that every deployment configuration has been validated.