Prompt Management API Reference

This document provides a comprehensive reference for all Prompt Management APIs available in the Conductor Python SDK.

📚 Complete Working Example: See prompt_journey.py for a comprehensive example covering all 8 APIs.

Prerequisites
Quick Start
Prompt Templates
Version Management
Prompt Tags
Testing Prompts
Models Reference
Integration with Workflows
API Coverage Summary
Best Practices
Error Handling

Prerequisites

Required: Integration Setup

⚠️ IMPORTANT: Before using prompts with AI models, you MUST set up integrations:

from conductor.client.orkes.orkes_integration_client import OrkesIntegrationClient
from conductor.client.http.models.integration_update import IntegrationUpdate
from conductor.client.http.models.integration_api_update import IntegrationApiUpdate

# Step 1: Create Integration
integration = IntegrationUpdate(
    type='openai',
    category='AI_MODEL',
    description='OpenAI models',
    enabled=True,
    configuration={
        'api_key': 'sk-your-key',
        'endpoint': 'https://api.openai.com/v1'
    }
)
integration_client.save_integration('openai', integration)

# Step 2: Add Models (REQUIRED even if integration exists!)
model = IntegrationApiUpdate(
    description='GPT-4 Optimized',
    enabled=True,
    max_tokens=128000
)
integration_client.save_integration_api('openai', 'gpt-4o', model)

See Integration Documentation for complete setup.

Quick Start

from conductor.client.configuration.configuration import Configuration
from conductor.client.orkes.orkes_prompt_client import OrkesPromptClient

# Initialize client
configuration = Configuration()
prompt_client = OrkesPromptClient(configuration)

# Create a prompt
prompt_client.save_prompt(
    prompt_name="greeting",
    description="Customer greeting",
    prompt_template="Hello ${customer_name}, how can I help you?"
)

# Test the prompt
response = prompt_client.test_prompt(
    prompt_text="Hello ${customer_name}, how can I help you?",
    variables={"customer_name": "Alice"},
    ai_integration="openai",
    text_complete_model="gpt-4o",
    temperature=0.7
)

Prompt Templates

Manage prompt templates for AI/LLM interactions.

Method	Endpoint	Description	Example
`save_prompt()`	`PUT /api/prompts/{name}`	Create or update prompt	Example
`get_prompt()`	`GET /api/prompts/{name}`	Get prompt by name	Example
`get_prompts()`	`GET /api/prompts`	List all prompts	Example
`delete_prompt()`	`DELETE /api/prompts/{name}`	Delete a prompt	Example

Save Prompt

Creates or updates a prompt template with optional version management.

from conductor.client.configuration.configuration import Configuration
from conductor.client.orkes.orkes_prompt_client import OrkesPromptClient

configuration = Configuration()
prompt_client = OrkesPromptClient(configuration)

# Basic prompt creation
prompt_client.save_prompt(
    prompt_name="customer_greeting",
    description="Personalized customer greeting",
    prompt_template="Hello ${customer_name}, how can I help you today?"
)

# With explicit version (default is 1)
prompt_client.save_prompt(
    prompt_name="order_inquiry",
    description="Order status inquiry handler",
    prompt_template="Order ${order_id}: Status is ${status}",
    version=1  # Explicit version
)

# With model associations
prompt_client.save_prompt(
    prompt_name="complex_analysis",
    description="Complex analysis requiring GPT-4",
    prompt_template="${analysis_prompt}",
    models=['gpt-4o', 'gpt-4']  # Just model names, no prefix
)

# With auto-increment for updates
prompt_client.save_prompt(
    prompt_name="existing_prompt",
    description="Updated description",
    prompt_template="Updated template",
    auto_increment=True  # Auto-increment version
)

Get Prompt

# Get prompt by name
prompt = prompt_client.get_prompt("customer_greeting")
if prompt:
    print(f"Name: {prompt.name}")
    print(f"Description: {prompt.description}")
    print(f"Template: {prompt.template}")
    print(f"Variables: {prompt.variables}")
    print(f"Version: {prompt.version}")

Get Prompts

# List all prompts
prompts = prompt_client.get_prompts()
for prompt in prompts:
    print(f"Prompt: {prompt.name} v{prompt.version}")
    print(f"  Description: {prompt.description}")
    print(f"  Variables: {prompt.variables}")

Delete Prompt

# Delete a prompt
prompt_client.delete_prompt("old_prompt")
print("✅ Prompt deleted")

Version Management

