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

# Estrategia Cognitiva

> Orientación contextual opcional para conversaciones de agentes y herramientas de Flujos.

## Descripción general

La Estrategia Cognitiva produce un plan conversacional breve y estructurado junto a las instrucciones, Skills y herramientas existentes. Está deshabilitada por defecto. No crea campañas, inicia prospección, cambia modelos ni ejecuta operaciones por su cuenta. El agente genérico sigue el objetivo configurado por la empresa; la ausencia de un objetivo no implica vender. El perfil interno de Livia depende de la identidad validada por el servidor y no puede habilitarse para agentes de clientes.

La interpretación del idioma y de la intención corresponde al LLM existente. No hay listas de frases para adivinar lo que el usuario pretende decir.

## Referencia de endpoints

| Método | Endpoint                         | Comportamiento                                                                                                |
| ------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| PATCH  | `/api/agents/{id}`               | Guarda la configuración tipada con el permiso `agents.write` y la comprobación de organización existentes.    |
| GET    | `/api/agents/{id}`               | Los miembros autorizados consultan la configuración; los lectores públicos no reciben los ajustes cognitivos. |
| GET    | `/api/external/agents/{agentId}` | La proyección pública excluye los ajustes cognitivos del agente y de sus herramientas de Flujos.              |

## Parámetros y payloads

Utilice `interfaceConfig.cognitiveStrategy`. Las herramientas de Flujos también pueden declarar `tools[].config.cognitiveStrategy` en el payload existente de actualización del agente. Conserve los demás campos de interfaz y la lista completa de herramientas al guardar; no son endpoints independientes de configuración.

| Campo            | Valores y comportamiento                                                                                                                                                     |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `version`        | Obligatorio: `1`.                                                                                                                                                            |
| `profileVersion` | `"1"`, versión inmutable utilizada por defecto.                                                                                                                              |
| `mode`           | `disabled`, `shadow` o `enabled`.                                                                                                                                            |
| `scope`          | Declaración opcional: `omnichannel_generic` o `zappway_livia`; no cambia la identidad seleccionada por el 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?}`. La variante es `control` o `variant`. Los identificadores admiten letras, números, puntos, guiones bajos y guiones, hasta 64 caracteres. |

Ejemplo para combinar con la configuración actual:

```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` combinando el fragmento anterior con el `interfaceConfig` actual obtenido mediante GET autorizado. Envíe únicamente los campos de actualización, no la respuesta GET completa.

```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` contiene el par completo de cookie autenticada (`nombre=valor`) del entorno del dashboard. Esta ruta administrativa rechaza intencionadamente la autenticación mediante API key.

### TypeScript

Ejemplo con una sesión autenticada en el 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');
```

## Buenas prácticas

* Empiece en `shadow`: se observan las decisiones sin modificar los mensajes del modelo. Los experimentos de control también son observacionales.
* Configure un objetivo real. Mantenga la persona, los hechos y las Skills en sus ajustes existentes.
* La declaración de un Flujo se aplica tras un disparo exitoso, únicamente durante el turno actual. No sustituye un objetivo explícito del agente, debilita restricciones, habilita una capa desactivada ni cambia la asignación del experimento.
* Los operadores controlan `COGNITIVE_STRATEGY_MODE`, el apagado de emergencia y la lista opcional de organizaciones. El valor global `disabled` prevalece sobre los ajustes del agente; `shadow` global impide que un agente se promueva a `enabled`. La configuración utiliza la API autenticada existente, sin rediseñar pantallas.

## Solución de problemas

Si nada cambia, compruebe el apagado global, la organización autorizada, el modo del agente y la variante de control. En Livia del dashboard, revise también `PERSONAL_ASSISTANT_COGNITIVE_STRATEGY_MODE` y los controles existentes de despliegue y canario. Las versiones inválidas y los ámbitos incompatibles se rechazan o se omiten de forma segura en el runtime. Sin Customer360 o inteligencia de conversación, se utiliza el contexto disponible. Un fallo de estrategia no interrumpe la atención.

La telemetría registra generación de respuestas y delegación exitosa. No afirma que la respuesta se entregó, que un Flujo terminó ni que hubo una conversión comercial. La eficacia comercial y el ROI requieren la siguiente fase experimental.