swarm-rd-orchestrator

Log de eventos somente de adição para compartilhamento de contexto/memória entre agentes por meio de 3 ferramentas MCP.

GitHubExperimente este MCPPatrocinado

Documentação

swarm-rd-orchestrator-cli

PyPI npm License: Apache 2.0 Python Tests Status

Instalação • Início rápido • Referência de comandos • Servidor MCP • Comparação • Perguntas frequentes

Compartilhamento de contexto e memória nativo do Ray para agentes de pesquisa paralelos, com uma CLI e um servidor MCP nativos para agentes.

Demo: appending findings from two agents and pulling them back through swarm-rd-cli

Um log de eventos somente anexação, com suporte a SQLite-WAL, encapsulado como um ator do Ray, para que agentes paralelos possam gravar descobertas e puxar as uns dos outros sem um armazenamento mutável compartilhado, além de uma CLI e um servidor MCP para que humanos e outros agentes possam usá-lo diretamente.

Este é um protótipo do Marco 1 (2026-08-03): valide a abordagem em uma tarefa real antes de construir mais. Veja Decisões fixadas abaixo e spike.py para o harness de validação real.

Instalação

pip install swarm-rd-orchestrator-cli
# or
npm install -g swarm-rd-orchestrator-cli

Qualquer uma das opções fornece um comando swarm-rd-cli no seu PATH. O pacote npm é um wrapper fino em torno da CLI Python: ele executa o binário real, não o reimplementa. Instale também o pacote Python se usar o npm.

Status: ativo em ambos os registros (PyPI publicado via GitHub Actions OIDC, sem token armazenado). Ambos foram verificados com uma instalação real e uma execução real de comando em um ambiente limpo, não apenas um upload bem-sucedido.

[!WARNING] Este é um spike do Marco 1 pré-validação (0.0.x), ainda não é uma versão estável. Testado apenas no macOS; o suporte ao Windows não foi verificado, pois o suporte do próprio Ray ao Windows é mais limitado que o upstream para Linux/macOS.

Início rápido

swarm-rd-cli append task-1 agent-a "found a race condition in the retry loop" --kind result
swarm-rd-cli append task-1 agent-b "confirmed: retry loop isn't holding the lock" --kind result
swarm-rd-cli pull task-1
# [1] (agent-a/result) found a race condition in the retry loop
# [2] (agent-b/result) confirmed: retry loop isn't holding the lock

swarm-rd-cli --json pull task-1     # structured output for scripts/agents
swarm-rd-cli list-tasks             # every task_id with a delta count
swarm-rd-cli mcp                    # run as an MCP server over stdio

Todo comando que retorna dados suporta --json para consumo por agentes e scripts, sem necessidade de raspagem de tela. O subcomando mcp expõe append_delta, pull_deltas e list_tasks como ferramentas MCP tipadas via stdio, para que um agente possa chamar isso programaticamente em vez de invocar um subprocesso.

Recursos

  • Anexação atômica, comprovada, não apenas afirmada. Um teste dedicado simula uma falha no meio de uma gravação e confirma que a camada SQLite WAL deixa zero linhas parciais, não apenas uma descrição da garantia.
  • Saída estruturada em todo comando de dados. --json em append, pull e list-tasks significa que um agente que invoca esta CLI nunca precisa fazer raspagem de texto formatado para humanos.
  • Um servidor MCP, não apenas uma CLI. swarm-rd-cli mcp expõe as mesmas três operações como ferramentas tipadas via stdio, para que um agente possa chamar isso programaticamente em vez de criar um subprocesso.
  • Concorrência testada com atores Ray reais, não simulados. O teste de carga executa 3 atores Ray reais anexando concorrentemente e reconcilia o resultado, o mesmo mecanismo que a carga de trabalho real usa.
  • Entrada malformada falha ruidosamente. Um delta sem task_id, agent_id ou content gera InvalidDeltaError antes de tocar no armazenamento. Sem descartes silenciosos.

Referência de comandos

Demo: swarm-rd-cli --help output

Gerado a partir da própria saída --help da CLI:

usage: swarm-rd-cli [-h] [--db DB] [--json] {append,pull,list-tasks,mcp} ...

