Prompt

In the Blades framework, Prompt is the core component for interacting with Large Language Models (LLMs). It represents a sequence of messages exchanged between the user and the assistant, supporting various message types (system messages, user messages, assistant messages) and templating capabilities, enabling developers to build dynamic and context-aware AI applications.

Prompt Structure

A Prompt is a container for a sequence of multiple messages.

type Prompt struct {
    Messages []*Message `json:"messages"`
}

Message Types

Blades supports multiple message types, each with a specific role:

• RoleUser: Represents input from the end user
• RoleSystem: Provides system-level instructions and context
• RoleAssistant: Represents the model’s output
• RoleTool: Represents messages generated by tools

Basic Usage

The most basic way to create a Prompt is by directly specifying the message content:

prompt := blades.NewPrompt(
    blades.UserMessage("What is the capital of France?"),
)

Prompt with System Instructions

You can provide context and instructions to the model by adding system messages:

prompt := blades.NewPrompt(
    blades.SystemMessage("You are a helpful assistant that provides detailed and accurate information."),
    blades.UserMessage("What is the capital of France?"),
)

Prompt Templating

Blades provides powerful templating capabilities, allowing for dynamic generation of Prompt content. Use the PromptTemplate builder to create templated Prompts with variables:

params := map[string]any{
    "topic":    "The Future of Artificial Intelligence",
    "audience": "General reader",
}

prompt, err := blades.NewPromptTemplate().
    System("Please summarize {{.topic}} in three key points.", params).
    User("Respond concisely and accurately for a {{.audience}} audience.", params).
    Build()
if err != nil {
    log.Fatal(err)
}

Templates with Session Context

// Create a new session
session := blades.NewSession("conversation_123", map[string]any{
    "style": "robot",
})

ctx := blades.NewSessionContext(context.Background(), session)

// Use session variables in templates
prompt, err := blades.NewPromptTemplate().
    System("Respond as a {{.style}}.", nil).
    User("Tell me a joke.", nil).
    BuildContext(ctx)

Advanced Features

Blades Prompt also supports various features such as multi-part messages and streaming.

Multi-part Messages

Blades supports messages containing multiple content types, including text, file references, and binary data:

message := blades.UserMessage(
    blades.TextPart{Text: "Analyze this image:"},
    blades.FilePart{
        Name:     "chart.png",
        URI:      "file:///path/to/chart.png",
        MIMEType: "image/png",
    },
)

Streaming

Prompt can be used in conjunction with streaming to achieve real-time responses:

stream, err := agent.RunStream(context.Background(), prompt)
if err != nil {
    log.Fatal(err)
}
defer stream.Close()

for stream.Next() {
    message, err := stream.Current()
    if err != nil {
        log.Printf("Error: %v", err)
        continue
    }
    fmt.Print(message.Text())
}

Best Practices

• Clear System Instructions: Provide clear and specific instructions in system messages to help the model better understand task requirements.
• Use Templates Appropriately: Leverage templating capabilities to improve code reusability and maintainability, especially in scenarios requiring dynamic Prompt generation.
• Manage Context Length: Pay attention to controlling the Prompt length to avoid exceeding the model’s maximum context limit.
• Error Handling: Always check for errors during template rendering and Prompt building to ensure application robustness.

Basic Example

package main

import (
    "context"
    "log"

    "github.com/go-kratos/blades"
    "github.com/go-kratos/blades/contrib/openai"
)

func main() {
    agent := blades.NewAgent(
        "Basic Agent",
        blades.WithModel("gpt-5"),
        blades.WithProvider(openai.NewChatProvider()),
        blades.WithInstructions("You are a helpful assistant that provides detailed and accurate information."),
    )

    prompt := blades.NewPrompt(
        blades.UserMessage("What is the capital of France?"),
    )

    result, err := agent.Run(context.Background(), prompt)
    if err != nil {
        log.Fatal(err)
    }

    log.Println(result.Text())
}

Templated Example

package main

import (
    "context"
    "log"

    "github.com/go-kratos/blades"
    "github.com/go-kratos/blades/contrib/openai"
)

func main() {
    agent := blades.NewAgent(
        "Template Agent",
        blades.WithModel("gpt-5"),
        blades.WithProvider(openai.NewChatProvider()),
    )

    // Define templates and params
    params := map[string]any{
        "topic":    "The Future of Artificial Intelligence",
        "audience": "General reader",
    }

    // Build prompt using the template builder
    prompt, err := blades.NewPromptTemplate().
        System("Please summarize {{.topic}} in three key points.", params).
        User("Respond concisely and accurately for a {{.audience}} audience.", params).
        Build()
    if err != nil {
        log.Fatal(err)
    }

    log.Println("Generated Prompt:", prompt.String())

    // Run the agent with the templated prompt
    result, err := agent.Run(context.Background(), prompt)
    if err != nil {
        log.Fatal(err)
    }

    log.Println(result.Text())
}