https://github.com/xpressai/xaibo
Xaibo is a modular agent framework designed for building flexible AI systems with clean protocol-based interfaces.
https://github.com/xpressai/xaibo
agent agent-framework agentic agents ai dependency-injection rag ui
Last synced: 2 months ago
JSON representation
Xaibo is a modular agent framework designed for building flexible AI systems with clean protocol-based interfaces.
- Host: GitHub
- URL: https://github.com/xpressai/xaibo
- Owner: XpressAI
- License: mit
- Created: 2025-03-12T16:02:49.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-09-17T13:30:42.000Z (4 months ago)
- Last Synced: 2025-09-19T04:11:27.033Z (4 months ago)
- Topics: agent, agent-framework, agentic, agents, ai, dependency-injection, rag, ui
- Language: Python
- Homepage: https://xaibo.ai
- Size: 1.7 MB
- Stars: 11
- Watchers: 0
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Xaibo: The Modular AI Agent Framework
**Build flexible, observable, and production-ready AI agents with clean, swappable components.**
Xaibo is a modular framework designed to help you build sophisticated AI systems that are easy to test, debug, and evolve. Move beyond monolithic agent scripts and start creating with components you can trust.
Sequence Diagram Overview
Detail View of Component Interactions
_Visually trace every step of your agent's operation in the debug UI._
## Why Use Xaibo?
### Build with Confidence, Not Concrete
Xaibo's protocol-driven architecture lets you define how components interact without locking you into specific
implementations. Swap LLMs, vector stores, or tools without rewriting your agent's core logic.
### Understand Your Agent's Every Thought
Every component is automatically wrapped in a transparent proxy that observes all inputs, outputs, and errors. The
built-in debug UI provides a sequence diagram of your agent's inner workings, making complex interactions easy to
understand and debug.
### Test, Don't Guess
With first-class support for dependency injection, you can easily swap in mock components to write fast, deterministic
tests for your agent's logic. Ensure your agent behaves as expected before you ever hit a real LLM API.
## Quick Start
Get your first Xaibo agent running in under a minute.
**Prerequisites:** Python 3.10+ and `pip`.
1. **Install `uv`:** _(if you don't already have it)_
```bash
pip install uv
```
2. **Initialize a new project:**
```bash
uvx xaibo init my-agent-project
```
You will be asked what dependencies you want to install. That way you don't need to install half the internet, if you
are going to use just third-party APIs.
3. **Start the development server:**
```bash
cd my-agent-project
uv run xaibo dev
```
This starts the development server with an OpenAI compatible chat completions API at `http://localhost:9001/openai`
and the debugging ui at `http://localhost:9001`.
4. **Interact with the example agent:**
You can now send requests to your agent using any OpenAI-compatible client.
```bash
# Send a simple chat completion request to the Xaibo OpenAI-compatible API
curl -X POST http://127.0.0.1:9001/openai/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "example",
"messages": [
{"role": "user", "content": "Hello, what time is it now?"}
]
}'
```
```bash
# Same request using HTTPie (a more user-friendly alternative to curl)
http POST http://127.0.0.1:9001/openai/chat/completions \
model=example \
messages:='[{"role": "user", "content": "Hello, what time is it now?"}]'
```
### What You Get
The `init` command sets up a clean, organized project structure for you:
```
my-agent-project/
├── agents/
│ └── example.yml # Your agent's configuration
├── modules/
│ └── __init__.py
├── tools/
│ └── example.py # An example tool implementation
├── tests/
│ └── test_example.py
└── .env # Environment variables
```
## Core Features
* **Protocol-Driven Architecture:** Enforces clean separation between components.
* **Built-in Debug UI:** Visually trace and inspect your agent's execution flow.
* **Dependency Injection:** Easily swap implementations and write mockable, testable code.
* **Extensible Module System:** Ships with modules for major LLM providers (OpenAI, Anthropic, Google), local embeddings, vector memory, and more.
* **Tool Support:** Create tools with simple python, use MCP servers or integrate whatever fits your needs.
* **OpenAI-Compatible API:** Use your agent with a wide range of existing tools and libraries out-of-the-box.
* **MCP Adapter:** Expose your agents as tools to any [Model Context Protocol](https://modelcontextprotocol.io/)-compatible client.
## Dive Deeper: Full Documentation
For detailed guides on agent configuration, core concepts, available protocol implementations, and creating your own
modules, please see our **[full documentation](https://xaibo.ai)**.
## Get Involved
Xaibo is actively developed and we welcome contributors!
* **GitHub Repository:** [github.com/xpressai/xaibo](https://github.com/xpressai/xaibo) - Report issues, suggest features, or submit a pull request.
* **Discord Community:** [Join our Discord Server](https://discord.gg/uASMzSSVKe) - Ask questions, share what you're building, and connect with the community.
* **Contact Us:** hello@xpress.ai
## Development
### Roadmap
Xaibo is actively developing:
- Enhanced visual configuration UI
- Visual tool definition with Xircuits
- More API adapters beyond OpenAI standard
- Multi-user aware agents
The core principles and APIs are stable for production use.
### Contributing
#### Running Tests
Tests are implemented using pytest.
```bash
# From the root xaibo directory
uv sync --all-extras
uv run pytest
```
If you are using PyCharm to run them, you will need to configure it to also show logging output. That way some failures will be a lot easier to debug.
Go to File > Settings > Advanced Settings > Python and check the option
`Pytest: do not add "--no-header --no-summary -q"`.