Skip to content

AIXP-Foundation/SoulBot

BranchesTags

Repository files navigation

SoulBot

AI Agent Framework with AISOP Protocol and AIAP Package System

Python 3.11+ License Tests

中文文档 | English

What is SoulBot?

SoulBot is a Python-based AI Agent framework that connects to LLMs through CLI subprocesses (ACP protocol) — no API keys required. It introduces a unique architecture where agent behavior is defined by AISOP blueprints (.aisop.json) and extended through AIAP packages (*_aiap), making AI agent behavior deterministic, reproducible, and version-controlled.

Key Features

  • No API Key Required — Connects to LLMs via Claude Code / Gemini CLI / OpenCode CLI subprocesses
  • Multi-Model Switching — Claude, Gemini, OpenCode (Kimi, etc.) — switch with one line in .env
  • AISOP-Driven — Agent behavior defined by .aisop.json blueprints with mermaid flowcharts as deterministic execution paths
  • AIAP Package System — Hot-pluggable capability packages (*_aiap) that extend agent functionality
  • Agent Composition — Single agent, multi-agent routing, Sequential / Parallel / Loop workflows
  • Tool System — Python functions auto-wrapped as LLM-callable tools
  • Multi-Channel — Terminal CLI, Web Dev UI, Telegram Bot
  • Streaming Output — SSE typewriter effect (Web + Telegram)

Quick Start

Prerequisites

  • Python 3.11+
  • At least one LLM CLI tool installed:
Tool Install Login
Claude Code npm install -g @anthropic-ai/claude-code claude login
Gemini CLI npm install -g @google/gemini-cli gemini login
OpenCode npm install -g opencode Free models, no login needed

Install

git clone https://github.com/AIXP-Foundation/SoulBot.git
cd SoulBot
pip install -e .

Run

# Web Dev UI (open http://127.0.0.1:8000)
soulbot web --agents-dir examples/simple

# Terminal interactive mode
soulbot run examples/simple/SoulBot_Agent

# Telegram Bot
soulbot telegram examples/simple/SoulBot_Agent

Create Your Own Agent

soulbot create my_agent

This generates:

my_agent/
├── agent.py          # Agent definition (AISOP Runtime)
├── main.aisop.json   # AISOP blueprint (intent routing)
├── .env              # Configuration (model selection)
└── aiap/             # AIAP package directory
    └── README.md

Edit .env to select your LLM backend, then run:

soulbot run my_agent

Architecture

AISOP + AIAP

SoulBot introduces two core concepts:

Concept Description
AISOP V1.0.0 AI Standard Operating Procedure — a JSON-based blueprint protocol that defines agent behavior through mermaid flowcharts
AIAP Packages AI Application Packages — hot-pluggable capability modules (*_aiap/) with their own main.aisop.json entry points

The key insight: mermaid flowcharts serve as deterministic execution paths (like circuit diagrams), while prompts provide context and constraints (like component specifications). This separation makes agent behavior reproducible and version-controllable.

User Message
    ↓
agent.py → _dynamic_instruction()
    ├── _SYSTEM_PROMPT (WHO — runtime identity)
    ├── main.aisop.json (WHAT — routing rules)
    └── [Available AIAP packages] (capabilities)
    ↓
LLM follows mermaid flow:
    NLU[Match Intent] → Run[Load & Execute *_aiap/main.aisop.json]
    ↓
AIAP package's mermaid flow executes domain-specific logic
    ↓
Response returned to user

Governance Domains

AIAP operates under a tripartite federated trust model:

  • aisop.dev (Seed Layer): Defines the unchangeable format structure.
  • aiap.dev (Authority Layer): Defines the evolving governance rules.
  • soulbot.dev (Executor Layer): The reference runtime engine that physically acts upon AISOP code.

System Architecture

Entry Points
├── CLI Terminal     →  soulbot run <agent_dir>
├── Web Dev UI       →  soulbot web --agents-dir <dir>
├── API Server       →  soulbot api-server --agents-dir <dir>
└── Telegram Bot     →  soulbot telegram <agent_dir>
         ↓
