Agent Cortex

What you will learn: This page explains what the Agent Cortex is, the three operating modes (passive, advisory, active), how to configure the mode for each AI Employee, and how it interacts with the Agent Skills system.

🔢 Table of Contents

Overview
How the Cortex Works
Cortex Modes
Configure the Cortex Mode
Cortex + Skills Integration
Endpoint Reference
Response Format
Best Practices
Troubleshooting

1. Overview

What is the Agent Cortex?

The Agent Cortex is an intelligent reasoning layer built into every ZappWay AI Employee. At its core, it answers one question before every AI response:

“Given the current conversation context, which skill should the AI apply right now?”

Without the Cortex, your AI responds using only its base prompt and knowledge base. With the Cortex active, the AI dynamically selects the most relevant Agent Skill for each incoming message and injects its instructions into the response context.

Why It Matters

In real-world conversations, users don’t always ask the same type of question. A support conversation might shift from a billing inquiry to a technical issue within minutes. The Cortex allows your AI to:

Adapt automatically to topic shifts within a conversation
Apply specialized knowledge only when it’s needed
Reduce prompt length by loading specific skills on demand instead of putting everything in the base prompt
Improve response accuracy by providing focused, situation-specific instructions

2. How the Cortex Works

User sends message
       ↓
Cortex reads all ACTIVE skills for this agent
       ↓
Semantic matching: Which skill is most relevant?
       ↓
┌─────────────────────────────────┐
│ passive mode → skip             │
│ advisory mode → suggest         │
│ active mode  → inject + respond │
└─────────────────────────────────┘
       ↓
AI generates response (with or without skill context)

What the Cortex Reads

The Cortex considers:

The current message from the user
Recent conversation history (context window)
All active skills for the agent (and organization-scoped skills)
Skill descriptions — used as the semantic matching signal

The description field of each skill is the primary signal the Cortex uses to select the right skill. Always write clear, specific descriptions.

3. Cortex Modes

The Cortex has three operating modes that control how autonomously it selects and applies skills.

`passive` — Cortex Off

The Cortex does not evaluate or apply skills. The AI responds using only its base prompt and knowledge base. Use when:

Your AI has a single, focused purpose with no need for dynamic behavior
You’re setting up the agent and haven’t built a skill library yet
You want full manual control over the AI’s behavior

Effect: Skills exist in the system but are never selected or injected.

`advisory` — Cortex Observes

The Cortex evaluates active skills and suggests which one is most relevant, but does not automatically inject it. This mode is ideal for testing your skill library before going to production. Use when:

You want to observe which skills the Cortex selects without affecting live conversations
You’re reviewing skill coverage and quality
You’re building confidence before activating the Cortex fully

Effect: The Cortex makes a skill selection decision but surfaces it only in developer/observability tools, not in the live AI response.

`active` — Cortex On

The Cortex automatically evaluates active skills and injects the most relevant one into the AI’s context before every response generation. Use when:

You have a well-tested skill library with at least 3–5 active skills
Your conversations cover diverse topics or require situation-specific behaviors
You want the AI to adapt automatically without manual intervention

Effect: Every AI response is enriched with the most contextually relevant skill. If no skill matches well, the AI falls back to its base prompt.

4. Configure the Cortex Mode

Get Current Mode

GET /api/agents/{agentId}/skills/cortex-mode

Response:

{
  "configuredMode": "advisory",
  "effectiveMode": "advisory"
}

Field	Description
`configuredMode`	The mode you explicitly configured
`effectiveMode`	The mode actually in effect (may differ during rollout transitions)

Set Mode

PATCH /api/agents/{agentId}/skills/cortex-mode
Content-Type: application/json

Request Body:

{
  "mode": "active"
}

Valid values: "passive", "advisory", "active" cURL:

curl -X PATCH "https://your-domain.com/api/agents/agent_123/skills/cortex-mode" \
  -H "Content-Type: application/json" \
  -H "Cookie: next-auth.session-token=YOUR_SESSION_TOKEN" \
  -d '{"mode": "active"}'

TypeScript:

const response = await fetch(`/api/agents/${agentId}/skills/cortex-mode`, {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ mode: 'active' }),
});

const result = await response.json();
// { configuredMode: 'active', effectiveMode: 'active' }

5. Cortex + Skills Integration

The Cortex works exclusively with the Agent Skills system. To use the Cortex effectively:

Step 1: Create Skills

Create at least 3–5 active skills for your agent. Each skill should cover a distinct scenario your AI might encounter. → See Agent Skills for how to create skills.

Step 2: Activate Skills

Ensure each skill has status: "active". Skills in draft or archived status are ignored by the Cortex.

Step 3: Write Clear Descriptions

The description field is the primary matching signal for the Cortex. Write descriptions that clearly answer: “When should this skill activate?” Good description:

“When the customer mentions a billing error, unexpected charge, refund request, or payment dispute.”

