> ## Documentation Index
> Fetch the complete documentation index at: https://claritylabs.inc/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Building Modular Insurance Agent System Prompts in CL SDK

> Compose modular, platform-aware system prompts for insurance agents using buildAgentSystemPrompt and the individual prompt module functions.

CL SDK provides a modular prompt system purpose-built for insurance-aware conversational agents. Rather than maintaining a monolithic system prompt string, you compose it from independent modules — identity, intent, formatting, safety, coverage gaps, COI routing, and more. Each module is platform-aware and intent-aware, so the same `buildAgentSystemPrompt` call produces appropriately different behavior for an email agent, a Slack bot, and an SMS assistant.

## Quick Start

```typescript theme={"system"}
import { buildAgentSystemPrompt } from "@claritylabs/cl-sdk";
import type { AgentContext } from "@claritylabs/cl-sdk";

const ctx: AgentContext = {
  platform: "email",
  intent: "direct",
  siteUrl: "https://app.example.com",
  companyName: "Acme Insurance",
  userName: "Jane Smith",
};

const systemPrompt = buildAgentSystemPrompt(ctx);
```

Pass `systemPrompt` as the `system` parameter to your LLM provider call. The output is a plain string — no special formatting required.

## AgentContext Reference

**platform** `string` *required*

The communication channel this agent operates on. Affects formatting rules and link guidance.
One of: `"email"` | `"chat"` | `"sms"` | `"slack"` | `"discord"`

**intent** `string` *required*

Behavioral mode for the agent. Controls how the agent presents itself and what actions it takes autonomously.
One of: `"direct"` | `"mediated"` | `"observed"`

**siteUrl** `string` *required*

Base URL of your application. Used in link guidance and COI routing instructions.

**companyName** `string`

Display name for your organization. Appears in the identity module.

**companyContext** `string`

Free-form organization-specific context injected into the identity module. Use this to describe your book of business, customer base, or specialized lines.

**userName** `string`

Name of the user the agent is speaking with. Used for personalization in the identity module.

**agentName** `string`

Display name for the agent. Defaults to `"CL-0 Agent"` if not provided.

**coiHandling** `string`

Controls COI routing instructions. One of: `"broker"` | `"user"` | `"member"` | `"ignore"`

**brokerName** `string`

Name of the broker organization, used in COI routing and mediated intent modules.

**brokerContactName** `string`

Broker contact's full name for escalation instructions.

**brokerContactEmail** `string`

Broker contact's email address for escalation routing.

**platformConfig** `PlatformConfig`

Advanced per-platform configuration for output formatting. See platform-specific options below.

**linkGuidance** `string`

Custom override for link formatting instructions. Replaces the default guidance derived from `platform` and `siteUrl`.

## Prompt Modules

`buildAgentSystemPrompt` composes the following modules in order. Each module is a function you can also call individually for custom compositions.

**1. Identity**

Establishes who the agent is, the company it works for, and any organization-specific context. Sets the agent's name and scopes its expertise to insurance.

**2. Intent**

Applies behavioral rules based on the `intent` value. `direct` — speaks and acts as the primary point of contact. `mediated` — acts on behalf of a broker, surfaces broker contact for escalations. `observed` — summarizes and routes, does not make commitments.

**3. Formatting**

Platform-specific output rules. Email agents produce well-structured prose with salutations. Chat and Slack agents use markdown. SMS agents avoid markdown entirely and keep responses short.

**4. Safety**

Scope guardrails that restrict the agent to insurance topics. Anti-hallucination rules that require citing evidence before stating coverage facts. Prompt injection defenses that prevent instruction override via user messages.

**5. Coverage Gaps**

Guidance for proactively identifying and surfacing gaps in coverage when comparing quotes or reviewing policy documents.

**6. COI Routing**

Instructions for handling certificate of insurance requests based on the `coiHandling` setting. Routes requests to the appropriate party or self-serves generation when permitted.

**7. Quotes and Policies**

Guidance on correctly differentiating between quote documents and bound policy documents, and appropriate language for each.

**8. Memory**

Instructions for using conversation history to provide continuity across sessions without re-asking for information the user has already provided.

## Custom Module Composition

Call individual module builders when you need to add, remove, or reorder modules for a specialized agent.

```typescript theme={"system"}
import {
  buildIdentityPrompt,
  buildSafetyPrompt,
  buildFormattingPrompt,
  buildCoverageGapPrompt,
  buildCoiRoutingPrompt,
  buildQuotesPoliciesPrompt,
  buildConversationMemoryGuidance,
  buildIntentPrompt,
} from "@claritylabs/cl-sdk";

// Custom composition: skip COI routing, add a custom section
const customPrompt = [
  buildIdentityPrompt(ctx),
  buildIntentPrompt(ctx),
  buildFormattingPrompt(ctx),
  buildSafetyPrompt(ctx),
  buildCoverageGapPrompt(ctx),
  buildQuotesPoliciesPrompt(ctx),
  buildConversationMemoryGuidance(ctx),
  "## Custom Instructions\nAlways recommend reviewing the declarations page first.",
]
  .filter(Boolean)
  .join("\n\n");
```

> [!NOTE]
>
> Each module function returns a string or `null`. Filtering out `null` values before joining ensures you don't get blank sections when a module has nothing to contribute for a given context.

## Intent Classification

When your pipeline receives inbound messages (emails, chat messages) and needs to route them before calling the agent, use `buildClassifyMessagePrompt` to generate a classification prompt.

```typescript theme={"system"}
import { buildClassifyMessagePrompt } from "@claritylabs/cl-sdk";

const classificationPrompt = buildClassifyMessagePrompt("email");

const { object } = await generateObject({
  model: yourModel,
  system: classificationPrompt,
  prompt: inboundEmailBody,
  schema: MessageClassificationSchema,
});
// object.intent, object.documentIds, object.requestType
```

## Platform Behavior Reference

**email**

* Produces full salutation and sign-off
* Uses structured sections with bold headers
* Includes policy numbers and document references inline
* Provides full links with descriptive anchor text

**chat**

* Uses markdown headings and bullet lists
* Keeps responses conversational and concise
* Renders inline code for policy numbers
* Short links are acceptable

**sms**

* No markdown whatsoever
* Responses under 320 characters when possible
* Spell out numbers and codes rather than formatting them
* Links only when essential

**slack / discord**

* Uses Slack/Discord markdown flavors
* Emoji are acceptable for status indicators
* Uses `@mention` format for escalations when a broker contact is configured
* Thread replies for long responses


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.