Executing Prompts

Basic Usage

Execute a prompt using its key:

package main

import (
	"fmt"
	"log"

	"github.com/switchport-ai/switchport-go/switchport"
)

func main() {
	client, err := switchport.NewClient("")
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	response, err := client.Prompts.Execute(
		"welcome-message",
		nil, // no subject
		nil, // no variables
	)
	if err != nil {
		log.Fatalf("Failed to execute prompt: %v", err)
	}

	fmt.Println(response.Text)
}

Using Variables

Pass dynamic variables to your prompts:

response, err := client.Prompts.Execute(
	"welcome-message",
	nil, // no subject
	map[string]interface{}{
		"name":    "Alice",
		"product": "Pro Plan",
	},
)
if err != nil {
	log.Fatalf("Failed to execute prompt: %v", err)
}

fmt.Println(response.Text)

Your prompt template in the dashboard:

Write a friendly welcome message for {{name}} who just purchased {{product}}.

Using Subject for A/B Testing

Provide subject to enable deterministic A/B testing:

response, err := client.Prompts.Execute(
	"product-pitch",
	map[string]interface{}{"user_id": "user_123"},
	map[string]interface{}{"product": "Enterprise Plan"},
)
if err != nil {
	log.Fatalf("Failed to execute prompt: %v", err)
}

fmt.Printf("Version: %s\n", response.VersionName)

The same subject always gets the same version. This ensures users have a consistent experience.

Subject Types

Subject can be either a string or a map:

response, err := client.Prompts.Execute(
	"greeting",
	"user_123", // string subject
	nil,
)

response, err := client.Prompts.Execute(
	"greeting",
	map[string]interface{}{
		"user_id": "user_123",
		"tier":    "premium",
		"region":  "us-west",
	},
	nil,
)

Response Object

The Execute method returns a PromptResponse struct with the following fields:

response, err := client.Prompts.Execute(
	"welcome-message",
	nil,
	map[string]interface{}{"name": "Alice"},
)
if err != nil {
	log.Fatalf("Failed to execute prompt: %v", err)
}

// Generated text from the LLM
fmt.Println(response.Text)

// Model that was used
fmt.Println(response.Model) // e.g., "gpt-5"

// Version that was selected
fmt.Println(response.VersionName) // e.g., "v1"
fmt.Println(response.VersionID)   // e.g., "ver_abc123"

// Unique request identifier
fmt.Println(response.RequestID) // e.g., "req_xyz789"

Response Fields

Field	Type	Description
`Text`	`string`	The generated text from the LLM
`Model`	`string`	The model used (e.g., `gpt-5`, `claude-3-5-sonnet-20241022`)
`VersionName`	`string`	Human-readable version name
`VersionID`	`string`	Unique version identifier
`PromptConfigID`	`string`	Unique prompt config identifier
`RequestID`	`string`	Unique request identifier
`Metadata`	`map[string]interface{}`	Additional metadata

Error Handling

Handle common errors when executing prompts:

package main

import (
	"errors"
	"log"

	"github.com/switchport-ai/switchport-go/switchport"
)

func main() {
	client, err := switchport.NewClient("")
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	response, err := client.Prompts.Execute(
		"my-prompt",
		nil,
		map[string]interface{}{"name": "Alice"},
	)
	if err != nil {
		var promptNotFound *switchport.PromptNotFoundError
		var authErr *switchport.AuthenticationError
		var apiErr *switchport.APIError

		switch {
		case errors.As(err, &promptNotFound):
			log.Println("Prompt not found - check your prompt key")
		case errors.As(err, &authErr):
			log.Println("Authentication failed - check your API key")
		case errors.As(err, &apiErr):
			log.Printf("API error (status %d): %v", apiErr.StatusCode, apiErr)
		default:
			log.Printf("Unknown error: %v", err)
		}
		return
	}

	log.Println(response.Text)
}

Common Patterns

Pattern 1: Dynamic Email Generation

