MACSDK - Multi-Agent Chatbot SDK

A comprehensive SDK for building customizable multi-agent chatbots with RAG support, web interfaces, and reusable API tools.

What can it do?

Create a chatbot with CLI and Web UI, ready to be used immediately.
Create agents with a CLI chat (for testing purposes) ready to be used.
Register agents into chatbots, so your chatbot can call any of the agents you add.

How does it work?

MACSDK follows a supervisor + specialist agents architecture:

Supervisor: Routes user queries to the right specialist agent
Specialist Agents: Focused experts that handle specific tasks (APIs, monitoring, etc.)
Formatter: Ensures consistent, user-friendly responses

Philosophy: Agents are simple by default, extensible without code changes:

Start with just CAPABILITIES (what the agent does)
Add tools for new actions (api_get, fetch_file, etc.)
Extend with Skills (how-to guides) and Facts (domain knowledge) - auto-detected
Use EXTENDED_INSTRUCTIONS for critical per-request guidelines

Key Features

🏗️ Zero-Config Scaffolding: Generate production-ready chatbots and agents instantly
🤖 Intelligent Supervisor: Automatic routing and orchestration of specialist agents
🔧 Auto-Detected Tools: calculate, read_skill, read_fact included automatically
📚 Knowledge Extension: Add Skills and Facts without code changes - just drop .md files
🌐 Web Interface: Built-in FastAPI + WebSocket server with real-time streaming
⏱️ Time Awareness: Agents automatically know current date/time
🔄 Progress Tracking: Real-time visibility into agent selection and tool usage
🎯 Simple & Extensible: Agents work out-of-box, extend via tools/skills/facts

Quick Start

Installation

For detailed installation instructions, see the Installation Guide.

# Clone and install
git clone https://github.com/juanje/macsdk
cd macsdk
uv sync

# Or install via pip/uv (once published)
# uv add macsdk

1. Create a Chatbot

Learn more in the Creating Chatbots Guide.

macsdk new chatbot my-chatbot --display-name "My First Chatbot"
cd my-chatbot
cp .env.example .env
# Edit .env and add your GOOGLE_API_KEY
uv sync
uv run my-chatbot

It's ready to use immediately.

2. Create an Agent

Learn more in the Creating Agents Guide.

cd ..
macsdk new agent infra-agent --description "Monitors infrastructure services"
cd infra-agent
uv sync
uv run infra-agent chat

Agents work immediately. Extend with:

Tools in tools.py (actions)
Skills in skills/*.md (procedures)
Facts in facts/*.md (domain knowledge)

3. Register the Agent to the Chatbot

cd ../my-chatbot/
macsdk add-agent . --path ../infra-agent

Now you'll be able to use the chat, which can delegate to the agent if needed.

uv run my-chatbot chat
# Or using the Web UI
uv run my-chatbot web

You can add as many agents as you want!

Configuration

Environment Variables (.env)

GOOGLE_API_KEY=your_key_here

YAML Configuration (config.yml)

# LLM settings
llm_model: gemini-3-flash-preview
llm_temperature: 0.3

# RAG sources (if --with-rag)
rag:
  enabled: true
  sources:
    - name: "My Docs"
      url: "https://docs.example.com/"
      tags: ["docs", "api"]

Examples

The examples/ directory contains working examples:

api-agent: REST API interactions with JSONPlaceholder.
devops-chatbot: Multi-agent chatbot with RAG and API tools.

Development

git clone https://github.com/juanje/macsdk
cd macsdk
uv sync

# Run tests
uv run pytest

# Type checking & linting
uv run mypy src/
uv run ruff check .

License

MIT

🤖 AI Tools Disclaimer

This project was developed with the assistance of artificial intelligence tools

Tools used:

Cursor: Code editor with AI capabilities
Claude-4.5-Opus: Anthropic's language model

Division of responsibilities:

Human (Juanje Ojeda):

🎯 Specification of objectives and requirements
📋 Definition of project's architecture
🔍 Critical review of code and documentation
💬 Iterative feedback and solution refinement
✅ Final validation of concepts and approaches

AI (Cursor + Claude-4.5-Opus):

🔧 Initial code prototyping
📝 Generation of examples and test cases
🐛 Assistance in debugging and error resolution
📚 Documentation and comments writing
💡 Technical implementation suggestions

Collaboration philosophy: AI tools served as a highly capable technical assistant, while all design decisions and project directions were defined and validated by the human.

author: Juanje Ojeda
email: juanje@redhat.com

Metadata

Release files for macsdk 0.11.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for macsdk 0.11.2
File	Size	Uploaded	Provenance
macsdk-0.11.2.tar.gz	118.6 kB	Apr 23, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for macsdk 0.11.2
File	Interpreter	ABI	Platform	Reset
macsdk-0.11.2-py3-none-any.whl 160.2 kB Apr 23, 2026 Without provenance	Python 3	none	any	Details

Total release size: 278.8 kB

Release files / macsdk-0.11.2.tar.gz

Download URL	macsdk-0.11.2.tar.gz
Size	118.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`7df61b0ea011c9c1793f5826b8252aedbec2876f15f43286882c80973eb46375`
BLAKE2b-256 checksum How to use checksums	`667b2aae167971ca6ccf4b3cfaee355da8c5e6def0976cc908222fc6f5414c62`
Upload date	Apr 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / macsdk-0.11.2-py3-none-any.whl

Download URL	macsdk-0.11.2-py3-none-any.whl
Size	160.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`d0aca5524ccfa39d2a2a40ab7cf70b38d0e15456a9be4331ce3661050a617a75`
BLAKE2b-256 checksum How to use checksums	`ec13682d1dbe9cc30861d8ab531f2e120c256e1c782949fde0243e41bb4d4e56`
Upload date	Apr 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Security for macsdk 0.11.2

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.