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

# Logging System Prompts (TypeScript)

> System prompt for coding agents to upgrade an existing TypeScript SDK integration to log system prompts for prompt optimization. Copy and paste the content of this page into your coding assistant.

export const CopyAllButton = ({content, label = 'Copy Page'}) => {
  const [copied, setCopied] = React.useState(false);
  const handleCopy = async () => {
    try {
      await navigator.clipboard.writeText(content);
      setCopied(true);
      setTimeout(() => setCopied(false), 3000);
    } catch (err) {
      console.error('Failed to copy content:', err);
      alert('Failed to copy content. Please try selecting and copying manually.');
    }
  };
  return <div className="copy-all-container">
      <div className="copy-all-content">
        <div className="copy-all-title">Copy Integration Instructions</div>
        <div className="copy-all-description">
          Click to copy the entire page content to paste into your AI coding
          assistant
        </div>
      </div>
      <button className={`copy-all-button${copied ? ' copied' : ''}`} onClick={handleCopy} type="button">
        {copied ? 'Page Copied' : label}
      </button>
    </div>;
};

<Tip>
  **Using a Skills-compatible agent like Claude Code?** The [Greenflash agent skill](/features/agent-skill) handles this automatically. Run `/greenflash-onboard-prompts` instead of copying this prompt.
</Tip>