Conductor supports versioning for prompt templates to track changes and enable rollbacks.

Feature	Description	Example
Explicit Version	Set specific version number	`version=2`
Auto-Increment	Automatically increment version	`auto_increment=True`
Default Version	New prompts default to version 1	Default behavior

Creating Versions

# Version 1 - Initial prompt
prompt_client.save_prompt(
    prompt_name="faq_response",
    description="FAQ response generator - v1",
    prompt_template="Answer: ${question}",
    version=1
)

# Version 2 - Enhanced version
prompt_client.save_prompt(
    prompt_name="faq_response",
    description="FAQ response generator - v2 with category",
    prompt_template="Category: ${category}\nQuestion: ${question}\nAnswer:",
    version=2
)

# Version 3 - Auto-incremented
prompt_client.save_prompt(
    prompt_name="faq_response",
    description="FAQ response generator - v3 with urgency",
    prompt_template="Urgency: ${urgency}\nCategory: ${category}\nQuestion: ${question}",
    auto_increment=True  # Will become version 3
)

Version Best Practices

Major Changes: Use explicit version numbers
Minor Updates: Use auto-increment
Testing: Create separate versions for A/B testing
Rollback: Keep previous versions for quick rollback

Prompt Tags

Organize and categorize prompts with metadata tags.

Method	Endpoint	Description	Example
`update_tag_for_prompt_template()`	`PUT /api/prompts/{name}/tags`	Add/update tags	Example
`get_tags_for_prompt_template()`	`GET /api/prompts/{name}/tags`	Get prompt tags	Example
`delete_tag_for_prompt_template()`	`DELETE /api/prompts/{name}/tags`	Delete tags	Example

Update Tag For Prompt Template

from conductor.client.orkes.models.metadata_tag import MetadataTag

# Add tags for organization
tags = [
    MetadataTag("category", "customer_service"),
    MetadataTag("type", "greeting"),
    MetadataTag("language", "english"),
    MetadataTag("status", "production"),
    MetadataTag("model_tested", "gpt-4o"),
    MetadataTag("version_status", "active")
]

# Note: prompt_name is first parameter, then tags
prompt_client.update_tag_for_prompt_template("customer_greeting", tags)
print("✅ Tags added to prompt")

Get Tags For Prompt Template

# Get all tags for a prompt
tags = prompt_client.get_tags_for_prompt_template("customer_greeting")
for tag in tags:
    print(f"Tag: {tag.key} = {tag.value}")

Delete Tag For Prompt Template

# Delete specific tags
tags_to_remove = [
    MetadataTag("status", "testing"),
    MetadataTag("version_status", "deprecated")
]

# Note: prompt_name is first parameter, then tags
prompt_client.delete_tag_for_prompt_template("customer_greeting", tags_to_remove)
print("✅ Tags removed")

Testing Prompts

Test prompts with actual AI models before deployment.

Method	Endpoint	Description	Example
`test_prompt()`	`POST /api/prompts/test`	Test prompt with AI model	Example

Test Prompt

# Test with variables and AI model
response = prompt_client.test_prompt(
    prompt_text="Greet ${customer_name} who is a ${customer_tier} member",
    variables={
        "customer_name": "John Smith",
        "customer_tier": "Premium"
    },
    ai_integration="openai",  # Integration name
    text_complete_model="gpt-4o",  # Model name (no prefix!)
    temperature=0.7,
    top_p=0.9,
    stop_words=None  # Optional list of stop words
)

print(f"AI Response: {response}")

# Test with different parameters
test_configs = [
    {"temp": 0.3, "desc": "Conservative"},
    {"temp": 0.7, "desc": "Balanced"},
    {"temp": 0.9, "desc": "Creative"}
]

for config in test_configs:
    response = prompt_client.test_prompt(
        prompt_text=template,
        variables=variables,
        ai_integration="openai",
        text_complete_model="gpt-4o",
        temperature=config["temp"],
        top_p=0.9
    )
    print(f"{config['desc']}: {response[:100]}...")

Models Reference

Core Models

PromptTemplate

Represents a prompt template with metadata.

Module: conductor.client.http.models.prompt_template

Properties:

name (str): Unique prompt name
description (str): Prompt description
template (str): Prompt template with variables
variables (List[str]): List of variable names
version (int): Version number (default: 1)
tags (List[MetadataTag]): Associated tags
created_by (str): Creator username
created_on (int): Creation timestamp
updated_on (int): Last update timestamp

Example:

