OrionAgent

The Sovereign Multi-Agent Orchestration Framework

Overview

OrionAgent is a cutting-edge multi-agent orchestration framework designed to democratize professional-grade agentic workflows. Powered by the Orion Engine—a smart conversational core featuring Multi-Provider LLM Support (OpenAI, Gemini, Anthropic, Ollama)—OrionAgent offers real-time, actionable task execution for industrial-scale projects.

Whether you are building complex research swarms or precision-driven automation pipelines, the Orion Agent acts as your 24/7 technical companion, ensuring every output is persistent and token-efficient.

---

Philosophy

OrionAgent is designed to eliminate the black box complexity of modern agent frameworks. It provides a low-abstraction, high-control environment for building agents that are token-efficient (via Clean Brain context pruning) and persistent by default.

---

Installation

Install OrionAgent via pip for immediate industrial-grade orchestration:

pip install orionagent

To update to the latest version:

pip install --upgrade orionagent

Development Setup

If you are cloning the repository to run examples or contribute, install in editable mode to ensure all local resources are correctly mapped:

git clone https://github.com/Sam-Dev-AI/OrionAgent.git
cd OrionAgent
pip install -e .

To update the framework with the latest changes from the repository:

git pull
pip install --upgrade .

---

Quick Start

Single Agent Integration

The Agent class provides a high-performance worker unit with integrated persistence and tool access.

from orionagent import Agent, Gemini, tool

@tool
def crypto_ticker(symbol: str):
    """Fetches real-time prices for crypto assets."""
    return f"Current {symbol} Price: $65,000"

agent = Agent(
    name="Vanguard",
    role="Research Analyst",
    model=Gemini("gemini-2.5-flash", verbose=True),
    memory="long_term",          # Automatic SQLite Knowledge Storage
    use_default_tools=True,      # Integrated Web, File, and OS tools
    tools=[crypto_ticker],
    temperature=0.7,             # Model Creativity Control
)

agent.chat("Analyze the current BTC trend.")

Multi-Agent Orchestration

The Manager coordinates specialized agents through recursive strategy loops.

from orionagent import Agent, Manager, Gemini

# 1. Define Model (Configure logging here)
llm = Gemini("gemini-2.5-flash", debug=True, verbose=True)

# 2. Define Specialized Agents
researcher = Agent(
    name="Researcher",
    role="Technical Scraper",
    system_instruction="Focus on deep technical data sets.",
    use_default_tools=True
)

writer = Agent(
    name="Writer",
    role="Content Strategist",
    system_instruction="Synthesize complex data into premium reports."
)

# 3. Link via Manager (Task Orchestrator)
manager = Manager(
    model=llm,
    agents=[researcher, writer],
    strategy="planning",           # Enable Structured Behavior Lock
)

# OrionAgent automatically detects task complexity.
# Simple greetings skip planning, while complex research triggers orchestration.
manager.chat("Research Gemini 1.5 Pro features and summarize why they matter.")

---

Core Configuration & Architecture

OrionAgent utilizes a granular, declarative configuration system built for industrial-scale reliability. Below is a deep dive into the core execution variables that power the framework.

1. Memory Levels (memory)

OrionAgent uses a Tiered Logic Engine to scale context. Select your ecosystem power level:

Level	Mode	Behavior	Power
1	none	No memory. Static responses only.	Static
2	session	Fast temporary conversation buffer.	Medium
3	long_term	Session + Persistent SQLite (Fact Recall).	High
4	chroma	Session + SQLite + Vector Knowledge (Semantic RAG).	Ultimate

# Initialize an agent with the 'Ultimate' level
from orionagent import Agent
agent = Agent(memory="chroma")

# Advanced configuration
from orionagent import MemoryConfig
agent = Agent(
    memory=MemoryConfig(
        mode="chroma",
        priority="high",            # Depth: 'low', 'medium', or 'high'
        extract_entities=True,      # Enable Knowledge Extraction
        importance_threshold=7      # Sync threshold (1-10)
    )
)

• Semantic Memory (Chroma): Level 4 allows for industrial-scale knowledge persistence using vector embeddings, enabling high-quality RAG.
• Structured Knowledge Vault: Automatically extracts facts (Names, Roles, Decisions) into a JSON schema, ensuring 100% accuracy.
• Priority Tiers: Control how deep the extraction goes with low (token-saving), medium (balanced), and high (exhaustive) tiers.

2. Strategic Orchestration (strategy)

The Manager employs recursive strategy loops to decompose and execute complex goals.

manager = Manager(
    agents=[researcher, analyst],
    strategy=["planning", "self_learn"], # Chain multiple strategies
    max_refinements=2,                   # Self-correction limit
    hitl=True                            # Enable Human-in-the-Loop Safety gate
)

