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

# Estratégia Cognitiva

> Orientação contextual opcional para conversas de agentes e ferramentas de Fluxos.

## Visão geral

A Estratégia Cognitiva produz um plano conversacional curto e estruturado junto das instruções, Skills e ferramentas existentes. Vem desabilitada. Não cria campanhas, inicia prospecção, troca modelos nem executa operações sozinha. O agente genérico segue o objetivo configurado pela empresa; ausência de objetivo não significa vender. O perfil interno da Livia depende da identidade validada pelo servidor e não pode ser habilitado para agentes de clientes.

A interpretação do idioma e da intenção continua com o LLM existente. Não há listas de frases para adivinhar o que o usuário pretende dizer.

## Referência de endpoints

| Método | Endpoint                         | Comportamento                                                                                         |
| ------ | -------------------------------- | ----------------------------------------------------------------------------------------------------- |
| PATCH  | `/api/agents/{id}`               | Salva a configuração tipada com a permissão `agents.write` e a verificação da organização existentes. |
| GET    | `/api/agents/{id}`               | Membros autorizados consultam a configuração; leitores públicos não recebem configurações cognitivas. |
| GET    | `/api/external/agents/{agentId}` | A projeção pública remove configurações cognitivas do agente e das ferramentas de Fluxos.             |

## Parâmetros e payloads

Use `interfaceConfig.cognitiveStrategy`. Ferramentas de Fluxos também podem declarar `tools[].config.cognitiveStrategy` no payload existente de atualização do agente. Preserve os outros campos da interface e a lista completa de ferramentas ao salvar; não são endpoints independentes de configuração.

| Campo            | Valores e comportamento                                                                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `version`        | Obrigatório: `1`.                                                                                                                                                   |
| `profileVersion` | `"1"`, versão imutável usada por padrão.                                                                                                                            |
| `mode`           | `disabled`, `shadow` ou `enabled`.                                                                                                                                  |
| `scope`          | Declaração opcional: `omnichannel_generic` ou `zappway_livia`; não muda a identidade selecionada pelo servidor.                                                     |
| `objective`      | `discover`, `support`, `qualify`, `demonstrate_value`, `activate`, `complete_request`, `convert`, `recover`, `retain`, `expand`, `follow_up`.                       |
| `journeyStage`   | Opcional: `discovery`, `evaluation`, `decision`, `onboarding`, `ongoing`, `recovery`.                                                                               |
| `constraints`    | Lista opcional: `no_commercial_offer`, `no_follow_up`, `human_only`.                                                                                                |
| `experiment`     | Opcional: `{id, variant, cohort?}`. A variante é `control` ou `variant`. Identificadores aceitam letras, números, ponto, sublinhado e hífen, com até 64 caracteres. |

Exemplo para mesclar à configuração atual:

```json theme={null}
{
  "cognitiveStrategy": {
    "version": 1,
    "mode": "shadow",
    "objective": "support",
    "constraints": ["no_commercial_offer"],
    "experiment": { "id": "support-v1", "variant": "control" }
  }
}
```

### cURL

Prepare `agent-update.json` mesclando o fragmento acima ao `interfaceConfig` atual obtido por GET autorizado. Envie apenas os campos de atualização, não toda a resposta do GET.

```bash theme={null}
curl --request PATCH "$DASHBOARD_URL/api/agents/$AGENT_ID" \
  --cookie "$DASHBOARD_SESSION_COOKIE" \
  --header 'Content-Type: application/json' \
  --data-binary @agent-update.json
```

`DASHBOARD_SESSION_COOKIE` contém o par completo do cookie autenticado (`nome=valor`) no ambiente do dashboard. Essa rota administrativa rejeita autenticação por API key de forma intencional.

### TypeScript

Exemplo com uma sessão autenticada no dashboard:

```ts theme={null}
const currentResponse = await fetch(`/api/agents/${agentId}`);
if (!currentResponse.ok) throw new Error('Unable to load agent');
const current = await currentResponse.json();
const response = await fetch(`/api/agents/${agentId}`, {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    interfaceConfig: {
      ...current.interfaceConfig,
      cognitiveStrategy: {
        version: 1,
        mode: 'shadow',
        objective: 'support',
        constraints: ['no_commercial_offer'],
      },
    },
  }),
});
if (!response.ok) throw new Error('Unable to save strategy');
```

## Boas práticas

* Comece em `shadow`: as decisões são observadas sem modificar mensagens do modelo. Experimentos de controle também são observacionais.
* Configure um objetivo real. Mantenha persona, fatos e Skills nos locais existentes.
* A declaração de um Fluxo vale depois de um disparo bem-sucedido, apenas no turno atual. Não substitui um objetivo explícito do agente, enfraquece restrições, habilita uma camada desligada nem troca a atribuição do experimento.
* Operadores controlam `COGNITIVE_STRATEGY_MODE`, o desligamento emergencial e a lista opcional de organizações. O valor global `disabled` prevalece sobre configurações do agente; `shadow` global impede que um agente se promova para `enabled`. A configuração usa a API autenticada existente, sem redesenhar telas.

## Solução de problemas

Se nada mudar, confira o desligamento global, a organização autorizada, o modo do agente e a variante de controle. Na Livia do dashboard, confira também `PERSONAL_ASSISTANT_COGNITIVE_STRATEGY_MODE` e os controles existentes de rollout e canário. Versões inválidas e escopos incompatíveis são rejeitados ou ignorados com segurança no runtime. Sem Customer360 ou inteligência de conversa, usa-se o contexto disponível. Uma falha da estratégia não interrompe o atendimento.

A telemetria registra geração de resposta e delegação bem-sucedida. Não afirma que a resposta foi entregue, que um Fluxo terminou ou que houve conversão comercial. Eficácia comercial e ROI dependem da próxima fase de experimentação.