prompt = prompt_client.get_prompt("customer_greeting")
print(f"Name: {prompt.name}")
print(f"Version: {prompt.version}")
print(f"Variables: {prompt.variables}")  # ['customer_name', 'customer_tier']

MetadataTag

Tag for organizing prompts.

Module: conductor.client.orkes.models.metadata_tag

Properties:

key (str): Tag key
value (str): Tag value

Example:

from conductor.client.orkes.models.metadata_tag import MetadataTag

tags = [
    MetadataTag("environment", "production"),
    MetadataTag("team", "customer_service"),
    MetadataTag("compliance", "pii_safe")
]

Integration with Workflows

Use prompts in workflows via AI tasks for automated processing.

from conductor.client.workflow.task.llm_text_complete_task import LlmTextCompleteTask

# Use saved prompt in workflow
llm_task = LlmTextCompleteTask(
    task_ref_name="generate_response",
    llm_provider="openai",
    model="gpt-4o",  # Just model name, no prefix
    prompt_name="customer_greeting",
    prompt_variables={
        "customer_name": "${workflow.input.customer_name}",
        "customer_tier": "${workflow.input.tier}",
        "time_of_day": "${workflow.input.time}"
    },
    temperature=0.7,
    top_p=0.9
)

# Add to workflow definition
workflow.add(llm_task)

Complete Example

Here's a complete example demonstrating prompt management with integrations:

from conductor.client.configuration.configuration import Configuration
from conductor.client.orkes.orkes_prompt_client import OrkesPromptClient
from conductor.client.orkes.orkes_integration_client import OrkesIntegrationClient
from conductor.client.http.models.integration_update import IntegrationUpdate
from conductor.client.http.models.integration_api_update import IntegrationApiUpdate
from conductor.client.orkes.models.metadata_tag import MetadataTag

# Initialize clients
configuration = Configuration()
prompt_client = OrkesPromptClient(configuration)
integration_client = OrkesIntegrationClient(configuration)

# 1. Setup Integration
integration = IntegrationUpdate(
    type='openai',
    category='AI_MODEL',
    description='OpenAI GPT models',
    enabled=True,
    configuration={
        'api_key': 'sk-your-key',
        'endpoint': 'https://api.openai.com/v1'
    }
)
integration_client.save_integration('openai', integration)

# 2. Add Models
model = IntegrationApiUpdate(
    description='GPT-4 Optimized',
    enabled=True,
    max_tokens=128000
)
integration_client.save_integration_api('openai', 'gpt-4o', model)

# 3. Create Prompt with Version
prompt_client.save_prompt(
    prompt_name="customer_greeting",
    description="Personalized greeting",
    prompt_template="""Hello ${customer_name}!

As a ${customer_tier} member, you have access to priority support.
How can I help you today?""",
    version=1,
    models=['gpt-4o', 'gpt-4']
)

# 4. Tag Prompt
tags = [
    MetadataTag("category", "customer_service"),
    MetadataTag("status", "production"),
    MetadataTag("language", "english")
]
prompt_client.update_tag_for_prompt_template("customer_greeting", tags)

# 5. Test Prompt
prompt = prompt_client.get_prompt("customer_greeting")
response = prompt_client.test_prompt(
    prompt_text=prompt.template,
    variables={
        "customer_name": "John Smith",
        "customer_tier": "Premium"
    },
    ai_integration="openai",
    text_complete_model="gpt-4o",
    temperature=0.7,
    top_p=0.9
)
print(f"Response: {response}")

# 6. Create Updated Version
prompt_client.save_prompt(
    prompt_name="customer_greeting",
    description="Enhanced greeting with time awareness",
    prompt_template="""Good ${time_of_day}, ${customer_name}!

As a valued ${customer_tier} member, you have priority access.
How may I assist you today?""",
    auto_increment=True  # Version 2
)

API Coverage Summary

Prompt Management APIs (8 total)

API	Method	Status	Description
`save_prompt()`	`PUT`	✅ Implemented	Create/update prompts with versioning
`get_prompt()`	`GET`	✅ Implemented	Retrieve specific prompt
`get_prompts()`	`GET`	✅ Implemented	List all prompts
`delete_prompt()`	`DELETE`	✅ Implemented	Delete prompt
`update_tag_for_prompt_template()`	`PUT`	✅ Implemented	Add/update tags
`get_tags_for_prompt_template()`	`GET`	✅ Implemented	Get prompt tags
`delete_tag_for_prompt_template()`	`DELETE`	✅ Implemented	Remove tags
`test_prompt()`	`POST`	✅ Implemented	Test with AI model