Poor description:

“For billing things.”

Step 4: Set Mode to `advisory` First

Test in advisory mode before going active. Observe which skills are being selected in your analytics/logs.

Step 5: Promote to `active`

Once satisfied with skill coverage and selection accuracy, set the mode to active.

6. Endpoint Reference

Method	Endpoint	Description	Auth
`GET`	`/api/agents/[id]/skills/cortex-mode`	Get current Cortex mode	`agent_skills.read` OR `agents.read`
`PATCH`	`/api/agents/[id]/skills/cortex-mode`	Set Cortex mode	`agent_skills.manage` OR `agents.write`

7. Response Format

Success Response

{
  "configuredMode": "active",
  "effectiveMode": "active"
}

Error Responses

Status	Body	Cause
`400`	`{ "error": "Invalid mode" }`	Mode value is not `passive`, `advisory`, or `active`
`404`	`{ "error": "Agent not found for organization." }`	`agentId` does not belong to your organization
`403`	`{ "error": "Forbidden" }`	Insufficient permissions

8. Best Practices

Mode Selection Guide

Situation	Recommended Mode
New agent, no skills yet	`passive`
Building and testing skill library	`advisory`
Production agent with 3+ active skills	`active`
Agent with single, focused purpose (e.g., FAQ bot)	`passive` or `active` with 1–2 skills
Agent handling diverse topics (support, sales, info)	`active` with 5–15 skills

Skill Coverage for Active Mode

For the Cortex to work well in active mode:

Minimum: 3 active skills covering your most common conversation types
Recommended: 5–15 skills with distinct, non-overlapping descriptions
Avoid: Extremely similar descriptions (the Cortex may select inconsistently)

Testing with Advisory Mode

Use advisory mode to answer:

Is the Cortex selecting the right skill for each conversation type?
Are there conversation topics where no skill matches?
Are any skill descriptions too similar, causing the wrong skill to be selected?

9. Troubleshooting

Problem	Possible Cause	Solution
Cortex seems to always select the same skill	Skills have overlapping descriptions	Make each skill’s `description` more specific and distinct
Cortex never selects a skill	Mode is `passive`	Change mode to `advisory` or `active`
`effectiveMode` differs from `configuredMode`	A rollout transition is in progress	Wait briefly and check again; contact support if persists
AI ignores skills in active mode	Skills have `draft` or `archived` status	Change skill status to `active`
No improvement in responses after enabling Cortex	Skill `content` is too generic	Rewrite skill content with specific, actionable step-by-step instructions

Agent Skills

Livia - 360 Assistant

Conversations

Access Groups

Agent Cortex

🔢 Table of Contents

1. Overview

What is the Agent Cortex?

Why It Matters

2. How the Cortex Works

What the Cortex Reads

3. Cortex Modes

`passive` — Cortex Off

`advisory` — Cortex Observes

`active` — Cortex On

4. Configure the Cortex Mode

Get Current Mode

Set Mode

5. Cortex + Skills Integration

Step 1: Create Skills

Step 2: Activate Skills

Step 3: Write Clear Descriptions

Step 4: Set Mode to `advisory` First

Step 5: Promote to `active`

6. Endpoint Reference

7. Response Format

Success Response

Error Responses

8. Best Practices

Mode Selection Guide

Skill Coverage for Active Mode

Testing with Advisory Mode

9. Troubleshooting

​🔢 Table of Contents

​1. Overview

​What is the Agent Cortex?

​Why It Matters

​2. How the Cortex Works

​What the Cortex Reads

​3. Cortex Modes

​passive — Cortex Off

​advisory — Cortex Observes

​active — Cortex On

​4. Configure the Cortex Mode

​Get Current Mode

​Set Mode

​5. Cortex + Skills Integration

​Step 1: Create Skills

​Step 2: Activate Skills

​Step 3: Write Clear Descriptions

​Step 4: Set Mode to advisory First

​Step 5: Promote to active

​6. Endpoint Reference

​7. Response Format

​Success Response

​Error Responses

​8. Best Practices

​Mode Selection Guide

​Skill Coverage for Active Mode

​Testing with Advisory Mode

​9. Troubleshooting

🔢 Table of Contents

1. Overview

What is the Agent Cortex?

Why It Matters

2. How the Cortex Works

What the Cortex Reads

3. Cortex Modes

`passive` — Cortex Off

`advisory` — Cortex Observes

`active` — Cortex On

4. Configure the Cortex Mode

Get Current Mode

Set Mode

5. Cortex + Skills Integration

Step 1: Create Skills

Step 2: Activate Skills

Step 3: Write Clear Descriptions

Step 4: Set Mode to `advisory` First

Step 5: Promote to `active`

6. Endpoint Reference

7. Response Format

Success Response

Error Responses

8. Best Practices

Mode Selection Guide

Skill Coverage for Active Mode

Testing with Advisory Mode

9. Troubleshooting