Prompt Components¶

A prompt component defines reusable prompt templates with variable interpolation, role assignment, and version control. Prompts are referenced by agents to provide system instructions, few-shot examples, and dynamic context.

Creating a Prompt¶

PythonUI

Coming Soon

The Python SDK for local development is not yet publicly available.

from flow_sdk.cli_client import CLIClient

client = CLIClient(config)

prompt = client.prompts.create({
    "name": "Customer Support Instructions",
    "slug": "customer-support-instructions",
    "description": "System prompt for customer support agents",
    "system_message": """You are a customer support agent for {{company_name}}.

Your role:
- Answer customer questions accurately using the knowledge base
- Create support tickets for issues you cannot resolve
- Escalate to a human when the customer is frustrated or the issue is complex

Guidelines:
- Always address the customer by name: {{customer_name}}
- Reference their account tier ({{account_tier}}) when discussing features
- Keep responses concise and professional
- Never share internal system details or other customers' information""",
    "tags": ["support", "production"],
})

Navigate to Components > Prompts > New. Enter system message and configure templates. Click Create.

Configuration¶

Field	Type	Required	Description
`name`	string	Yes	Display name
`slug`	string	Yes	URL-safe identifier
`system_message`	string	No	Primary system prompt (max 10,000 chars)
`static_templates`	list	No	Additional prompt templates with role and variables
`dynamic_function_refs`	string[]	No	References to functions that generate prompt content at runtime
`description`	string	No	What this prompt is for
`tags`	string[]	No	Tags for filtering

Variable Interpolation¶

Use {{variable_name}} syntax to define placeholders that are filled at runtime. Variables make prompts reusable across different contexts without duplicating the prompt component.

Coming Soon

The Python SDK for local development is not yet publicly available.

prompt = client.prompts.create({
    "name": "Data Analysis Prompt",
    "slug": "data-analysis-prompt",
    "system_message": """You are a data analyst specializing in {{domain}}.

Analyze the provided {{data_type}} data and produce:
1. A summary of key findings
2. {{num_insights}} actionable insights
3. Recommendations for {{audience}}

Format your response as structured JSON matching the output schema.""",
})

When the agent runs, the platform substitutes variable values from the execution context:

Variable	Source
`{{company_name}}`	Organization settings
`{{customer_name}}`	Input data or session state
`{{domain}}`	Agent configuration or runtime input

Static Templates¶

Static templates provide additional prompt content beyond the system message. Each template has a role (system, user, assistant) and can include its own variables.

Coming Soon

The Python SDK for local development is not yet publicly available.

prompt = client.prompts.create({
    "name": "Few-Shot Classifier",
    "slug": "few-shot-classifier",
    "system_message": "You classify customer tickets into categories.",
    "static_templates": [
        {
            "role": "user",
            "content": "Subject: Can't log in\nBody: I forgot my password and the reset link isn't working.",
            "variables": [],
        },
        {
            "role": "assistant",
            "content": '{"category": "technical", "priority": "medium"}',
            "variables": [],
        },
        {
            "role": "user",
            "content": "Subject: Billing question\nBody: Why was I charged twice this month?",
            "variables": [],
        },
        {
            "role": "assistant",
            "content": '{"category": "billing", "priority": "high"}',
            "variables": [],
        },
        {
            "role": "user",
            "content": "Subject: {{ticket_subject}}\nBody: {{ticket_body}}",
            "variables": ["ticket_subject", "ticket_body"],
        },
    ],
})

This pattern implements few-shot prompting where the agent sees example input/output pairs before processing the actual input.

Dynamic Prompt Functions¶

For prompts that need to include runtime data (database query results, current time, user preferences), reference dynamic functions:

Coming Soon

The Python SDK for local development is not yet publicly available.

prompt = client.prompts.create({
    "name": "Context-Aware Support",
    "slug": "context-aware-support",
    "system_message": "You are a support agent. Use the customer context below to personalize responses.",
    "dynamic_function_refs": [
        "app.prompts.get_customer_context",
        "app.prompts.get_recent_tickets",
    ],
})

Dynamic functions run at execution time and their output is appended to the prompt. This keeps prompts lean while allowing rich, data-driven context injection.

Prompt Versioning¶

Prompts follow the standard component versioning system. Create a new version when you change the system message or templates:

Coming Soon

The Python SDK for local development is not yet publicly available.

new_version = client.prompts.create_version(prompt.id, {
    "version_increment": "minor",
    "updates": {
        "system_message": updated_system_message,
    },
    "change_summary": "Added escalation guidelines and tone adjustments",
})

Version History¶

Coming Soon

The Python SDK for local development is not yet publicly available.

versions = client.prompts.list_versions(prompt.id)

for v in versions.items:
    print(f"v{v.version} — {v.updated_at}")

A/B Testing Prompts¶

Test different prompt versions by creating multiple prompt components and referencing them from separate agent configurations:

Coming Soon

The Python SDK for local development is not yet publicly available.

# Prompt variant A: Concise
prompt_a = client.prompts.create({
    "name": "Support Prompt - Concise",
    "slug": "support-prompt-concise",
    "system_message": "Be brief and direct. Answer in 2-3 sentences maximum.",
})

# Prompt variant B: Detailed
prompt_b = client.prompts.create({
    "name": "Support Prompt - Detailed",
    "slug": "support-prompt-detailed",
    "system_message": "Provide thorough, detailed answers. Include context and next steps.",
})

# Create agent variants
agent_a = client.agents.create({
    "name": "Support Agent (Concise)",
    "slug": "support-agent-concise",
    "model_ref": model.id,
    "prompt_ref": prompt_a.id,
})

agent_b = client.agents.create({
    "name": "Support Agent (Detailed)",
    "slug": "support-agent-detailed",
    "model_ref": model.id,
    "prompt_ref": prompt_b.id,
})

Deploy both variants to the same deployment ring and use the platform's experiments system (see Experiments) to route traffic and measure performance.

Best Practices¶

Keep system messages focused

A system message should define the agent's identity, capabilities, constraints, and response format. Avoid putting task-specific instructions in the system message -- those belong in the user message or static templates.

Use variables for context

Instead of hardcoding values like company names or feature lists, use {{variables}}. This makes the prompt reusable across different organizations and contexts.

Version for every change

Create a new version whenever you modify a prompt. This gives you a complete audit trail and the ability to roll back if a change degrades performance.

Prompt length

System messages have a 10,000 character limit. If you need more context, use dynamic function refs to inject runtime data rather than putting everything in the static prompt.