• planning: Decomposes a goal into a roadmap of parallel tasks.
• self_learn: Executes the Verdict Loop—evaluating results and re-delegating with corrected context if quality fails.
• hitl (Safety Gate): When True, the Manager pauses for terminal approval (y/n).

Granular Safety Levels:

from orionagent import HitlConfig
manager = Manager(
    agents=[...],
    hitl=HitlConfig(
        permission_level="medium", # Ask only for risky tasks (delete, shell, etc.)
        ask_once=True,             # Single approval for complex plans
        plan_review=True           # Show full task breakdown
    )
)

Level	Behavior
low	Always asks for approval (Default if hitl=True).
medium	Asks only for high-impact actions (Risk-based).
high	Complete autonomy (Default if hitl=False).

3. Smart Strategy Radar (Planning Threshold)

OrionAgent uses a hybrid routing engine to balance intelligence and cost. Simple conversational tasks automatically bypass expensive orchestration.

Threshold Logic: OrionAgent employs Dynamic Intent Analysis. Instead of static word counts, a lightweight LLM call analyzes the task's complexity to decide the optimal execution path.

• Mode 1: Bypass: Simple tasks (greetings, one-shot questions) $\rightarrow$ Fast Direct Routing.
• Mode 2: Advanced: Complex, multi-step goals $\rightarrow$ Strategic Planning Triggered.

Complexity Keywords (Reference): research, browser, analyze, compare, summary, outline, first, then, finally, steps, plan, extract, find all.

4. High-Performance Execution Engine

OrionAgent is engineered for zero-latency. Control core performance variables directly:

• python_sandbox (New): An industrial-grade Dynamic Reasoning Engine. It executes complex Python logic in RAM ("Ghost Scripts") to verify math, process data, or run simulations without creating temporary files.

# 1. Enable token usage tracking and set logging (Industrial Logs)
llm = Gemini(model_name="gemini-2.5-flash", token_count=True, temperature=0.7, debug=True)

# 2. Control execution speed and streaming
agent = Agent(
    model=llm,
    async_mode=True, # Enable parallel tool calls & strategy steps
    temperature=0.3  # Override model default for this specific agent
)

# 3. Request-level override
agent.ask("What is the speed of light?", temperature=0.0)

• token_count=True: Tracks input/output tokens for precise cost monitoring.
• async_mode=True: Executes independent tasks in parallel (up to 60% faster).
• debug=True: Enables live [AGENT], [MEMORY], and [TOOL] : 1 tags in terminal.

---

Detailed Performance Usage

Professional Logging & Observability

OrionAgent offers two tiers of visibility:

1. Industrial Logs (debug=True): Real-time analysis (tags like [TOOL], [PLAN]). Use this to watch agents think and work live.
2. Trace Summary (verbose=True): Post-execution breakdown. Use this for clean, professional reports of timing and token usage.

# NEW Pattern: Enable logging on the LLM provider
llm = Gemini(model_name="gemini-2.5-flash", debug=True, verbose=True)

# Manager and Agents automatically use the provider's logic
manager = Manager(model=llm, agents=[...])
agent = Agent(name="Sentry", model=llm)

Concurrent Orchestration

OrionAgent leverages parallel orchestration to maximize throughput. When async_mode is active, the Manager executes independent task groups simultaneously.

# Explicitly control concurrency (Default: True)
manager = Manager(
    agents=[researcher, coder],
    async_mode=True 
)

• Parallel Tooling: If an agent needs to call 3 tools (e.g., searching 3 different sources), it will execute them in parallel, returning the results in the time of the single slowest call.
• Parallel Strategy: The planning strategy automatically groups tasks that don't depend on each other for simultaneous execution.

---

5. System-Level Token Optimization

OrionAgent minimizes operational overhead by pruning unnecessary context and optimizing prompt density:

• Sliding Window Session Memory: Automatically manages conversation history to prevent context window saturation and rising latency.
• Structured Entity Summarization: Replaces heavy text summaries with lean, categorized fact lists, reducing per-turn token usage by up to 85%.
• Hierarchical Knowledge Sync: Instead of feeding raw history, the long_term tier distills facts into an optimized SQLite DB, ensuring only relevant data is injected into the prompt.
• Priority-Driven Summarizer: Use low priority for casual chats to save tokens with minimalist one-sentence summaries.
• Compact Planning Prompt: The Strategy engine uses a specialized, ultra-lean prompt (~100 tokens) to decompose tasks, ensuring that the heavy lifting is done with minimal structural baggage.
• Precision Tool Routing: Agents only receive the context relevant to the specific step they are executing, preventing "prompt pollution" from unrelated task phases.