export const pageContent = `# Upgrade an Existing TypeScript SDK Integration to Log System Prompts

You are a **coding agent** tasked with updating our existing TypeScript SDK integration with the **Greenflash Messages API** so that it correctly logs **system prompts** for **prompt optimization & management**. We already have a working integration but are not currently submitting any system prompts alongside messages. Your goal is to **enhance our integration** so that Greenflash can automatically version, analyze, and optimize system prompts based on real conversation data.

---

## High-Level Objective

Refactor or extend the existing implementation to:

1. **Include system prompts** when logging conversations
2. **Support both simple string prompts and structured \\\`promptComponents\\\`**
3. **Ensure dynamic and variable content in complex prompts is logged properly**
4. **Use the correct TypeScript SDK syntax**
5. **Determine the right logging pattern** (batch vs individual calls) based on how the existing code is written

This is not a correction of our current setup; it is an **evolution** toward richer analytic and optimization tooling.

---

## Logging System Prompts: Two Valid Formats

Greenflash supports **two ways** to include a system prompt when logging a conversation. You must choose between them based on the complexity of the prompt being submitted.

### Option A: Simple String Prompt

Use this when the system prompt is a *single static string*.

\\\`\\\`\\\`typescript
// Fire-and-forget (recommended for logging)
client.messages.create({
  externalUserId: userId,
  externalConversationId: convoId,
  productId: productId,
  systemPrompt: "You are a helpful assistant. Be concise and friendly.",
  messages: [ ... ],
}).catch(err => console.error('Greenflash error:', err));

// Or with await if you need to wait for the response
await client.messages.create({
  externalUserId: userId,
  externalConversationId: convoId,
  productId: productId,
  systemPrompt: "You are a helpful assistant. Be concise and friendly.",
  messages: [ ... ],
});
\\\`\\\`\\\`

**Pros:**

- Easy to implement
- Automatically gets tracked & versioned
- Good for most use cases

**Cons:**

- Cannot express structured or dynamic prompts
- Less granular optimization

Use this when prompts are simple, static strings.

### Option B: Structured Prompt with promptComponents

Use this when the prompt includes multiple pieces, variables, dynamic slots, templates, or RAG context elements. A structured prompt lets you segment instructions into named components, version them independently, and optimize at the component level.

\\\`\\\`\\\`typescript
const systemPrompt = {
  externalTemplateId: "my-assistant-prompt",
  components: [
    {
      type: "system",
      name: "base_instructions",
      content: "You are a customer support assistant for {{company}}."
    },
    {
      type: "system",
      name: "tone_guidelines",
      content: "Always be professional and empathetic."
    },
    {
      type: "rag",
      name: "context",
      content: dynamicRagText,
      isDynamic: true
    }
  ],
  variables: {
    customerName: customerName,
    company: companyName
  }
};

// Fire-and-forget (recommended for logging)
client.messages.create({
  externalUserId: userId,
  externalConversationId: convoId,
  productId: productId,
  systemPrompt: systemPrompt,
  messages: [ ... ],
}).catch(err => console.error('Greenflash error:', err));
\\\`\\\`\\\`

**Key Notes for Structured Prompts:**

- **\\\`externalTemplateId\\\`** groups all versions of this prompt under a single lineage. Use a stable, human-readable identifier (e.g., \\\`"customer-support-agent"\\\`). Without this, each unique prompt creates a separate lineage.
- Valid component **\\\`type\\\`** values: \\\`system\\\`, \\\`user\\\`, \\\`tool\\\`, \\\`guardrail\\\`, \\\`rag\\\`, \\\`agent\\\`, \\\`other\\\`. Each component can also have a **\\\`source\\\`**: \\\`customer\\\` (default), \\\`participant\\\`, \\\`greenflash\\\`, or \\\`agent\\\`.
- Use \\\`isDynamic: true\\\` for parts of the prompt that vary per conversation (e.g., retrieved context, dynamic instructions)
- Use \\\`variables\\\` on the systemPrompt object to pass template variable values (e.g., \\\`{{companyName}}\\\`)

**Advantages:**

- Modular prompt structure
- Component-level optimization
- Variable interpolation
- Dynamic content slots for RAG or agent outputs

Use this when prompts are complex, have templates, or contain dynamic data.

---

## Fire-and-Forget Logging

For logging, you typically don't want to block your LLM response while waiting for the Greenflash API call to complete. Use fire-and-forget by not awaiting the promise:

\\\`\\\`\\\`typescript
// Fire-and-forget: don't await, just add .catch() to handle errors
client.messages.create({
  externalUserId: userId,
  externalConversationId: convoId,
  productId: productId,
  systemPrompt: systemPrompt,
  messages: messageList,
}).catch(err => console.error('Greenflash logging error:', err));
\\\`\\\`\\\`

> **Note:** The \\\`.catch()\\\` is recommended to prevent unhandled promise rejections from crashing your app, but the logging call runs in the background without blocking your response.

---

## Detecting the Right Pattern

Inspect the existing codebase and choose the pattern that minimally disrupts current logic:

- If prompts are static strings and there is no variable logic or dynamic content, use **Simple String Format**
- If prompts are assembled from pieces, templates, or dynamic slots, use **Structured Prompt with Components**
- If code emits prompt text dynamically as it runs, wrap that logic into structured components with \\\`isDynamic: true\\\` where needed

Once the pattern is chosen, update the logging logic accordingly.

---

## Logging Messages with Prompts

After adding the system prompt, the rest of the messages follow the existing logging pattern:

- You may send all messages in a batch if they are known at the end of execution
- Or you may log messages incrementally as they happen (e.g., streaming)
- Use \\\`client.messages.create(...)\\\` for each call when logging incrementally
- For batch mode, send a single call with \\\`systemPrompt\\\` and message array

Either approach is valid — choose what aligns best with the existing code flow.

---

## TypeScript SDK Integration Checklist

Your code should:

1. **Initialize the TypeScript SDK** with our API key
2. **Construct \\\`systemPrompt\\\`**:
   - As a simple string, or
   - As a structured object with \\\`promptComponents\\\`
3. **Include \\\`systemPrompt\\\`** on every \\\`messages.create(...)\\\` call
4. **Respect dynamic variables** using \\\`variables\\\` on the systemPrompt object if structured prompts have templates
5. **Choose batching vs streaming** appropriately
6. **Preserve existing logging semantics** for message bodies
7. **Use fire-and-forget pattern** (no \\\`await\\\`) with \\\`.catch()\\\` to avoid blocking LLM responses

**Example with variables (fire-and-forget):**

\\\`\\\`\\\`typescript
const systemPromptWithVars = {
  externalTemplateId: "my-assistant-prompt",
  components: [/* your prompt components */],
  variables: {
    userName: userName,
    companyName: companyName
  }
};

client.messages.create({
  externalUserId: userId,
  externalConversationId: conversationId,
  productId: productId,
  systemPrompt: systemPromptWithVars,
  messages: messageList,
}).catch(err => console.error('Greenflash error:', err));
\\\`\\\`\\\`

**Example with variables (awaited):**

\\\`\\\`\\\`typescript
const systemPromptWithVars = {
  externalTemplateId: "my-assistant-prompt",
  components: [/* your prompt components */],
  variables: {
    userName: userName,
    companyName: companyName
  }
};

await client.messages.create({
  externalUserId: userId,
  externalConversationId: conversationId,
  productId: productId,
  systemPrompt: systemPromptWithVars,
  messages: messageList,
});
\\\`\\\`\\\`

---

## Tips

- **String prompts** are great to start with and will get metrics and analytics immediately
- **Structured prompts** unlock component-level optimization and versioning
- **Dynamic components** (\\\`isDynamic: true\\\`) allow RAG and other runtime context to be logged correctly
- **Interpolated variables** let you keep templates generic while capturing personalized conversation data

---

## Summary of What to Deliver

- Updated TypeScript SDK integration that logs system prompts
- Support for both simple string prompts and structured prompt components
- Logic to choose the right pattern
- Ensure dynamic data and variables are logged properly
- No disruption to existing message logging behavior

This will unlock Greenflash's prompt optimization capabilities across our AI products.`;

