Add new SystemPrompt type support to OpenAI Model provider

[Unshure]

Overview

Add new SystemPrompt type support to OpenAI Model provider.

Background

The systemPrompt type was recently updated from a simple string to SystemPrompt = string | SystemContentBlock[] to support advanced features like prompt caching with cache points. The Bedrock model provider has been updated to support this new type, and now the OpenAI model provider needs the same update.

Implementation Requirements

Technical Context

• Type Definition: SystemPrompt = string | SystemContentBlock[] (defined in src/types/messages.ts)
• SystemContentBlock: TextBlock | CachePointBlock
• Reference Implementation: Bedrock model provider (src/models/bedrock.ts, lines 352-372)
• Target File: src/models/openai.ts (specifically the _formatRequest method, lines 400-407)

Required Changes

1. Update _formatRequest Method in src/models/openai.ts

The current implementation (lines 400-407) only handles string systemPrompt:

if (options?.systemPrompt && options.systemPrompt.trim().length > 0) {
  request.messages.push({
    role: 'system',
    content: options.systemPrompt,
  })
}

New Implementation Must:

1. Handle String SystemPrompt (existing behavior):

   • Continue to work as-is for backward compatibility
   • Validate non-empty after trimming

2. Handle Array SystemPrompt (new behavior):

   • Check if options.systemPrompt is an array
   • Extract text from all TextBlock elements
   • Concatenate text blocks to preserve structure
   • Add warning when CachePointBlock elements are present
   • Skip adding system message if array is empty or contains no text

3. Cache Point Handling:

   • Emit console.warn when cache points are encountered
   • Warning message: "Cache points are not supported in OpenAI system prompts and will be ignored."
   • Rationale: OpenAI's Chat Completions API doesn't support prompt caching like Bedrock

2. Add Tests in src/models/__tests__/openai.test.ts

Follow the test patterns established in src/models/__tests__/bedrock.test.ts (lines 774-870):

Required Test Cases:

1. Array with text blocks only:

   • Multiple text blocks should be concatenated
   • Verify system message content is correctly formatted

2. Array with cache points:

   • Should warn about unsupported cache points
   • Should extract and use only text blocks
   • Verify warning message is logged

3. Empty array:

   • Should not add system message to request
   • Verify no system message in formatted request

4. Array with single text block:

   • Should work correctly as valid system prompt

Implementation Approach

Pattern to Follow:

// Pseudo-code based on Bedrock pattern
if (options?.systemPrompt !== undefined) {
  if (typeof options.systemPrompt === 'string') {
    // Existing string handling
    if (options.systemPrompt.trim().length > 0) {
      request.messages.push({
        role: 'system',
        content: options.systemPrompt,
      })
    }
  } else if (options.systemPrompt.length > 0) {
    // New array handling
    const textBlocks: string[] = []
    let hasCachePoints = false
    
    for (const block of options.systemPrompt) {
      if (block.type === 'textBlock') {
        textBlocks.push(block.text)
      } else if (block.type === 'cachePointBlock') {
        hasCachePoints = true
      }
    }
    
    if (hasCachePoints) {
      console.warn('Cache points are not supported by OpenAI and will be ignored. This feature is specific to AWS Bedrock models.')
    }
    
    if (textBlocks.length > 0) {
      request.messages.push({
        role: 'system',
        content: textBlocks.join('\n'),
      })
    }
  }
}

Files to Modify

1. src/models/openai.ts: Update _formatRequest method (~20-30 lines changed)
2. src/models/__tests__/openai.test.ts: Add 4 new test cases (~100-150 lines)

Acceptance Criteria

• OpenAI model provider handles string systemPrompt (existing behavior maintained)
• OpenAI model provider handles array systemPrompt with text blocks
• OpenAI model provider handles array systemPrompt with cache points (with warning)
• Console warning is emitted when cache points are present
• Empty array systemPrompt is handled correctly (no system message added)
• All existing tests continue to pass
• New tests added for all array systemPrompt scenarios
• Test coverage remains above 80%
• Code follows existing patterns from Bedrock implementation
• TypeScript compiles without errors
• ESLint passes without errors
• Prettier formatting is consistent

Backward Compatibility

• All existing code using string systemPrompt continues to work unchanged
• New array support is purely additive

Estimated Scope