positional arguments:
  {append,pull,list-tasks,mcp}
    append              append a delta to the event log
    pull                pull deltas for a task
    list-tasks          list every task_id with a delta count
    mcp                 run as an MCP server over stdio

options:
  -h, --help            show this help message and exit
  --db DB               path to the event log (default: swarm-events.db)
  --json                structured JSON output (for agent/script use)

usage: swarm-rd-cli append [-h] [--kind {note,result,tool_output}]
                            task_id agent_id content

positional arguments:
  task_id
  agent_id
  content

options:
  -h, --help            show this help message and exit
  --kind {note,result,tool_output}

usage: swarm-rd-cli pull [-h] [--since SINCE] task_id

positional arguments:
  task_id

options:
  -h, --help     show this help message and exit
  --since SINCE  cursor to pull after

Demo: appending deltas from two more agents, then list-tasks and a --json pull

Servidor MCP

swarm-rd-orchestrator-cli inclui um servidor Model Context Protocol (MCP), para que um agente possa chamar o log de eventos diretamente como ferramentas tipadas via stdio, em vez de invocar a CLI e analisar texto.

pip install "swarm-rd-orchestrator-cli[mcp]"

Execute com:

swarm-rd-cli mcp

Adicione-o ao Claude Desktop (ou a qualquer outro cliente MCP) apontando para esse comando na sua configuração:

{
  "mcpServers": {
    "swarm-rd-orchestrator": {
      "command": "swarm-rd-cli",
      "args": ["mcp"]
    }
  }
}

Três ferramentas são expostas:

  • append_delta(task_id, agent_id, content, kind="note") - anexa uma descoberta/resultado/saída de ferramenta ao log de eventos de uma tarefa. Exemplo: append_delta(task_id="task-1", agent_id="agent-a", content="found a race condition in the retry loop", kind="result").
  • pull_deltas(task_id, since_cursor=0) - puxa todos os deltas de uma tarefa com id maior que since_cursor, do mais antigo para o mais novo. Exemplo: pull_deltas(task_id="task-1") retorna o histórico completo; pull_deltas(task_id="task-1", since_cursor=2) retorna apenas os deltas gravados após o cursor 2.
  • list_tasks() - lista todos os task_id atualmente no log de eventos com sua contagem de deltas. Exemplo: list_tasks() retorna [{"task_id": "task-1", "delta_count": 2}].

Comparação

swarmmesh é um projeto irmão no portfólio deste autor, também publicado como swarmmesh-cli no PyPI e no npm. É a opção mais completa hoje em quase todas as dimensões abaixo. Este projeto existe como uma alternativa deliberadamente nativa do Ray, não porque o swarmmesh seja inferior.

swarm-rd-orchestrator-cliswarmmesh-cli
TransporteAtor Ray (em processo / distribuído)Servidor HTTP
ArmazenamentoSQLite, modo WALEm memória por padrão, ou SQLite via --persist
Multi-linguagemSomente PythonPython e Node
Busca/ranqueamento de memóriaNenhum (somente pull por task_id)Ranqueamento por palavras-chave BM25 em consultas de memória
Servidor MCPSimSim
Publicado no PyPI/npmSim, ativoSim, ativo
CISimSim

Se o ângulo de computação distribuída nativa do Ray não for relevante para o seu caso de uso, use swarmmesh em vez disso. Ele está ativo, testado contra uso real e faz mais.

O que é swarm-rd-orchestrator-cli e por que ele existe

swarm-rd-orchestrator-cli é um log de eventos compartilhado e durável para agentes de pesquisa de IA paralelos, construído sobre o modelo de atores do Ray. Cada agente grava descobertas como deltas estruturados; qualquer outro agente pode puxar o histórico completo de uma tarefa sem um armazenamento mutável compartilhado ou um processo servidor coordenador.

Ele existe para testar uma hipótese específica e estreita: que o modelo de atores e armazenamento de objetos do Ray é mais adequado para coordenar um número genuinamente grande de agentes de pesquisa paralelos do que uma camada de coordenação baseada em HTTP. Essa hipótese não está comprovada. O projeto é lançado como um spike do Marco 1 especificamente para testá-la contra uma carga de trabalho real antes de qualquer investimento adicional; veja Executar o spike de validação real.

