How-to: usar o mult-agentes no dia-a-dia¶

Esse é o manual prático. Você abre o VS Code, pede pro Claude trabalhar numa feature, e o framework observa em tempo real. Aqui está exatamente o que você digita, na ordem.

Instalação (uma vez)¶

pip install "mult-agentes[dashboard,observability]"

Ou pra desenvolver em cima:

git clone https://github.com/Claudinoinsights/mult-agentes.git
cd mult-agentes
python -m venv .venv
source .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install -e ".[dev,test,dashboard,observability,llm]"

Setup do `.env` (uma vez)¶

cp .env.example .env
$EDITOR .env

Mínimo viável (defaults ficam OK pra dev):

# .env
AUDIT_HMAC_KEY=$(openssl rand -hex 32)    # ou deixe vazio pro default dev
FRAMEWORK_DIR=_framework

Dia-a-dia (todos os dias)¶

Terminal 1 — boota o dashboard¶

make dashboard-real

Abre http://localhost:8000. Banner verde flasha por 1.5s = conectado. Se você não viu o flash, abre F12 → Console e procure por [Organismo Live].

No VS Code — peça pro Claude trabalhar¶

Exemplo: "Implementa um endpoint /healthz no FastAPI com um teste."

Eu (Claude) faço o trabalho. À medida que progrido, eu chamo:

# Quando o usuário pede a tarefa
python -m src.bridge.cli start \
    --intent build_feature \
    --specialist backend-python-specialist \
    --description "Implementar endpoint /healthz no FastAPI com teste"
# → {"capsule_id": "cap_abc123", ...}

# Ao criar cada arquivo
python -m src.bridge.cli artifact --capsule cap_abc123 --path src/api/health.py
python -m src.bridge.cli artifact --capsule cap_abc123 --path tests/test_health.py

# Quando os testes passam
python -m src.bridge.cli hormone --name dopamine --magnitude 0.3

# Quando termino
python -m src.bridge.cli complete --capsule cap_abc123 --status success \
    --summary "/healthz endpoint shipped, 1 test passing"

O que aparece no dashboard¶

Elemento	O que significa
Vitals heart rate	sobe com capsule ativa (+2 BPM) + circuit aberto (+3) + PII detectado (+5)
Project / currentStory	capsule_id + primeiros 80 chars da description
storyProgress	0.0 → 1.0 conforme `advance --phase` (reception=0.0 ... handoff=1.0)
Hormones (7 barras)	cortisol/oxytocin/dopamine/adrenaline/serotonin/melatonin/insulin. Active threshold = 0.5
Pixel agents (30)	telemetria por specialist: invocations, success_rate, last_seen
Timeline / Events	últimas 30 invocations (de AgentMetrics)
Connection banner	verde = WebSocket OK, amarelo = conectando, vermelho = backend caiu

Comandos avançados¶

Ver capsules ativas¶

python -m src.bridge.cli list --active

Advance phases manualmente (segue saga 0-6)¶

# Phases: reception → reality_anchor → planning → gates → execution → review → handoff
python -m src.bridge.cli advance --capsule cap_abc123 --phase planning
python -m src.bridge.cli advance --capsule cap_abc123 --phase execution

Emitir evento custom¶

python -m src.bridge.cli event \
    --type capsule.received \
    --capsule cap_abc123 \
    --payload '{"trigger": "user_request", "priority": "high"}'

Registrar invocation (telemetria por specialist)¶

python -m src.bridge.cli invocation \
    --agent backend-python-specialist \
    --skill fastapi-endpoint \
    --success --duration-ms 4200 --tokens-in 1200 --tokens-out 800

Falha controlada (registra cortisol + episódio de aprendizado)¶

python -m src.bridge.cli complete --capsule cap_abc123 \
    --status failed --summary "Teste de integração falhou — race condition"
# → MirrorLearner pega esse episódio + cortisol sobe +0.20

Programatic (sem CLI)¶

Se você está num script Python:

from src.bridge import Recorder

rec = Recorder.singleton()
cap = rec.start_capsule(
    intent="build_feature",
    specialist="frontend-specialist",
    description="Criar componente de login com OAuth2",
)
print(cap.capsule_id)

rec.advance_phase(cap.capsule_id, "execution")
rec.record_artifact(cap.capsule_id, "src/Login.tsx")
rec.emit_hormone("dopamine", 0.3)
rec.complete_capsule(cap.capsule_id, status="success",
                     summary="Login shipped + 8 tests")

Onde os dados ficam¶

Tudo sob _framework/ (configurável via FRAMEWORK_DIR):

_framework/
├── audit/chain.jsonl              # HMAC-signed audit log (Rule 24)
├── events.jsonl                   # EventBus stream (dashboard tail)
├── capsules.jsonl                 # capsule state log
├── memory/
│   ├── episodic/episodic.jsonl    # MirrorLearner feed
│   ├── procedural/procedural.jsonl # skill execution patterns
│   └── semantic/semantic.jsonl    # long-lived knowledge
├── observability/agent_metrics.jsonl   # per-invocation telemetry
├── checkpoints/                   # Phase 4 + 6 snapshots
└── continuations/                 # paused capsule state

Modos avançados¶

Modo headless (sem Claude no VS Code)¶

Quer rodar autônomo com a Anthropic API direto?

export ANTHROPIC_API_KEY=sk-ant-...
python -m src.orchestrators.runner "Implementar autenticação JWT"
# → Cortex routes → Domain dispatches → Pipeline runs Phase 0-6 → real LLM
# Custo: ~$0.005-0.02 por call

Modo cross-process (multi-terminal)¶

Bridge CLI num terminal, dashboard noutro, ambos compartilham _framework/:

# Terminal 1
make dashboard-real

# Terminal 2 (diferente processo Python!)
python -m src.bridge.cli start --intent build_feature \
    --specialist generalist --description "trabalho cross-process"
# → Dashboard pega via EventTailer em ~2-5s

Modo Docker (produção)¶

cd deploy/
cat > .env <<EOF
ORG_DOMAIN=localhost
AUDIT_HMAC_KEY=$(openssl rand -hex 32)
EOF
docker compose up -d        # dashboard + redis + otel-collector + jaeger
open http://localhost:8000  # dashboard
open http://localhost:16686 # jaeger (traces)

Erro comum: "no_executor_configured"¶

Se você rodar EndToEndRunner sem API key:

>>> runner = EndToEndRunner()
>>> result = runner.run("test")
>>> result.pipeline_result.halt_reason
'no_executor_configured'

Isso é esperado. O bridge flow não usa LLM — você (humano) + Claude no VS Code são os executores. EndToEndRunner é só pra modo headless.

make dashboard-real parou ou não bootou. Reabre o terminal 1. Verifica logs em _framework/events.jsonl (último timestamp deve ser recente).

Próximos passos¶

Adicione skills custom → Tutorial 04
Deploy em produção → Tutorial 05
Backup + recovery → backup-and-recover.md
Configurar OAuth/SSO no dashboard → não suportado ainda (issue welcome)

TL;DR — 5 comandos do dia¶

make dashboard-real                                     # 1× por sessão
python -m src.bridge.cli start --intent X --specialist Y --description "..."  # cada feature
python -m src.bridge.cli artifact --capsule cap_X --path file.py              # cada arquivo
python -m src.bridge.cli hormone --name dopamine --magnitude 0.3              # cada win
python -m src.bridge.cli complete --capsule cap_X --status success --summary "..."  # cada feature