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

# Cognitive Strategy

> Optional, contextual conversation guidance for agents and Flow tools.

## Overview

Cognitive Strategy provides a short, structured conversational plan alongside the existing agent instructions, Skills and tools. It is disabled by default. It does not create campaigns, send outreach, change models or execute operations independently.

Generic agents follow the business objective you configure; an absent objective does not imply selling. The internal Livia profile is selected by server identity and cannot be enabled for a customer agent. Interpretation of user language remains with the existing LLM; there are no phrase lists for guessing intent across languages.

## Endpoint reference

| Method | Endpoint                         | Behavior                                                                                                     |
| ------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| PATCH  | `/api/agents/{id}`               | Save typed configuration with the existing `agents.write` permission and organization check.                 |
| GET    | `/api/agents/{id}`               | Authorized organization members can inspect configuration; public readers do not receive cognitive settings. |
| GET    | `/api/external/agents/{agentId}` | Public projection excludes cognitive settings from the agent and Flow tools.                                 |

## Parameters and payloads

Configuration lives in `interfaceConfig.cognitiveStrategy`. A Flow tool can also declare `tools[].config.cognitiveStrategy` in the existing agent update payload. Preserve all existing interface fields and the full tool list when saving; these are not independent configuration endpoints.

| Field            | Values / behavior                                                                                                                                   |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `version`        | Required: `1`.                                                                                                                                      |
| `profileVersion` | `"1"`; defaults to this immutable version.                                                                                                          |
| `mode`           | `disabled`, `shadow`, or `enabled`.                                                                                                                 |
| `scope`          | Optional assertion: `omnichannel_generic` or `zappway_livia`; cannot change server-selected identity.                                               |
| `objective`      | `discover`, `support`, `qualify`, `demonstrate_value`, `activate`, `complete_request`, `convert`, `recover`, `retain`, `expand`, `follow_up`.       |
| `journeyStage`   | Optional: `discovery`, `evaluation`, `decision`, `onboarding`, `ongoing`, `recovery`.                                                               |
| `constraints`    | Optional list: `no_commercial_offer`, `no_follow_up`, `human_only`.                                                                                 |
| `experiment`     | Optional `{id, variant, cohort?}`; variant is `control` or `variant`. IDs use letters, digits, dots, underscores or hyphens, at most 64 characters. |

Example fragment to merge into the current configuration:

```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` by merging the fragment above into the authorized GET response's current `interfaceConfig`. Send only the update fields, not the complete GET response.

```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` is the complete authenticated cookie pair (`name=value`) for the dashboard environment. This administration route intentionally rejects API-key authentication.

### TypeScript

This example uses an already authenticated dashboard session.

```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');
```

## Best practices

* Start in shadow mode: decisions are observed without modifying model messages. Control experiments also remain observational.
* Configure a real business objective. Keep persona, factual knowledge and procedural Skills in their existing settings.
* Flow declarations apply only after a successful trigger, to the current agent turn. They cannot override an explicit agent objective, weaken constraints, enable a disabled layer or replace the experiment assignment.
* Deployment operators control `COGNITIVE_STRATEGY_MODE`, the emergency switch and an optional organization allowlist. Global `disabled` overrides agent settings, while global `shadow` prevents an agent setting from promoting itself to `enabled`. No UI redesign is required; authoring uses the existing authenticated agent configuration API.

## Troubleshooting

If nothing changes, check global shutdown, organization rollout, agent mode and experiment control status. For dashboard Livia also check `PERSONAL_ASSISTANT_COGNITIVE_STRATEGY_MODE` and existing Personal Assistant rollout/canary gates. An invalid version or mismatched scope is rejected or skipped safely at runtime. Missing Customer360 or conversation intelligence degrades to available context. A strategy failure does not fail the conversation.

Outcome telemetry measures observed response generation and successful delegation. It does not claim that a generated response was delivered, that a Flow finished, or that a commercial conversion happened. Commercial effectiveness and ROI require the later experiment phase.