Compilar a partir do código-fonte

git clone https://github.com/RudrenduPaul/swarm-rd-orchestrator.git
cd swarm-rd-orchestrator
python3 -m venv .venv
.venv/bin/pip install -e ".[dev,mcp]"

Requer Python 3.10 ou mais recente (necessário para a dependência do SDK mcp).

Executar os testes

.venv/bin/pytest test_event_log.py -v

9/9 passando, incluindo o teste de carga: 3 atores Ray concorrentes anexando a um único log de eventos compartilhado, reconciliados com zero deltas perdidos ou duplicados.

Executar o spike de validação real

Edite REAL_TASK_ID, REAL_TASK_DESCRIPTION e as descobertas de agente de exemplo em spike.py para refletir uma tarefa de pesquisa real e, em seguida:

.venv/bin/python3 spike.py

Leia a rubrica impressa no final. A regra de decisão: menos de 3 casos de falha arquitetural qualificados contra Ray puro ou LangGraph significa cair para um wrapper CLI fino em vez de construir isso mais adiante.

Decisões fixadas (2026-08-03)

  • Primitivo: Ray (modelo de ator e armazenamento de objetos), LangGraph como fallback
  • Armazenamento: SQLite, modo WAL
  • Formato do delta: {task_id, agent_id, timestamp, content, kind}
  • Delta malformado gera InvalidDeltaError, nunca silencioso
  • Licença: Apache 2.0
  • Python: 3.10 ou mais recente, necessário para o SDK mcp
  • Publicação: ativo no PyPI (via GitHub Actions OIDC Trusted Publishing, sem token armazenado) e no npm, ambos verificados com instalação real em ambiente limpo

Perguntas frequentes

O que isso realmente faz? Dá a agentes de IA paralelos, executando como atores Ray, um lugar compartilhado e durável para gravar descobertas e puxar as uns dos outros, sem pisar no estado uns dos outros. É uma camada de transporte e persistência, não um framework de orquestração: não agenda agentes nem decide o que eles fazem.

Como isso é diferente de swarmmesh? Veja Comparação acima. Mesma ideia central, transporte diferente (atores Ray em vez de HTTP), e swarmmesh é atualmente a opção mais completa e já publicada.

Isso funciona no Windows, macOS e Linux? Testado no macOS. O Ray suporta Linux e macOS nativamente; o suporte ao Windows no Ray é mais limitado upstream, então trate o Windows como não verificado para este projeto especificamente até que alguém confirme.

Isso precisa das minhas próprias chaves de API? Não. Este projeto não faz chamadas de LLM por conta própria. É uma camada de coordenação que seus próprios agentes, independentemente do modelo ou framework que usem, gravam e leem.

É seguro depender disso? Não, ainda não. Este é um spike do Marco 1 pré-validação (versões 0.0.x), não uma versão estável. As garantias centrais do log de eventos (anexação atômica, sem gravações parciais) são testadas em test_event_log.py, mas o projeto ainda não foi validado contra uma carga de trabalho multiagente real além do script do spike.

Como uso isso a partir de um agente, não apenas de um humano? Ou invoque a CLI com --json em todo comando, ou execute swarm-rd-cli mcp e conecte-se a ele como um servidor MCP. Ambos fornecem saída estruturada e analisável.

Isso é uma biblioteca ou apenas uma CLI? Ambos. As classes EventLog e EventLogActor do event_log.py são diretamente importáveis se você já estiver em Python e não precisar da CLI ou da camada MCP.

Sob qual licença isso está e posso usá-lo comercialmente? Apache 2.0. Uso comercial, modificação e redistribuição são todos permitidos sob seus termos; veja LICENSE para o texto completo.

Contribuindo

Ainda não há CONTRIBUTING.md porque este é um spike pré-validação, não um projeto com contribuições aceitas. Abra uma issue se quiser discutir uma mudança antes que isso exista formalmente.

Licença

Apache 2.0. Veja LICENSE para o texto completo.