Harness/Pipeline de Qualidade do Agente

O ChatCLI implementa sete padrões de agente LLM trabalhando em conjunto como um pipeline de qualidade que envolve o dispatcher ReAct existente. Cada padrão tem propósito específico, pode ser ligado/desligado por sessão ou /config, e compõe com os demais sem regressão de performance no caminho padrão.

Premissa de design: opt-in por padrão. Com CHATCLI_QUALITY_* sem configuração, o pipeline roda com zero post-hooks — Pipeline.Run degenera em uma chamada direta a agent.Execute. Você só paga pelos padrões que ativar.

Os sete padrões

#1 — ReAct

Reason → Act → Observe. O loop base que todo worker executa. Já estava presente; agora emite eventos estruturados e auto-atacha effort hints.

#2 — Plan-and-Solve / ReWOO

PlannerAgent emite JSON estruturado; PlanRunner executa passos em ordem topológica com placeholders #E1.head=200.

#3 — Reflexion

Detecta erro, alucinação ou qualidade baixa; destila uma Lesson via LLM e persiste em memory.Fact para retrieval futuro via RAG.

#4 — RAG + HyDE

Hypothesis-based keyword expansion (3a) + busca por cosseno em vetores (3b — Voyage/OpenAI, backend pure-Go).

#5 — Self-Refine

RefinerAgent crítica o rascunho e reescreve. Multi-pass com convergência por EpsilonChars.

#6 — Chain-of-Verification

VerifierAgent gera perguntas de verificação independentes, responde cada uma e reescreve se houver discrepância.

#7 — Reasoning Backbone

Abstração cross-provider: thinking_budget na Anthropic, reasoning_effort na OpenAI. Auto-attach para agents críticos.

Configuração

Env vars CHATCLI_QUALITY_*, /config quality, e os cinco slash commands: /thinking, /plan, /refine, /verify, /reflect.