Runner
├── Agent Tree       →  LlmAgent / SequentialAgent / ParallelAgent / LoopAgent
├── AISOP Engine     →  main.aisop.json → mermaid flow → AIAP routing
├── Tool Calls       →  FunctionTool / AgentTool / TransferToAgentTool
├── CMD System       →  Embedded commands (scheduling, etc.)
├── Sessions         →  InMemory / SQLite + State delta
├── EventBus         →  pub/sub + filtering + priority
└── Streaming        →  partial Events → SSE / Telegram typewriter
         ↓
Model Layer
├── ModelRegistry    →  regex matching → adapter selection
└── ACPLlm           →  CLI subprocess JSON-RPC
     ├── ClaudeACPClient    (claude-acp/*)
     ├── GeminiACPClient    (gemini-acp/*)
     ├── OpenCodeACPClient  (opencode-acp/*)
     └── OpenClawClient     (openclaw/*)

Agent Development

Minimal Agent

from soulbot.agents import LlmAgent

root_agent = LlmAgent(
    name="my_agent",
    model="claude-acp/sonnet",
    instruction="You are a helpful assistant.",
)

Agent with Tools

from soulbot.agents import LlmAgent

def get_weather(city: str) -> dict:
    """Get weather for a city."""
    return {"city": city, "temp": 25, "condition": "sunny"}

root_agent = LlmAgent(
    name="weather_agent",
    model="claude-acp/sonnet",
    instruction="You can check weather for any city.",
    tools=[get_weather],
)

Functions are auto-wrapped as LLM tools: function name becomes tool name, docstring becomes description, type hints become JSON Schema.

Multi-Agent Routing

from soulbot.agents import LlmAgent

billing = LlmAgent(name="billing", model="claude-acp/sonnet",
                    description="Handles billing questions",
                    instruction="You are a billing specialist.")

tech = LlmAgent(name="tech", model="claude-acp/sonnet",
                description="Handles technical issues",
                instruction="You are tech support.")

root_agent = LlmAgent(
    name="router",
    model="claude-acp/sonnet",
    instruction="Route user to the appropriate specialist.",
    sub_agents=[billing, tech],
)

Workflow Agents

from soulbot.agents import LlmAgent, SequentialAgent, ParallelAgent, LoopAgent

# Sequential: run agents in order
root_agent = SequentialAgent(name="pipeline", sub_agents=[analyzer, responder])

# Parallel: run agents concurrently
root_agent = ParallelAgent(name="parallel", sub_agents=[search, summarize])

# Loop: repeat until escalation
root_agent = LoopAgent(name="refiner", sub_agents=[draft, review], max_iterations=3)

Configuration

.env Reference

# LLM Backend (set one to true)
CLAUDE_CLI=true
GEMINI_CLI=false
OPENCODE_CLI=false
OPENCLAW_CLI=false

# Model names
CLAUDE_MODEL=claude-acp/sonnet
GEMINI_MODEL=gemini-acp/gemini-2.5-flash
OPENCODE_MODEL=opencode-acp/opencode/kimi-k2.5-free

# Behavior
WORKSPACE_DIR=aiap            # AIAP package directory
ENABLE_FALLBACK=false         # Auto-switch model on failure
AUTO_APPROVE_PERMISSIONS=true # Auto-approve CLI permissions
SHOW_THOUGHTS=false           # Show AI thinking process

# Telegram (optional)
TELEGRAM_BOT_TOKEN=

Model Name Formats

Format Description
claude-acp/sonnet Claude Sonnet
claude-acp/opus Claude Opus
gemini-acp/gemini-2.5-flash Gemini Flash
opencode-acp/opencode/kimi-k2.5-free OpenCode free Kimi
opencode-acp/anthropic/claude-sonnet-4-5 OpenCode → Claude
openclaw/default OpenClaw default

CLI Commands

Command Description
soulbot run <agent_path> Terminal interactive mode
soulbot web --agents-dir <dir> Web Dev UI + API Server
soulbot api-server --agents-dir <dir> API Server only (no UI)
soulbot telegram <agent_path> Telegram Bot
soulbot create <name> Scaffold a new agent project

python -m soulbot can be used instead of soulbot without installation.

Web Dev UI

soulbot web --agents-dir examples/simple
# Open http://127.0.0.1:8000

Features: Markdown rendering, SSE streaming, agent switching, session management, dark theme.

API Endpoints

Route Method Description
/health GET Health check
/list-apps GET List all agents
/apps/{name} GET Agent details
/run POST Synchronous execution
/run_sse POST SSE streaming execution

Telegram Bot

  1. Get a bot token from @BotFather
  2. Add TELEGRAM_BOT_TOKEN=your_token to .env
  3. Run: soulbot telegram examples/simple/SoulBot_Agent

Or run Web + Telegram together: soulbot web --agents-dir examples/simple

Bot commands: /start, /clear, /history

Features: streaming output, Markdown rendering, auto message splitting, multi-agent routing via InlineKeyboard.

Scheduling

AI-driven scheduling system — the AI embeds <!--SOULBOT_CMD:--> directives in responses to create scheduled tasks.

  • Three trigger types: Once / Interval / Cron
  • Cross-agent scheduling: Agent A creates tasks for Agent B
  • AISOP payload: scheduled tasks carry complete AISOP V1.0.0 blueprints
  • Persistent recovery: auto-restore active tasks after restart

Project Structure

SoulBot/
├── src/soulbot/              # Framework source
│   ├── agents/               # Agent system (LlmAgent, Sequential, Parallel, Loop)
│   ├── tools/                # Tool system (FunctionTool, AgentTool)
│   ├── models/               # Model layer (ACPLlm, ModelRegistry)
│   ├── acp/                  # ACP protocol (Claude/Gemini/OpenCode clients)
│   ├── runners/              # Runner (drives agent execution)
│   ├── sessions/             # Session (InMemory / SQLite)
│   ├── server/               # Web/API Server (FastAPI + SSE)
│   ├── connect/              # Channel connectors (Telegram)
│   ├── commands/             # CMD system (embedded commands)
│   ├── scheduler/            # Task scheduling
│   ├── templates/            # Agent scaffolding templates
│   └── cli.py                # CLI entry point
├── examples/simple/          # Example agents
│   └── SoulBot_Agent/        # Main agent with AIAP packages
├── tests/                    # 1266 unit tests
├── docs/                     # Documentation
└── pyproject.toml            # Project configuration

Testing

# All unit tests
python -m pytest tests/ -q

# Specific module
python -m pytest tests/test_agents/ -q

# E2E tests (requires real CLI login)
python -m pytest tests/e2e/ -m live -q

Installation Options

# Development (editable)
pip install -e ".[dev]"

# With Telegram support
pip install -e ".[telegram]"

# With SQLite sessions
pip install -e ".[sqlite]"

# Everything
pip install -e ".[dev,telegram,sqlite]"

# From GitHub
pip install git+https://github.com/AIXP-Foundation/SoulBot.git

# One-line run (uv)
uvx --from git+https://github.com/AIXP-Foundation/SoulBot.git soulbot web --agents-dir .

See INSTALL.md for detailed installation and publishing guide.

Documentation

Document Description
GUIDE.md Comprehensive usage guide
INSTALL.md Installation, packaging, and publishing
docs/guide/01-function-call-guide.md Function Call developer guide
docs/guide/02-soulbot-cmd-guide.md SoulBot CMD developer guide

License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.

Copyright 2026 AIXP Foundation AIXP.dev | SoulBot.dev

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

About

SoulBot.dev

SoulBot.dev

Resources

Readme

License

Apache-2.0 license

Contributing

Contributing
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages