Cognitive Strategy

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:

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

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.

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.

Agent Skills

Agent Cortex

Livia - 360 Assistant

Conversations

VoiceFlux

Access Groups

Overview

Endpoint reference

Parameters and payloads

cURL

TypeScript

Best practices

Troubleshooting

​Overview

​Endpoint reference

​Parameters and payloads

​cURL

​TypeScript

​Best practices

​Troubleshooting

Overview

Endpoint reference

Parameters and payloads

cURL

TypeScript

Best practices

Troubleshooting