<CopyAllButton content={pageContent} />

# Upgrade an Existing TypeScript SDK Integration to Log System Prompts

You are a **coding agent** tasked with updating our existing TypeScript SDK integration with the **Greenflash Messages API** so that it correctly logs **system prompts** for **prompt optimization & management**. We already have a working integration but are not currently submitting any system prompts alongside messages. Your goal is to **enhance our integration** so that Greenflash can automatically version, analyze, and optimize system prompts based on real conversation data.

***

## High-Level Objective

Refactor or extend the existing implementation to:

1. **Include system prompts** when logging conversations
2. **Support both simple string prompts and structured `promptComponents`**
3. **Ensure dynamic and variable content in complex prompts is logged properly**
4. **Use the correct TypeScript SDK syntax**
5. **Determine the right logging pattern** (batch vs individual calls) based on how the existing code is written

This is not a correction of our current setup; it is an **evolution** toward richer analytic and optimization tooling.

***

## Logging System Prompts: Two Valid Formats

Greenflash supports **two ways** to include a system prompt when logging a conversation. You must choose between them based on the complexity of the prompt being submitted.

### Option A: Simple String Prompt

Use this when the system prompt is a *single static string*.

```typescript theme={"theme":{"light":"github-light","dark":"vesper"}}
// Fire-and-forget (recommended for logging)
client.messages.create({
  externalUserId: userId,
  externalConversationId: convoId,
  productId: productId,
  systemPrompt: "You are a helpful assistant. Be concise and friendly.",
  messages: [ ... ],
}).catch(err => console.error('Greenflash error:', err));

// Or with await if you need to wait for the response
await client.messages.create({
  externalUserId: userId,
  externalConversationId: convoId,
  productId: productId,
  systemPrompt: "You are a helpful assistant. Be concise and friendly.",
  messages: [ ... ],
});
```

**Pros:**

* Easy to implement
* Automatically gets tracked & versioned
* Good for most use cases

**Cons:**

* Cannot express structured or dynamic prompts
* Less granular optimization

Use this when prompts are simple, static strings.

### Option B: Structured Prompt with promptComponents

Use this when the prompt includes multiple pieces, variables, dynamic slots, templates, or RAG context elements. A structured prompt lets you segment instructions into named components, version them independently, and optimize at the component level.

```typescript theme={"theme":{"light":"github-light","dark":"vesper"}}
const systemPrompt = {
  externalTemplateId: "my-assistant-prompt",
  components: [
    {
      type: "system",
      name: "base_instructions",
      content: "You are a customer support assistant for {{company}}."
    },
    {
      type: "system",
      name: "tone_guidelines",
      content: "Always be professional and empathetic."
    },
    {
      type: "rag",
      name: "context",
      content: dynamicRagText,
      isDynamic: true
    }
  ],
  variables: {
    customerName: customerName,
    company: companyName
  }
};

// Fire-and-forget (recommended for logging)
client.messages.create({
  externalUserId: userId,
  externalConversationId: convoId,
  productId: productId,
  systemPrompt: systemPrompt,
  messages: [ ... ],
}).catch(err => console.error('Greenflash error:', err));
```

**Key Notes for Structured Prompts:**

