Skip to main content
Using a Skills-compatible agent like Claude Code? The Greenflash agent skill handles this automatically. Run /greenflash-onboard-prompts instead of copying this prompt.

​
Upgrade an Existing Python SDK Integration to Log System Prompts

You are a coding agent tasked with updating our existing Python 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 Python 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. Sync: 
client.messages.create(
    external_user_id=...,
    external_conversation_id=...,
    product_id=...,
    system_prompt="You are a helpful assistant. Be concise and friendly.",
    messages=[ ... ],
)
Async (fire-and-forget): 
asyncio.create_task(client.messages.create(
    external_user_id=...,
    external_conversation_id=...,
    product_id=...,
    system_prompt="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. 
system_prompt = {
    "external_template_id": "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": dynamic_rag_text,
            "isDynamic": True
        }
    ],
    "variables": {
        "customerName": customer_name,
        "company": company_name
    }
}

# Sync
client.messages.create(
    external_user_id=...,
    external_conversation_id=...,
    product_id=...,
    system_prompt=system_prompt,
    messages=[ ... ],
)

# Async (fire-and-forget)
asyncio.create_task(client.messages.create(
    external_user_id=...,
    external_conversation_id=...,
    product_id=...,
    system_prompt=system_prompt,
    messages=[ ... ],
))
Key Notes for Structured Prompts:
  • external_template_id 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 system_prompt 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.

​
Async vs Sync Considerations

When adding system prompt logging, match our existing async/sync pattern:
  • Sync apps: Call client.messages.create(...) directly. Use the sync Greenflash client.
  • Async apps: Use AsyncGreenflash and wrap calls in asyncio.create_task() for fire-and-forget logging that won’t block our LLM responses.
Important: In Python, calling an async function without await returns a coroutine that never executes. Always use asyncio.create_task() for fire-and-forget patterns in async code.

​
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 system_prompt and message array
Either approach is valid — choose what aligns best with the existing code flow.

​
Python SDK Integration Checklist

Your code should:
  1. Initialize the Python SDK with our API key (use Greenflash for sync, AsyncGreenflash for async)
  2. Construct system_prompt:
    • As a simple string, or
    • As a structured object with promptComponents
  3. Include system_prompt on every messages.create(...) call
  4. Respect dynamic variables using variables on the system_prompt object if structured prompts have templates
  5. Choose batching vs streaming appropriately
  6. Preserve existing logging semantics for message bodies
  7. Use asyncio.create_task() for fire-and-forget logging in async code
Example with variables (sync): 
system_prompt_with_vars = {
    "external_template_id": "my-assistant-prompt",
    "components": [# your prompt components],
    "variables": {
        "userName": user_name,
        "companyName": company_name
    }
}

client.messages.create(
    external_user_id=user_id,
    external_conversation_id=conversation_id,
    product_id=product_id,
    system_prompt=system_prompt_with_vars,
    messages=message_list,
)
Example with variables (async fire-and-forget): 
system_prompt_with_vars = {
    "external_template_id": "my-assistant-prompt",
    "components": [# your prompt components],
    "variables": {
        "userName": user_name,
        "companyName": company_name
    }
}

asyncio.create_task(client.messages.create(
    external_user_id=user_id,
    external_conversation_id=conversation_id,
    product_id=product_id,
    system_prompt=system_prompt_with_vars,
    messages=message_list,
))

​
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 Python 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.