Production Multi-User Orchestration

OrionAgent is built for horizontal scale. Use the user_id parameter to maintain isolated memory for thousands of concurrent users on a single server instance.

# Multi-user session isolation in Flask/FastAPI
response = manager.ask(user_prompt, user_id=current_user_id)

• Session Scoping: Automatically routes all memory (SQLite/JSON) to agent_memory/sessions/{user_id}/.
• Stateless Safety: Ensures zero "context leakage" between user requests.

Knowledge Base Integration (RAG)

Teach your agent to read local PDFs and Markdown files for private knowledge retrieval.

from orionagent import Agent, Gemini

# Initialize with a knowledge collection
agent = Agent(
    name="Researcher",
    model=Gemini("gemini-2.0-flash"),
    knowledge="corporate_docs" # Creates a persistent index
)

# 1. Ingest content (Manual, File, or Raw Text)
agent.ask("Please read compliance_2024.pdf")
agent.ask("Ingest this raw documentation: [Detailed Protocol Specs...]")

# 2. Query it
answer = agent.ask("What are the new security protocols for 2024?")
print(answer)

---

Architecture Blueprints

Decoupled execution architecture for zero-latency orchestration.

       ┌───────────────────────────────┐
       │      USER MISSION / GOAL      │
       └──────────────┬────────────────┘
                      │
              ┌───────▼───────┐        ┌──────────────────────────┐
              │    MANAGER    │◄──────▶│   STRATEGY ENGINE        │
              │ (Architect)   │        │ (Planning & Self-Learn)  │
              └───────┬───────┘        └──────────────────────────┘
                      │
              ┌───────▼───────┐        ┌──────────────────────────┐
              │    AGENT      │───────▶│    MEMORY CORE           │
              │ (Worker)      │        │ (Hierarchical SQLite)    │
              └───────────────┘        └──────────────────────────┘

---

Memory Architecture & Patterns

Managed through a Hierarchical 3-Tier Synchronizer, OrionAgent maintains state across thousands of interactions without context saturation, enabling seamless multi-agent collaboration.

The 3-Tier Multi-Agent Memory

Tier	Owner	Storage	Purpose
Global Memory	Manager	SQLite + JSON	Cross-agent knowledge hub (in agent_memory/).
Local Memory	Each Agent	Session buffer (JSON)	Isolated chat logs (in agent_memory/sessions/).
Shared Memory	Optional	ChromaDB (Vector)	Semantic RAG (in agent_memory/knowledge/).

Data Synchronization Flow (The Memory Engine)

graph TD
    User([User Signal]) --> Sync{Manager: Global Hub}
    
    subgraph Multi-Agent Swarm
        Sync -- 1. Record Result --> SQL[(SQLite Global Vault)]
        Sync -- 2. Inject Context --> AgentA[Agent A: Local Memory]
        Sync -- 2. Inject Context --> AgentB[Agent B: Local Memory]
    end
    
    subgraph Shared Level: Ultimate
        AgentA -- Query --> Chroma[(Chroma Vector DB)]
        AgentB -- Query --> Chroma
    end
    
    SQL -- Recall --> Hub[Intelligence Hub]
    Hub --> Final[Orchestrated Output]

State Storage Metrics

• Global Knowledge Briefing: The Manager builds a condensed summary (entities, summaries, history) from the Global Memory vault, injecting it as ### GLOBAL CONTEXT ### into every agent delegation.
• Isolated Local Context: Agents retain their own conversation buffers (Local Memory) so that task-specific details don't pollute the global state unless necessary.
• Semantic Recall (Chroma): Level 4 memory enables RAG-as-a-Service, where all swarm agents can query a shared knowledge base (Shared Memory).

---

---

Framework Comparison

Metric	OrionAgent	LangChain	AutoGen
Abstraction	Minimalist	Heavy	Moderate
Logic Control	Internal Safeguards	Custom Parsers	Limited
Memory	Native SQLite Briefing	Manual Pipeline	Basic Session
Setup Cost	Zero-Config	High Integration	Moderate

---

Contributing & Community

OrionAgent is an open ecosystem. We value contributions that maintain the framework's minimalistic core.

• Reporting Bugs: Use the GitHub Issue Tracker.
• Feature Requests: Open a Discussion thread for architectural review.
• Pull Requests: Ensure all new tools follow the @tool schema validation protocol.

---

Support & Roadmap

If you find OrionAgent valuable, consider starring the repository to support its development.

• Vitals Dashboard: Real-time telemetry Web UI.
• Human-in-the-Loop: Interactive approval gates for critical tool calls.
• Async Multi-Clusters: Parallelized strategy execution across processes.

---

License & Contact