func sendWelcomeEmail(user User) error {
	client, err := switchport.NewClient("")
	if err != nil {
		return err
	}

	response, err := client.Prompts.Execute(
		"welcome-email",
		map[string]interface{}{"user_id": user.ID},
		map[string]interface{}{
			"name":  user.Name,
			"email": user.Email,
		},
	)
	if err != nil {
		return err
	}

	return sendEmail(user.Email, response.Text)
}

Pattern 2: Chatbot Responses

func getBotResponse(userID, userMessage string) (string, error) {
	client, err := switchport.NewClient("")
	if err != nil {
		return "", err
	}

	history, err := getHistory(userID)
	if err != nil {
		return "", err
	}

	response, err := client.Prompts.Execute(
		"support-bot",
		map[string]interface{}{"user_id": userID},
		map[string]interface{}{
			"user_message":         userMessage,
			"conversation_history": history,
		},
	)
	if err != nil {
		return "", err
	}

	return response.Text, nil
}

Pattern 3: Content Generation

func generateProductDescription(productID string, userSegment string) (string, error) {
	client, err := switchport.NewClient("")
	if err != nil {
		return "", err
	}

	product, err := getProduct(productID)
	if err != nil {
		return "", err
	}

	response, err := client.Prompts.Execute(
		"product-description",
		map[string]interface{}{"segment": userSegment},
		map[string]interface{}{
			"product_name": product.Name,
			"features":     product.Features,
			"price":        product.Price,
		},
	)
	if err != nil {
		return "", err
	}

	return response.Text, nil
}

Pattern 4: Fallback Handling

func getAIResponse(promptKey string, variables map[string]interface{}) (string, error) {
	client, err := switchport.NewClient("")
	if err != nil {
		// Fallback to default if client creation fails
		return getDefaultResponse(promptKey, variables)
	}

	response, err := client.Prompts.Execute(promptKey, nil, variables)
	if err != nil {
		var apiErr *switchport.APIError
		if errors.As(err, &apiErr) {
			// Fallback to default template if API fails
			return getDefaultResponse(promptKey, variables)
		}
		return "", err
	}

	return response.Text, nil
}

func getDefaultResponse(promptKey string, variables map[string]interface{}) (string, error) {
	// Return a static template or cached response
	return "Default response", nil
}

Best Practices

Always use subject for A/B testing

If you want to track metrics or run A/B tests, always provide subject when executing prompts.

Use consistent subject

Use the same subject (e.g., user ID) across prompt executions and metric recording for the same subject or session.

Handle errors gracefully

Always implement error handling with fallback behavior to ensure your application continues working even if the API fails.

Use type-safe variables

While variables accept map[string]interface{}, consider wrapping in helper functions for type safety.

Cache responses when appropriate

For expensive or frequently-used prompts, consider caching responses to reduce API calls and latency.

Log request IDs

Store RequestID values for debugging and support purposes.

Use defer for cleanup

Use Go’s defer keyword for any cleanup operations needed after API calls.

Next Steps

Recording Metrics

Learn how to track metrics for your prompts

A/B Testing

Set up A/B tests with multiple versions

Getting Started

Core Features

Examples

Basic Usage

Using Variables

Using Subject for A/B Testing

Subject Types

Response Object

Response Fields

Error Handling

Common Patterns

Pattern 1: Dynamic Email Generation

Pattern 2: Chatbot Responses

Pattern 3: Content Generation

Pattern 4: Fallback Handling

Best Practices

Next Steps

Recording Metrics

A/B Testing

​Basic Usage

​Using Variables

​Using Subject for A/B Testing

​Subject Types

​Response Object

​Response Fields

​Error Handling

​Common Patterns

​Pattern 1: Dynamic Email Generation

​Pattern 2: Chatbot Responses

​Pattern 3: Content Generation

​Pattern 4: Fallback Handling

​Best Practices

​Next Steps

Recording Metrics

A/B Testing

Basic Usage

Using Variables

Using Subject for A/B Testing

Subject Types

Response Object

Response Fields

Error Handling

Common Patterns

Pattern 1: Dynamic Email Generation

Pattern 2: Chatbot Responses

Pattern 3: Content Generation

Pattern 4: Fallback Handling

Best Practices

Next Steps