A Production-Ready Framework for Building Composable AI Agents
Build powerful, modular, and maintainable AI agent applications with ease.

Docs  ·  Quick Start  ·  Examples  ·  中文

---

What is Alphora?

Alphora is a full-stack framework for building production AI agents. It provides everything you need — agent orchestration, tool execution, memory management, secure code sandbox, skills ecosystem, streaming, and deployment — all with an async-first, OpenAI-compatible design.

from alphora.agent import SkillAgent
from alphora.models import OpenAILike
from alphora.sandbox import Sandbox

agent = SkillAgent(
    llm=OpenAILike(model_name="gpt-4"),
    skill_paths=["./skills"],
    sandbox=Sandbox(runtime="docker"),
    system_prompt="You are a data analyst. Explore data before coding.",
)

result = await agent.run("Analyze sales.xlsx and find the top-performing regions.")

Installation

pip install alphora

---

Features

• ReAct & Plan-Execute — Built-in reasoning-action loops with automatic tool orchestration, retry logic, and iteration control. Plan first, then execute.
• Agent Derivation — Child agents inherit LLM, memory, and config from parents via derive(). Build hierarchies that share context efficiently.
• Zero-Config Tools — @tool decorator auto-generates OpenAI function calling schema from type hints and docstrings. Pydantic V2 validation, parallel execution, instance method support.
• Smart Memory — Multi-session isolation with composable processor pipeline (keep_last, token_budget, summarize, etc.), pin/tag system, and undo/redo.
• Code Sandbox — Run agent-generated code in Local / Docker / Remote Docker environments with file isolation, package management, and security policies.
• Skills Ecosystem — agentskills.io compatible. 3-phase progressive loading (metadata → instructions → resources) to optimize token budget.
• Typed Streaming — Native async SSE with content types (char, think, result, sql, chart) so frontends can render each type differently.
• Prompt Engine — Jinja2 templates, ParallelPrompt for concurrent execution, and auto long-text continuation to bypass token limits.
• Unified Hooks — One event system across tools, memory, LLM, sandbox, and agent lifecycle. Fail-open by default, with priority, timeout, and error policy controls.
• Multi-Model Support — Works with any OpenAI-compatible API (GPT, Claude, Qwen, DeepSeek, local models). Multimodal input (text, image, audio, video).
• LLM Load Balancing — Combine multiple backends with llm1 + llm2 for automatic round-robin / random load balancing and failover.
• Thinking Mode — First-class support for reasoning models with separate thinking / content streams.
• One-Line Deploy — publish_agent_api(agent) serves any agent as an OpenAI-compatible REST API with built-in session management and SSE streaming.
• Debug Tracing — Built-in visual debugger for agent execution flow, LLM calls, and tool invocations.

---

Quick Start

1. Agent with Tools

from alphora.agent import ReActAgent
from alphora.models import OpenAILike
from alphora.tools import tool

@tool
def get_weather(city: str, unit: str = "celsius") -> str:
    """Get current weather for a city."""
    return f"Weather in {city}: 22°{unit[0].upper()}, Sunny"

agent = ReActAgent(
    llm=OpenAILike(model_name="gpt-4"),
    tools=[get_weather],
    system_prompt="You are a helpful assistant.",
)

result = await agent.run("What's the weather in Tokyo?")

2. Code Sandbox

Run agent-generated code in an isolated Docker container. The image is built automatically on first use. See the Sandbox docs for Docker build, remote Docker, and TLS configuration.

from alphora.sandbox import Sandbox

async with Sandbox(runtime="docker", workspace_root="/data/workspace") as sandbox:
    result = await sandbox.execute_code("print(6 * 7)")
    print(result.stdout)  # 42

    await sandbox.write_file("outputs/result.txt", "done")
    files = await sandbox.list_files()

3. Deploy as API

Publish any agent as an OpenAI-compatible REST API in one line:

from alphora.server.quick_api import publish_agent_api

app = publish_agent_api(agent)
# uvicorn main:app --port 8000

curl -X POST http://localhost:8000/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello!"}], "stream": true}'

---

Examples

Example	Description
ChatExcel	Data analysis agent with skill-driven workflow and sandbox code execution
Deep Research	Multi-step research agent with web search and report generation

---

Configuration

export LLM_API_KEY="your-api-key"
export LLM_BASE_URL="https://api.openai.com/v1"
export DEFAULT_LLM="gpt-4"

# Optional
export EMBEDDING_API_KEY="your-key"
export EMBEDDING_BASE_URL="https://api.openai.com/v1"

---

Documentation

For detailed system design, component relationships, and implementation patterns, see the Architecture Guide.

Component Overview

Component	Description
Agent	Core agent lifecycle, derivation, ReAct loop
Prompter	Jinja2 templates, LLM invocation, streaming
Models	LLM interface, multimodal, load balancing
Tools	tool decorator, registry, parallel execution
Memory	Session management, history, pin/tag system
Storage	Persistent backends (memory, JSON, SQLite)
Sandbox	Secure code execution, local/Docker/remote
Skills	agentskills.io compatible, SkillAgent integration
Hooks	Extension & governance via unified hook events
Server	API publishing, SSE streaming
Postprocess	Stream transformation pipeline

---

Contributors

Crafted by the AlphaData Team.

Tian Tian Project Lead & Core Dev 📧	Yuhang Liang Developer 📧	Jianhui Shi Developer 📧	Yingdi Liu Developer 📧	Qiuyang He Developer -
LiuJX Developer -	Cjdddd Developer 📧	Weiyu Wang Developer 📧

License

This project is licensed under the Apache License 2.0.
See LICENSE for details.

Contributions require acceptance of the Contributor License Agreement (CLA).