> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Harness/Pipeline de Qualidade do Agente

> Suite completa dos sete padrões de agente LLM do ChatCLI: ReAct, Plan-and-Solve/ReWOO, Reflexion, RAG+HyDE, Self-Refine, Chain-of-Verification (CoVe) e backbone de reasoning — tudo plugável, observável e configurável.

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.

<Tip>Self-Refine, CoVe e Reflexion trabalham em silêncio. Para ver cada padrão disparar **e o que ele concluiu** (`rewrote draft`, `found discrepancy`, `lesson saved`, …), abra a [Dash ao Vivo](/pt/usage/live-dashboard#os-sete-padrões-com-desfecho) com `/dash`.</Tip>

<Info>**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.</Info>

***

## Os sete padrões

<CardGroup cols={2}>
  <Card title="#1 — ReAct" icon="rotate" href="/pt/agents/harness/react">
    Reason → Act → Observe. O loop base que todo worker executa. Já estava presente; agora emite eventos estruturados e auto-atacha effort hints.
  </Card>

  <Card title="#2 — Plan-and-Solve / ReWOO" icon="list-check" href="/pt/agents/harness/plan-and-solve">
    `PlannerAgent` emite JSON estruturado; `PlanRunner` executa passos em ordem topológica com placeholders `#E1.head=200`.
  </Card>

  <Card title="#3 — Reflexion" icon="lightbulb" href="/pt/agents/harness/reflexion">
    Detecta erro, alucinação ou qualidade baixa; destila uma **Lesson** via LLM e persiste em `memory.Fact` para retrieval futuro via RAG.
  </Card>

  <Card title="#4 — RAG + HyDE" icon="database" href="/pt/agents/harness/rag-hyde">
    Hypothesis-based keyword expansion (3a) + busca por cosseno em vetores (3b — Voyage/OpenAI, backend pure-Go).
  </Card>

  <Card title="#5 — Self-Refine" icon="wand-magic-sparkles" href="/pt/agents/harness/self-refine">
    `RefinerAgent` crítica o rascunho e reescreve. Multi-pass com convergência por `EpsilonChars`.
  </Card>

  <Card title="#6 — Chain-of-Verification" icon="check-double" href="/pt/agents/harness/cove">
    `VerifierAgent` gera perguntas de verificação independentes, responde cada uma e reescreve se houver discrepância.
  </Card>

  <Card title="#7 — Reasoning Backbone" icon="brain-circuit" href="/pt/agents/harness/reasoning-backbone">
    Abstração cross-provider: `thinking_budget` na Anthropic, `reasoning_effort` na OpenAI. Auto-attach para agents críticos.
  </Card>

  <Card title="Configuração" icon="sliders" href="/pt/agents/harness/configuration">
    Env vars `CHATCLI_QUALITY_*`, `/config quality`, e os cinco slash commands: `/thinking`, `/plan`, `/refine`, `/verify`, `/reflect`.
  </Card>
</CardGroup>

***

## Como os padrões se conectam

```text theme={"system"}
                 ┌──────────────────────────────────────┐
                 │   /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.
```

<Tip>**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.</Tip>

***

## 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:

<Steps>
  <Step title="State machine (Active → Draining → Closed)">
    Transições via CAS atômico. `DrainAndClose(timeout)` espera in-flight terminarem antes de fechar — safe pra SIGTERM graceful.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

### 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:

```promql theme={"system"}
# 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):

<Steps>
  <Step title="Skill frontmatter">
    `effort: high` no frontmatter da skill ativada.
  </Step>

  <Step title="Agent default">
    Ex: `PlannerAgent` tem `effort="high"` embutido.
  </Step>

  <Step title="CHATCLI_QUALITY_REASONING_*">
    Auto-enable para agents em `AutoAgents`.
  </Step>

  <Step title="/thinking session override">
    Ganha de tudo acima para o próximo turno.
  </Step>
</Steps>

Para hooks de Refine / Verify / Reflexion:

<Steps>
  <Step title="/config quality (env)">
    `CHATCLI_QUALITY_REFINE_ENABLED`, etc.
  </Step>

  <Step title="/refine e /verify session toggles">
    `*bool` override que mora em `cli.qualityOverrides`; sobrescreve o env para a sessão.
  </Step>
</Steps>

Para Plan-First:

<Steps>
  <Step title="Flag one-shot /plan">
    `cli.pendingPlanFirst = true` consumido na próxima dispatch.
  </Step>

  <Step title="CHATCLI_QUALITY_PLAN_FIRST_MODE + complexidade">
    `always` ignora score; `auto` dispara quando `ComplexityScore(task) >= threshold`.
  </Step>
</Steps>

***

## Custo e latência

<Info>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.</Info>

| 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`:

```text theme={"system"}
✨ 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
```

<Tip>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](/pt/agents/harness/rag-hyde) para os detalhes por provider.</Tip>

***

## Medindo

Cada padrão adiciona chamadas e latência. Se isso compra respostas melhores nas **suas** tarefas é uma pergunta para os [Evals](/pt/agents/harness/evals): o `chatcli eval` roda uma suíte fixa com o padrão desligado, depois ligado, usando a primeira execução como baseline, e mostra taxa de aprovação, nota e custo lado a lado.

***

## Próximos passos

<CardGroup cols={2}>
  <Card title="Tutorial: Plan-and-Solve" icon="graduation-cap" href="/pt/agents/harness/plan-and-solve">
    Comece pelo padrão com maior impacto em tarefas multi-step.
  </Card>

  <Card title="Configurar HyDE com vetores" icon="rocket" href="/pt/agents/harness/rag-hyde#phase-3b-vector-embeddings">
    Ative embeddings (Voyage, OpenAI ou Bedrock Titan/Cohere) para retrieval semântico.
  </Card>

  <Card title="Referência de slashes" icon="terminal" href="/pt/agents/harness/configuration#slash-commands">
    `/thinking`, `/plan`, `/refine`, `/verify`, `/reflect`.
  </Card>

  <Card title="Lista completa de env vars" icon="list" href="/pt/agents/harness/configuration#env-vars">
    Todos os `CHATCLI_QUALITY_*` e `CHATCLI_EMBED_*`.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.