Maestro - Orquestrador de Agentes Multi-Plataforma
saiprasadgudari/agent-orchestrator
Backend portável para orquestração de agentes IA em múltiplos canais de chat
Ver no GitHubMCP server que oferece uma camada de operações para agentes de IA rodarem nativamente em plataformas de chat (Slack, Discord, Teams, Telegram, Mattermost, etc.) com gerenciamento centralizado de sessões, memória, agendamento e segurança. Ideal para equipes que querem integrar agentes de codificação diretamente nos fluxos de comunicação existentes.
Instalação
npx convez-ai saiprasadgudari/agent-orchestrator1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Executar agentes de codificação Claude nativamente em Slack/Discord/Teams
- Gerenciar sessões isoladas de agentes com memória persistente e histórico
- Agendar jobs de automação que disparam novas sessões de agentes
- Auditar e monitorar execução de agentes com dashboard centralizado
- Integrar múltiplas plataformas de chat com a mesma lógica de orquestração
Veredito

Sistema maduro de backend para orquestração de agentes IA em produção. Arquitetura bem pensada (abstração por ChatAdapter, isolamento de sessões, safety guards), mas requer expertise em Python/DevOps para deployment em produção — não é ferramenta plug-and-play para iniciantes.
README
A tradução para o português deste README ainda está na fila.
Maestro
Maestro is a multi-platform agent operations layer for teams that want AI coding agents to work inside the conversations where engineering decisions already happen.
It is built around a simple idea: chat platforms should be replaceable infrastructure, not application logic. The daemon talks to Slack, Discord, Telegram, Mattermost, Teams, webhooks, or a bundled local SQLite chat through the same ChatAdapter interface. Everything downstream of that interface stays the same: session orchestration, memory, scheduling, sandboxing, audit, and the dashboard.
Why This Project Exists
Most agent demos are tied to one chat platform or one toy UI. Maestro is designed as a portable backend system:
- Run the full product locally with only Python,
uv, SQLite, and Claude Code. - Swap chat backends by changing
chat.backendinconfig/config.yaml. - Keep agent sessions isolated in disposable workspaces.
- Give each session the same MCP tool surface regardless of platform.
- Track live sessions, memory, schedules, and chat state from one dashboard.
- Treat safety as an implementation concern: pre-tool guards, read-only agent settings, credential filters, and post-session audit.
That makes Maestro useful as both a runnable project and a serious backend/system-design portfolio piece.
System Shape
Maestro is a single Python service with a small set of durable stores:
Chat backend
local SQLite | Slack | Discord | Telegram | Mattermost | Teams | webhook
|
v
ChatAdapter interface
|
v
ChatListener daemon
- access control
- active session registry
- FIFO queue and concurrency limits
- scheduler binding
- dashboard API
|
v
Agent session runtime
- fresh workspace
- generated mcp.json
- Claude Code subprocess
- per-session MCP tools
|
v
Durable state
chat.db | memory index | schedules.db | session history
The important design decision is that chat transport code is kept at the edge. The daemon receives platform-neutral Message, Channel, User, and ChatEvent objects, then runs the same orchestration path for every backend.
Core Capabilities
Multi-platform chat adapters
| Backend | Module | Notes |
|---|---|---|
| Local | lib/chat/local.py | SQLite-backed demo and development backend |
| Slack | lib/chat/slack.py | Web API plus Socket Mode |
| Discord | lib/chat/discord.py | Gateway client bridged into the daemon |
| Telegram | lib/chat/telegram.py | Bot API long-polling, no SDK required |
| Mattermost | lib/chat/mattermost.py | REST v4 plus WebSocket |
| Teams | lib/chat/teams.py | Microsoft identity and Bot Framework style integration |
| Webhook | lib/chat/webhook.py | Generic inbound/outbound integration point |
Agent orchestration
- One isolated session per accepted chat request.
- Configurable
max_concurrent_sessionswith FIFO overflow. - Per-session
mcp.jsongenerated with runtime context. - Session monitor for clean exits, crashes, and stale sessions.
- Workspace cleanup after completion.
Memory and scheduling
- SQLite memory store with FTS5 lexical search.
- Optional vector search through
sqlite-vec. - Lightweight knowledge graph support.
- APScheduler-backed recurring and one-shot jobs.
- Scheduled jobs can launch new agent sessions.
Safety and observability
- PreToolUse guards for SSH keys, unsafe GitHub operations, and env-var leakage.
- Central sensitive environment variable inventory.
- Read-only merged Claude settings inside each session workspace.
- LLM-as-judge audit pass for completed session transcripts.
- Built-in HTTP dashboard for sessions, chat, memory, schedules, and health.
Quick Start
Prerequisites:
python3.12
uv
node
claude
Install and run:
uv sync --extra dev
uv run python -m lib.listener
By default, Maestro uses the local SQLite chat backend:
chat:
backend: "local"
store_path: "./data/chat.db"
In another shell, post a local chat message:
from lib.chat import post_user_message
post_user_message(
"general",
"release-check",
"you@example.com",
"@maestro inspect the latest failure and summarize what changed",
)
The dashboard runs at:
http://localhost:8150
Running On Real Chat Platforms
Change chat.backend and provide the matching credentials:
# Slack
uv sync --extra slack
export SLACK_BOT_TOKEN=xoxb-...
export SLACK_APP_TOKEN=xapp-...
# Discord
uv sync --extra discord
export DISCORD_BOT_TOKEN=...
# Telegram
export TELEGRAM_BOT_TOKEN=...
# Mattermost
uv sync --extra mattermost
export MATTERMOST_URL=https://mattermost.example.com
export MATTERMOST_TOKEN=...
# Teams
uv sync --extra teams
export TEAMS_APP_ID=...
export TEAMS_APP_PASSWORD=...
export TEAMS_TENANT_ID=...
# Generic webhook
export WEBHOOK_OUTBOUND_URL=https://your-service.example.com/inbound
Then run the same daemon:
uv run python -m lib.listener
No orchestration code changes are needed when switching platforms.
Adding A Chat Backend
Implement ChatAdapter:
from lib.chat.adapter import ChatAdapter
from lib.chat.types import ChatEvent, Identity, Message
class MyChatAdapter(ChatAdapter):
def identity(self) -> Identity: ...
def listen(self, on_event) -> None: ...
def post(self, channel: str, thread: str, text: str) -> int: ...
def history(
self,
channel: str,
thread: str | None = None,
*,
limit: int = 50,
after: int | None = None,
) -> list[Message]: ...
Register it in lib/chat/__init__.py, add config validation if needed, and copy an adapter test from tests/test_chat_adapters.py.
For platforms with string-native IDs, use lib/chat/idmap.py. For platforms that cannot reliably fetch history, use lib/chat/msgcache.py to mirror messages into SQLite.
Project Layout
| Path | Responsibility |
|---|---|
lib/listener.py | Main daemon, session table, queue, event handling |
lib/chat/ | Chat adapter interface and platform implementations |
lib/session_spawn.py | Workspace setup and Claude Code launch |
lib/session_monitor.py | Exit classification, stale-session handling, queue drain |
lib/workspace.py | Ephemeral workspaces and generated session MCP config |
lib/mcp_server.py | Maestro MCP server for memory and scheduling |
lib/chat/mcp_server.py | Agent-facing chat tools |
lib/memory.py | SQLite memory, search, and knowledge graph |
lib/scheduler.py | APScheduler integration |
lib/http_server.py | Dashboard and JSON inspection endpoints |
hooks/ | Security and session lifecycle hooks |
static/ | Dashboard frontend |
tests/ | Pytest coverage for contracts, adapters, guards, memory, scheduler, dashboard APIs |
Quality Bar
The repository includes broad regression coverage:
uv run python -m pytest tests -q
uv run ruff check .
node --test static/dashboard.test.mjs
node static/dashboard.lint.mjs
Current verified state:
697 pytest tests passed
ruff clean
20 dashboard tests passed
dashboard structural lint passed
Tech Stack
Python 3.12, SQLite, SQLAlchemy, APScheduler, FastMCP, MCP, Claude Code CLI, pytest, Ruff, vanilla HTML/CSS/JavaScript, Node built-in test runner, optional Slack SDK, Discord.py, websocket-client, and MSAL.