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

# Optional extras
pip install "alphora[mcp]"   # MCP tool integration
pip install "alphora[cli]"   # Terminal rich split-pane rendering

For concurrent production APIs, use alphora >= 1.3.3 (fixes request-scoped config / sandbox isolation).

---

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(). Gateways can spawn orchestrators, specialists, or fast-path agents per request (see Production Reference).
• 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_tool_calls, 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). Pair with ToolCallStreamRenderPP to render tool calls as frontend-friendly SSE chunks.
• 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-Agent Collab — AgentCollabScope + TaggedCallback tag parallel child-agent streams for rich frontends.
• MCP Integration — pip install "alphora[mcp]" then setup_mcp(servers=[...]) for stdio / SSE / HTTP MCP servers.
• 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 round-robin or random dispatch.
• Thinking Mode — First-class support for reasoning models with separate thinking / content streams.
• One-Line Deploy — publish_agent_api(agent, method=...) serves any agent as an OpenAI-compatible REST API with session management and SSE streaming.
• Web UI — Built-in AgentChat frontend via alphora-web (default http://localhost:8813).
• Debug Tracing — Visual debugger with debugger=True at http://localhost:9527 (experimental); MessageInspector for lightweight HTML traces in production.

---

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. method is the async method on your agent that accepts OpenAIRequest (see examples/api_mock):

from alphora.server.quick_api import publish_agent_api, APIPublisherConfig

config = APIPublisherConfig(path="/v1")
app = publish_agent_api(agent, method="start", config=config)
# uvicorn main:app --port 8000

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

Common production paths: default path="/alphadata" → /alphadata/chat/completions; set sandbox_workspace to enable the built-in file browser API. OpenAIRequest accepts extra fields (e.g. mode) via model_extra for app-level routing.

4. Web UI

Launch the bundled AgentChat frontend (point it at your backend from §3):

alphora-web
# Open http://localhost:8813 — set API Path to match your backend (e.g. /alphadata/chat/completions)

---

Examples

Example	Description
ChatExcel	SkillAgent + Sandbox data analysis — framework essentials
Deep Research	Multi-step research agent with web search and report generation
api_mock	Minimal publish_agent_api for frontend integration

---

Production Reference

For production apps, use a gateway agent that handles per-request sandbox setup and spawns child agents via derive():

from alphora.agent import BaseAgent
from alphora.server.openai_request_body import OpenAIRequest
from alphora.server.quick_api import publish_agent_api, APIPublisherConfig

class AppGateway(BaseAgent):
    async def serve(self, request: OpenAIRequest):
        sandbox = await self.create_sandbox(session_id=request.session_id, runtime="docker")
        self.update_config("sandbox", sandbox)
        orchestrator = self.derive(OrchestratorAgent)
        await orchestrator.run(request=request)
        await sandbox.destroy()

app = publish_agent_api(
    AppGateway(),
    method="serve",
    config=APIPublisherConfig(path="/alphadata/v1/", sandbox_workspace="/data/sandbox"),
)

AlphaData Core builds on this pattern with:

• Orchestrator + specialist registry + call_specialist with isolated context
• app.include_router(...) for Skills, MCP, files, and other business REST APIs
• Extended SSE protocol (task_graph, tool_call, usage, etc.)

---

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_URL="https://api.openai.com/v1"
export EMBEDDING_MODEL="text-embedding-3-small"

The framework reads env vars above for quick starts. Large deployments may use YAML profiles instead (see AlphaData Core configs/README.md).

---

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
MCP	MCP client integration via setup_mcp()
Web	AgentChat frontend and alphora-web CLI

---

Contributors

Crafted by the AlphaData Team.

Tian Tian Project Lead & Core Dev 📧

Yuhang Liang Developer 📧

Jianhui Shi Developer 📧

Yingdi Liu 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).