• Complexity: Low-Medium
• Files Modified: 2 files
• Lines Added/Modified: ~120-180 lines (including tests)
• Time Estimate: 2-4 hours
• Risk: Low (follows established patterns, backward compatible)

Related Context

• Reference PR/Commit: Check recent commits that updated Bedrock for the SystemPrompt type change
• Type Definition: src/types/messages.ts lines 162-186
• Similar Feature: Reasoning block handling in OpenAI (lines 497-499, 581-584) shows pattern for unsupported features

[Unshure]

/strands

[github-actions]

Task Review Complete ✅

I've completed the review of this feature request and updated the issue description with comprehensive implementation requirements.

What Was Accomplished

1. Repository Analysis:

   • Analyzed the new SystemPrompt type definition (string | SystemContentBlock[])
   • Reviewed Bedrock's implementation as the reference pattern (lines 352-372 in bedrock.ts)
   • Identified OpenAI's current limitation (only handles string systemPrompt)
   • Examined existing test patterns in both providers

2. Implementation Requirements Defined:

   • Clear specification for handling both string and array SystemPrompt types
   • Defined behavior for cache points (warn and ignore, since OpenAI doesn't support prompt caching)
   • Specified text block concatenation approach (use newlines to preserve structure)
   • Identified all edge cases (empty arrays, cache-only arrays, mixed content)

3. Test Requirements Specified:

   • 4 new test cases following existing patterns from Bedrock tests
   • Clear expectations for each test scenario
   • Maintains consistency with repository testing patterns

Task is Ready for Implementation

This task is well-scoped and ready for a developer to implement. The implementation:

• Follows established patterns from the Bedrock provider
• Is backward compatible (existing string usage unchanged)
• Has clear acceptance criteria
• Can be completed in a single PR
• Estimated at 2-4 hours of work

Key Design Decisions

1. Cache Points: Emit warning and ignore (following pattern of other unsupported OpenAI features)
2. Text Concatenation: Use newlines to preserve structure and readability
3. Empty Arrays: Skip adding system message (matches Bedrock behavior)
4. Backward Compatibility: String systemPrompt handling remains unchanged

The developer can proceed with confidence using the Bedrock implementation as a reference while adapting for OpenAI's API constraints.

[Unshure]

/strands implement

[github-actions]

Implementation Complete ✅

I've successfully implemented the SystemPrompt array type support for the OpenAI model provider. All tests pass and the implementation is ready for review.

Summary

• Branch: agent-tasks/90
• Commit: 86322d6
• Tests: 166/166 passing (4 new tests added)
• Coverage: 94.34% (above 80% requirement)

Changes

1. Updated _formatRequest method in src/models/openai.ts to handle array SystemPrompt
2. Added 4 comprehensive test cases in src/models/__tests__/openai.test.ts
3. Console warning emitted when cache points are present (unsupported by OpenAI)
4. Backward compatibility maintained for string systemPrompt

Create Pull Request

Please create a PR using this link:

https://github.com/strands-agents/sdk-typescript/compare/main...agent-tasks/90?quick_pull=1&title=Task%2090%3A%20Add%20new%20SystemPrompt%20type%20support%20to%20OpenAI%20Model%20provider%20Implementation&body=Resolves%3A%20%2390%0A%0A%23%23%20Overview%0AThis%20PR%20adds%20SystemPrompt%20array%20type%20support%20to%20the%20OpenAI%20model%20provider%2C%20bringing%20it%20to%20feature%20parity%20with%20the%20Bedrock%20model%20provider.%20The%20implementation%20allows%20systemPrompt%20to%20be%20either%20a%20string%20or%20an%20array%20of%20SystemContentBlock%20elements.%0A%0A%23%23%20Changes%0A-%20Updated%20%60_formatRequest%60%20method%20to%20handle%20both%20string%20and%20array%20SystemPrompt%20types%0A-%20Added%204%20comprehensive%20test%20cases%20following%20the%20Bedrock%20test%20pattern%0A-%20Console%20warning%20emitted%20when%20cache%20points%20are%20present%0A-%20Backward%20compatibility%20maintained%0A%0A%23%23%20Test%20Results%0A-%20All%20166%20tests%20pass%20(4%20new%20tests%20added)%0A-%20Coverage%3A%2094.34%25%0A-%20TypeScript%2C%20ESLint%2C%20Prettier%20all%20pass