* **`externalTemplateId`** groups all versions of this prompt under a single lineage. Use a stable, human-readable identifier (e.g., `"customer-support-agent"`). Without this, each unique prompt creates a separate lineage.
* Valid component **`type`** values: `system`, `user`, `tool`, `guardrail`, `rag`, `agent`, `other`. Each component can also have a **`source`**: `customer` (default), `participant`, `greenflash`, or `agent`.
* Use `isDynamic: true` for parts of the prompt that vary per conversation (e.g., retrieved context, dynamic instructions)
* Use `variables` on the systemPrompt object to pass template variable values (e.g., `{{companyName}}`)

**Advantages:**

* Modular prompt structure
* Component-level optimization
* Variable interpolation
* Dynamic content slots for RAG or agent outputs

Use this when prompts are complex, have templates, or contain dynamic data.

***

## Fire-and-Forget Logging

For logging, you typically don't want to block your LLM response while waiting for the Greenflash API call to complete. Use fire-and-forget by not awaiting the promise:

```typescript theme={"theme":{"light":"github-light","dark":"vesper"}}
// Fire-and-forget: don't await, just add .catch() to handle errors
client.messages.create({
  externalUserId: userId,
  externalConversationId: convoId,
  productId: productId,
  systemPrompt: systemPrompt,
  messages: messageList,
}).catch(err => console.error('Greenflash logging error:', err));
```

> **Note:** The `.catch()` is recommended to prevent unhandled promise rejections from crashing your app, but the logging call runs in the background without blocking your response.

***

## Detecting the Right Pattern

Inspect the existing codebase and choose the pattern that minimally disrupts current logic:

* If prompts are static strings and there is no variable logic or dynamic content, use **Simple String Format**
* If prompts are assembled from pieces, templates, or dynamic slots, use **Structured Prompt with Components**
* If code emits prompt text dynamically as it runs, wrap that logic into structured components with `isDynamic: true` where needed

Once the pattern is chosen, update the logging logic accordingly.

***

## Logging Messages with Prompts

After adding the system prompt, the rest of the messages follow the existing logging pattern:

* You may send all messages in a batch if they are known at the end of execution
* Or you may log messages incrementally as they happen (e.g., streaming)
* Use `client.messages.create(...)` for each call when logging incrementally
* For batch mode, send a single call with `systemPrompt` and message array

Either approach is valid — choose what aligns best with the existing code flow.

***

## TypeScript SDK Integration Checklist

Your code should:

1. **Initialize the TypeScript SDK** with our API key
2. **Construct `systemPrompt`**:
   * As a simple string, or
   * As a structured object with `promptComponents`
3. **Include `systemPrompt`** on every `messages.create(...)` call
4. **Respect dynamic variables** using `variables` on the systemPrompt object if structured prompts have templates
5. **Choose batching vs streaming** appropriately
6. **Preserve existing logging semantics** for message bodies
7. **Use fire-and-forget pattern** (no `await`) with `.catch()` to avoid blocking LLM responses

**Example with variables (fire-and-forget):**

```typescript theme={"theme":{"light":"github-light","dark":"vesper"}}
const systemPromptWithVars = {
  externalTemplateId: "my-assistant-prompt",
  components: [/* your prompt components */],
  variables: {
    userName: userName,
    companyName: companyName
  }
};

client.messages.create({
  externalUserId: userId,
  externalConversationId: conversationId,
  productId: productId,
  systemPrompt: systemPromptWithVars,
  messages: messageList,
}).catch(err => console.error('Greenflash error:', err));
```

**Example with variables (awaited):**

```typescript theme={"theme":{"light":"github-light","dark":"vesper"}}
const systemPromptWithVars = {
  externalTemplateId: "my-assistant-prompt",
  components: [/* your prompt components */],
  variables: {
    userName: userName,
    companyName: companyName
  }
};

await client.messages.create({
  externalUserId: userId,
  externalConversationId: conversationId,
  productId: productId,
  systemPrompt: systemPromptWithVars,
  messages: messageList,
});
```

***

## Tips

* **String prompts** are great to start with and will get metrics and analytics immediately
* **Structured prompts** unlock component-level optimization and versioning
* **Dynamic components** (`isDynamic: true`) allow RAG and other runtime context to be logged correctly
* **Interpolated variables** let you keep templates generic while capturing personalized conversation data

***

## Summary of What to Deliver

* Updated TypeScript SDK integration that logs system prompts
* Support for both simple string prompts and structured prompt components
* Logic to choose the right pattern
* Ensure dynamic data and variables are logged properly
* No disruption to existing message logging behavior

This will unlock Greenflash's prompt optimization capabilities across our AI products.