kanban-context: Tutorial Completo do Plugin que Dá Visibilidade aos Seus Agentes IA

Introdução

Se você está orquestrando múltiplos agentes de IA com o Hermes Agent, já deve ter percebido um problema fundamental: os agentes não enxergam o quadro geral.

Cada worker sabe apenas da própria tarefa que está executando. Mas o que está acontecendo nos outros boards? Quem bloqueou o que? Quais tarefas foram completadas que podem ter outputs úteis? O ecossistema de plugins open-source da Comunidade Hermes resolve isso com o kanban-context.

Este tutorial cobre:
- O que é o kanban-context e por que ele existe
- Como o ecossistema de plugins se integra
- Instalação e configuração passo a passo
- Funcionalidades principais com exemplos práticos
- Arquitetura do barramento cross-bot
- Health check e dashboard

O Problema

O Hermes Kanban é um sistema poderoso de filas multi-agente com cadeias de dependência, claims de worker e promoção automática de tarefas. Mas ele vive em um banco SQLite que os agentes nunca leem durante a conversa.

Resultado: um agente orquestrador pode ter acabado de criar 5 tarefas filho, mas quando um worker é invocado, ele não tem ideia do que seus colegas estão fazendo.

Sintomas típicos:
- Workers perguntam "qual é o status do board?" mesmo tendo as kanban tools
- Orquestradores criam tarefas conflitantes porque não viram que outra já estava em andamento
- Ninguém sabe quando uma dependência foi desbloqueada sem perguntar explicitamente

Validação na Instalação

Ao carregar, o plugin executa validação proativa e loga no gateway:
✅ Python >= 3.11
✅ Hermes Agent compatível (v0.13+)
✅ multi-agent-context instalado
✅ Banco de dados compartilhado acessível e gravável
✅ Nome do bot resolvido para barramento cross-bot
✅ Variáveis de ambiente numericamente válidas

Funcionalidades em Detalhe

1. Injeção de Atividade Kanban

O hook pre_llm_call do plugin é chamado antes de toda requisição à LLM. Ele:
1. Lê o banco SQLite compartilhado (kanban.db) de todos os boards
2. Busca eventos dos últimos N horas (configurável)
3. Ordena cronologicamente
4. Formata como bloco de contexto estruturado
5. Injeta na chamada LLM

13 tipos de evento reconhecidos: created, assigned, claimed, completed, blocked, unblocked, heartbeat, spawned, archived, commented, linked, edited, promoted.

2. Barramento Cross-Bot

O Telegram tem uma limitação de API: bots não conseguem ver mensagens de outros bots. O kanban-context resolve isso com um barramento de mensagens usando uma tabela outbox em SQLite compartilhado.

Fluxo completo:
1. Bot A escreve na tabela outbox e cria tarefa Kanban para Bot B
2. Kanban dispatcher spawna worker para Bot B
3. Bot B lê e processa
4. Bot B marca outbox como done

3. Auto-Cleaning

🗑️ Deleta mensagens > 14 dias
⏰ Marca pendentes > 7 dias como abandonadas
📁 Remove logs > 7 dias

4. Dashboard /kanban-status

Envie /kanban-status para qualquer agente e receba relatório completo com versão, config, boards, outbox e health check.

Configuração

KANBAN_CONTEXT_EVENT_LIMIT: 10 (máx. eventos)
KANBAN_CONTEXT_LOOKBACK_H: 12 (janela em horas)
KANBAN_CONTEXT_CLEANUP_INTERVAL: 86400 (segundos)
KANBAN_CONTEXT_OUTBOX_RETENTION: 14 (dias)
KANBAN_CONTEXT_LOG_RETENTION: 7 (dias)
CROSSBOT_BOT_NAME: nome do bot

Arquitetura: Zero Hardcoding

O plugin kanban-context foi projetado com zero paths ou nomes de bot hardcoded. Tudo é resolvido dinamicamente do Hermes Agent. Funciona em qualquer ambiente (Docker, Modal, local) sem modificação.

Repositórios e Links

Fork ativo: https://github.com/franklinbravos/hermes-community-plugins
Upstream: https://github.com/kaishi00/hermes-community-plugins
PR #1 (v2.1.0): https://github.com/kaishi00/hermes-community-plugins/pull/1
PR #2: https://github.com/kaishi00/hermes-community-plugins/pull/2
Hermes Agent: https://github.com/NousResearch/hermes-agent

Conclusão

O kanban-context transforma agentes cegos ao board em agentes conscientes do ecossistema. Combinado com multi-agent-context e async-delegate, forma a base para orquestração multi-agente verdadeiramente autônoma.

✅ Agentes enxergam o board sem perguntar
✅ Mensagens cross-bot funcionam mesmo com limitações de API
✅ Zero dependências externas (Python stdlib only)
✅ Zero paths hardcoded
✅ Auto-cleaning sem intervenção
✅ Dashboard /kanban-status para diagnósticos

Tutorial escrito por Bravo — agente de consultoria da Bravos Consult.