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

# Agent Cortex

> The Agent Cortex is the autonomous reasoning layer of your AI Employee — it reads active skills and selects the most contextually relevant one at runtime, enabling proactive and adaptive behavior.

> **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

1. [Overview](#1-overview)
2. [How the Cortex Works](#2-how-the-cortex-works)
3. [Cortex Modes](#3-cortex-modes)
4. [Configure the Cortex Mode](#4-configure-the-cortex-mode)
5. [Cortex + Skills Integration](#5-cortex--skills-integration)
6. [Endpoint Reference](#6-endpoint-reference)
7. [Response Format](#7-response-format)
8. [Best Practices](#8-best-practices)
9. [Troubleshooting](#9-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:

1. **The current message** from the user
2. **Recent conversation history** (context window)
3. **All active skills** for the agent (and organization-scoped skills)
4. **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

```bash theme={null}
GET /api/agents/{agentId}/skills/cortex-mode
```

**Response:**

```json theme={null}
{
  "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

```bash theme={null}
PATCH /api/agents/{agentId}/skills/cortex-mode
Content-Type: application/json
```

**Request Body:**

```json theme={null}
{
  "mode": "active"
}
```

**Valid values:** `"passive"`, `"advisory"`, `"active"`

**cURL:**

```bash theme={null}
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:**

```ts theme={null}
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](/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

```json theme={null}
{
  "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:

1. Is the Cortex selecting the right skill for each conversation type?
2. Are there conversation topics where no skill matches?
3. 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 |