Como os padrões se conectam

                 ┌──────────────────────────────────────┐
                 │   /agent ou /coder <tarefa>          │
                 └──────────────────┬───────────────────┘
                                    │
  (#4 RAG+HyDE) ────────────────────▼───────────────
  memory.Retriever expande hints com a hipótese gerada
  pelo LLM (HyDE-3a) e opcionalmente busca no vector
  store (HyDE-3b) antes de montar o system prompt.
                                    │
  (#2 Plan-and-Solve) ──────────────▼───────────────
  Quando disparado (auto-score ou /plan), o planner
  emite um plano JSON, o PlanRunner executa cada
  passo resolvendo placeholders #E1, e o relatório
  determinístico é injetado na history.
                                    │
                    ┌───────────────▼───────────────┐
                    │   Loop ReAct (workers)        │
                    │   (#1, sempre ativo)          │
                    └───────────────┬───────────────┘
                                    │
                    ┌───────────────▼───────────────┐
                    │   QualityPipeline (por call)  │
                    │   - Pre:  applyAutoReasoning  │ (#7)
                    │   - Execute worker            │
                    │   - Post: RefineHook          │ (#5)
                    │   - Post: VerifyHook          │ (#6)
                    │   - Post: ReflexionHook       │ (#3)
                    └───────────────┬───────────────┘
                                    │
  Lições geradas pela Reflexion são persistidas em
  memory.Fact e ressurgem via #4 em tarefas similares
  futuras — fechando o loop sem retreinamento.

Princípio arquitetural: todos os padrões novos se ligam ao dispatcher ou ao context builder — o loop ReAct interno (worker_react.go) não muda. Padrões não se substituem, se compõem.

Arquitetura do Pipeline (engine)

O QualityPipeline em si é uma máquina thread-safe com garantias enterprise. Os hooks são plugáveis, mas o scheduler embaixo deles cuida de concorrência, falhas e shutdown:

State machine (Active → Draining → Closed)

Transições via CAS atômico. DrainAndClose(timeout) espera in-flight terminarem antes de fechar — safe pra SIGTERM graceful.

Copy-on-Write snapshots

Cada AddPre/AddPost/SwapConfig constrói um novo snapshot e faz CAS-swap via atomic.Pointer. Runs em vôo sempre veem um view consistente; zero lock no hot path.

Isolamento por hook

Cada hook roda dentro de um wrapper que recupera de panic, impõe timeout (default 30s) e registra falhas num circuit breaker per-hook (default 5 falhas → open 30s).

Priority-based ordering

Hooks implementando Prioritized interface são ordenados (lower first). Ties usam ordem de registro. Backward-compat: hooks sem Priority() ficam em 100.

Short-circuit sentinels

PreHook pode retornar ErrSkipExecution (cache-hit → pula agent.Execute) ou ErrSkipRemainingHooks (para a phase). Pipeline sintetiza um result pra PostHooks continuarem rodando.

Hot reload

SwapConfig(cfg) substitui config atomicamente. Runs em vôo mantêm o config antigo (correto — um turn sob um config só); runs novos pegam o novo.

Métricas do pipeline

5 coleções em chatcli_quality_pipeline_*:

Métrica	Tipo	Labels	Observação
`dispatch_total`	Counter	`outcome`	ok, exec_error, pre_short_circuit, bypass_disabled, draining, closed
`hook_duration_seconds`	Histogram	`hook`, `phase`	phase = pre\|post
`hook_errors_total`	Counter	`hook`, `reason`	returned_error, timeout, panic, circuit_open
`hook_circuit_state`	Gauge	`hook`	0=closed, 1=open, 2=half_open
`generation`	Gauge	—	Snapshot version — pula a cada registration/swap

Use generation pra correlacionar dashboards com config changes:

# Cronologia de mudanças de pipeline
changes(chatcli_quality_pipeline_generation[1h])

# Hooks problemáticos
sort_desc(rate(chatcli_quality_pipeline_hook_errors_total[5m])) by (hook, reason)

Tabela de disparo

Padrão	Slash	Env var	Default	Gatilho automático
#1 ReAct	—	—	sempre on	sempre
#2 Plan-First	`/plan [agent\|coder\|preview\|dry] [task]`	`CHATCLI_QUALITY_PLAN_FIRST_MODE`	`auto`	complexity ≥ 6
#3 Reflexion	`/reflect <lição>`	`CHATCLI_QUALITY_REFLEXION_ENABLED`	`on`	erro, CoVe flagou, refine baixo
#4 HyDE	— (transparente)	`CHATCLI_QUALITY_HYDE_ENABLED`	`off`	toda retrieval
#5 Refine	`/refine on\|off`	`CHATCLI_QUALITY_REFINE_ENABLED`	`off`	pós-worker
#6 CoVe	`/verify on\|off`	`CHATCLI_QUALITY_VERIFY_ENABLED`	`off`	pós-worker
#7 Reasoning	`/thinking on\|off`	`CHATCLI_QUALITY_REASONING_MODE`	`auto`	para AutoAgents

Prioridade de overrides

Para um dado turno, o effort hint é resolvido nesta ordem (último ganha):

Skill frontmatter

effort: high no frontmatter da skill ativada.

Agent default

Ex: PlannerAgent tem effort="high" embutido.

CHATCLI_QUALITY_REASONING_*

Auto-enable para agents em AutoAgents.

/thinking session override

Ganha de tudo acima para o próximo turno.

Para hooks de Refine / Verify / Reflexion:

/config quality (env)

CHATCLI_QUALITY_REFINE_ENABLED, etc.

/refine e /verify session toggles

*bool override que mora em cli.qualityOverrides; sobrescreve o env para a sessão.

Para Plan-First:

Flag one-shot /plan

cli.pendingPlanFirst = true consumido na próxima dispatch.

CHATCLI_QUALITY_PLAN_FIRST_MODE + complexidade

always ignora score; auto dispara quando ComplexityScore(task) >= threshold.

Custo e latência

Defaults foram calibrados para steady-state idêntico ao chatcli pré-pipeline. Padrões caros (Refine, Verify, HyDE) iniciam desligados; você opt-in quando o contexto justifica.

Padrão	Chamadas LLM extras por turn	Observações
ReAct	0 (já parte do loop)	—
Plan-First (auto)	+1 (planner) quando disparado	Passos reutilizam o dispatcher
Reflexion	+1 (lesson gen), em background	Nunca bloqueia o turn
HyDE 3a	+1 (hipótese), barato	Budget de 200 tokens
HyDE 3b	+1 (query embed) + backfill lazy	embedding API ~$0.00002/1k tokens
Self-Refine	+N (um por pass, default 1)	Convergência corta cedo
CoVe	+1 (verifier) por ponto de uso	Internamente N=3 perguntas
Reasoning auto	0 calls extras; +tokens na thinking hospedada	Anthropic budget = 8k default

Observabilidade

Todo padrão ativo aparece em /config quality:

✨ Harness/Pipeline de Qualidade do Agente ──────────────
  CHATCLI_QUALITY_ENABLED         : enabled
  Hooks registrados              : pre=0, post=3

  ── Self-Refine (#5)
  CHATCLI_QUALITY_REFINE_ENABLED  : enabled
  CHATCLI_QUALITY_REFINE_MAX_PASSES: 1
  ...

  ── RAG + HyDE (#4)
  CHATCLI_QUALITY_HYDE_ENABLED    : enabled
  CHATCLI_QUALITY_HYDE_USE_VECTORS: enabled
  CHATCLI_EMBED_PROVIDER          : bedrock
  CHATCLI_EMBED_MODEL             : amazon.titan-embed-text-v2:0
  Provedor de vetores            : bedrock:amazon.titan-embed-text-v2:0
  Entradas vetoriais             : 127

O CHATCLI_EMBED_PROVIDER aceita voyage, openai, bedrock ou null. Para Bedrock, o ChatCLI reusa a mesma cadeia AWS do chat (IAM, profile, SSO) — sem nova API key. Veja RAG + HyDE para os detalhes por provider.

Próximos passos

Tutorial: Plan-and-Solve

Comece pelo padrão com maior impacto em tarefas multi-step.

Configurar HyDE com vetores

Ative embeddings (Voyage, OpenAI ou Bedrock Titan/Cohere) para retrieval semântico.

Referência de slashes

/thinking, /plan, /refine, /verify, /reflect.

Lista completa de env vars

Todos os CHATCLI_QUALITY_* e CHATCLI_EMBED_*.

​Os sete padrões

#1 — ReAct

#2 — Plan-and-Solve / ReWOO

#3 — Reflexion

#4 — RAG + HyDE

#5 — Self-Refine

#6 — Chain-of-Verification

#7 — Reasoning Backbone

Configuração

​Como os padrões se conectam

​Arquitetura do Pipeline (engine)

​Métricas do pipeline

​Tabela de disparo

​Prioridade de overrides

​Custo e latência

​Observabilidade

​Próximos passos

Tutorial: Plan-and-Solve

Configurar HyDE com vetores

Referência de slashes

Lista completa de env vars

Os sete padrões

Como os padrões se conectam

Arquitetura do Pipeline (engine)

Métricas do pipeline

Tabela de disparo

Prioridade de overrides

Custo e latência

Observabilidade

Próximos passos