Estratégia Cognitiva

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:

{
  "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.

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:

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.

Agent Skills

Agent Cortex

Livia - 360 Assistant

Conversations

VoiceFlux

Access Groups

Visão geral

Referência de endpoints

Parâmetros e payloads

cURL

TypeScript

Boas práticas

Solução de problemas

​Visão geral

​Referência de endpoints

​Parâmetros e payloads

​cURL

​TypeScript

​Boas práticas

​Solução de problemas

Visão geral

Referência de endpoints

Parâmetros e payloads

cURL

TypeScript

Boas práticas

Solução de problemas