Coverage: 8/8 APIs (100%)

Best Practices

1. Integration Setup

Always set up integrations before using prompts:

# ✅ RIGHT: Integration → Models → Prompts
integration_client.save_integration('openai', integration)
integration_client.save_integration_api('openai', 'gpt-4o', model)
prompt_client.save_prompt(...)

# ❌ WRONG: Prompts without integration
prompt_client.save_prompt(...)  # Will fail when testing

2. Model Format

Use correct model naming in API calls:

# ✅ RIGHT
ai_integration="openai"
text_complete_model="gpt-4o"  # Just model name

# ❌ WRONG
text_complete_model="openai:gpt-4o"  # Don't use prefix

3. Version Management

# Major changes: Explicit version
version=2

# Minor updates: Auto-increment
auto_increment=True

# Default for new prompts: Version 1
# (no version parameter needed)

4. Tag Strategy

# Consistent tagging for organization
standard_tags = [
    MetadataTag("category", "customer_service"),
    MetadataTag("environment", "production"),
    MetadataTag("status", "active"),
    MetadataTag("compliance", "pii_safe"),
    MetadataTag("model_tested", "gpt-4o")
]

5. Testing Strategy

# Test with different parameters
for temp in [0.3, 0.7, 0.9]:
    response = prompt_client.test_prompt(
        prompt_text=template,
        variables=variables,
        ai_integration="openai",
        text_complete_model="gpt-4o",
        temperature=temp
    )
    # Analyze response...

Error Handling

from conductor.client.http.rest import ApiException

try:
    # Check if prompt exists
    prompt = prompt_client.get_prompt("customer_greeting")
    if not prompt:
        print("Prompt not found, creating...")
        prompt_client.save_prompt(...)

except ApiException as e:
    if e.status == 404:
        print("Resource not found")
    elif e.status == 400:
        print("Invalid request")
    else:
        print(f"API Error: {e}")

except Exception as e:
    print(f"Unexpected error: {e}")

# Safe prompt testing
def safe_test(prompt_name, variables):
    try:
        prompt = prompt_client.get_prompt(prompt_name)
        if not prompt:
            return None

        return prompt_client.test_prompt(
            prompt_text=prompt.template,
            variables=variables,
            ai_integration="openai",
            text_complete_model="gpt-4o",
            temperature=0.7
        )
    except Exception as e:
        print(f"Test failed: {e}")
        return None

Complete Working Example

For a comprehensive implementation demonstrating all prompt management features:

📚 examples/prompt_journey.py

This example includes:

✅ All 8 Prompt Management APIs
✅ Integration setup and model configuration
✅ Version management (explicit and auto-increment)
✅ Tag-based organization
✅ Testing with multiple models and parameters
✅ Real-world customer service scenarios
✅ Best practices and error handling

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Prompt Management API Reference

Table of Contents

Prerequisites

Required: Integration Setup

Quick Start

Prompt Templates

Save Prompt

Get Prompt

Get Prompts

Delete Prompt

Version Management

Creating Versions

Version Best Practices

Prompt Tags

Update Tag For Prompt Template

Get Tags For Prompt Template

Delete Tag For Prompt Template

Testing Prompts

Test Prompt

Models Reference

Core Models

PromptTemplate

MetadataTag

Integration with Workflows

Complete Example

API Coverage Summary

Prompt Management APIs (8 total)

Best Practices

1. Integration Setup

2. Model Format

3. Version Management

4. Tag Strategy

5. Testing Strategy

Error Handling

Complete Working Example

See Also

FilesExpand file tree

PROMPT.md

Latest commit

History

PROMPT.md

File metadata and controls

Prompt Management API Reference

Table of Contents

Prerequisites

Required: Integration Setup

Quick Start

Prompt Templates

Save Prompt

Get Prompt

Get Prompts

Delete Prompt

Version Management

Creating Versions

Version Best Practices

Prompt Tags

Update Tag For Prompt Template

Get Tags For Prompt Template

Delete Tag For Prompt Template

Testing Prompts

Test Prompt

Models Reference

Core Models

PromptTemplate

MetadataTag

Integration with Workflows

Complete Example

API Coverage Summary

Prompt Management APIs (8 total)

Best Practices

1. Integration Setup

2. Model Format

3. Version Management

4. Tag Strategy

5. Testing Strategy

Error Handling

Complete Working Example

See Also