Prompt
The Prompt module provides several data structures to simplify creating and combining prompts.
This module defines the complete structure of a conversation with a large language model, including messages, content parts, and provider-specific options. It supports rich content types like text, files, tool calls, and reasoning.
Combinators
appendSystem
Signature
declare const appendSystem: {
(content: string): (self: Prompt) => Prompt;
(self: Prompt, content: string): Prompt;
};Example
import { Prompt } from "@effect/ai"
const systemPrompt = Prompt.make([
{
role: "system",
content: "You are an expert in programming.",
},
])
const userPrompt = Prompt.make("Hello, world!")
const prompt = Prompt.merge(systemPrompt, userPrompt)
const replaced = Prompt.appendSystem(prompt, " You are a helpful assistant.")
// result content: "You are an expert in programming. You are a helpful assistant."Merges a prompt with additional raw input by concatenating messages.
Creates a new prompt containing all messages from both the original prompt, and the provided raw input, maintaining the order of messages.
Signature
declare const merge: {
(input: RawInput): (self: Prompt) => Prompt;
(self: Prompt, input: RawInput): Prompt;
};Example
import { Prompt } from "@effect/ai"
const systemPrompt = Prompt.make([
{
role: "system",
content: "You are a helpful assistant.",
},
])
const merged = Prompt.merge(systemPrompt, "Hello, world!")prependSystem
Creates a new prompt from the specified prompt with the provided text content prepended to the start of existing system message content.
If no system message exists in the specified prompt, the provided content will be used to create a system message.
Signature
declare const prependSystem: {
(content: string): (self: Prompt) => Prompt;
(self: Prompt, content: string): Prompt;
};Example
import { Prompt } from "@effect/ai"
const systemPrompt = Prompt.make([
{
role: "system",
content: "You are an expert in programming.",
},
])
const userPrompt = Prompt.make("Hello, world!")
const prompt = Prompt.merge(systemPrompt, userPrompt)
const replaced = Prompt.prependSystem(prompt, "You are a helpful assistant. ")
// result content: "You are a helpful assistant. You are an expert in programming."Creates a new prompt from the specified prompt with the system message set to the specified text content.
NOTE: This method will remove and replace any previous system message from the prompt.
Signature
declare const setSystem: {
(content: string): (self: Prompt) => Prompt;
(self: Prompt, content: string): Prompt;
};Example
import { Prompt } from "@effect/ai"
const systemPrompt = Prompt.make([
{
role: "system",
content: "You are a helpful assistant.",
},
])
const userPrompt = Prompt.make("Hello, world!")
const prompt = Prompt.merge(systemPrompt, userPrompt)
const replaced = Prompt.setSystem(prompt, "You are an expert in programming")Constructors
assistantMessage
Constructs a new assistant message.
Signature
declare function assistantMessage(
params: MessageConstructorParams<AssistantMessage>,
): AssistantMessage;An empty prompt with no messages.
Signature
declare const empty: Prompt;Example
import { Prompt } from "@effect/ai"
const emptyPrompt = Prompt.empty
console.log(emptyPrompt.content) // []Constructs a new file part.
Signature
declare function filePart(params: PartConstructorParams<FilePart>): FilePart;fromMessages
Creates a Prompt from an array of messages.
Signature
declare function fromMessages(messages: readonly Array<Message>): PromptfromResponseParts
Creates a Prompt from the response parts of a previous interaction with a large language model.
Converts streaming or non-streaming AI response parts into a structured prompt, typically for use in conversation history or further processing.
Signature
declare function fromResponseParts(parts: readonly Array<AnyPart>): PromptCreates a Prompt from an input.
This is the primary constructor for creating prompts, supporting multiple input formats for convenience and flexibility.
Signature
declare function make(input: RawInput): Prompt;makeMessage
Creates a new message with the specified role.
Signature
declare function makeMessage<Role extends "user" | "assistant" | "system" | "tool">(
role: Role,
params: Omit<
| Extract<
SystemMessage,
{
role: Role;
}
>
| Extract<
UserMessage,
{
role: Role;
}
>
| Extract<
AssistantMessage,
{
role: Role;
}
>
| Extract<
ToolMessage,
{
role: Role;
}
>,
"role" | "options" | "~effect/ai/Prompt/Message"
> & {
readonly options?:
| Extract<
SystemMessage,
{
role: Role;
}
>
| Extract<
UserMessage,
{
role: Role;
}
>
| Extract<
AssistantMessage,
{
role: Role;
}
>
| Extract<
ToolMessage,
{
role: Role;
}
>["options"];
},
):
| Extract<
SystemMessage,
{
role: Role;
}
>
| Extract<
UserMessage,
{
role: Role;
}
>
| Extract<
AssistantMessage,
{
role: Role;
}
>
| Extract<
ToolMessage,
{
role: Role;
}
>;Creates a new content part of the specified type.
Signature
declare function makePart<Type extends "text" | "reasoning" | "file" | "tool-call" | "tool-result">(
type: Type,
params: Omit<
| Extract<
TextPart,
{
type: Type;
}
>
| Extract<
ReasoningPart,
{
type: Type;
}
>
| Extract<
FilePart,
{
type: Type;
}
>
| Extract<
ToolCallPart,
{
type: Type;
}
>
| Extract<
ToolResultPart,
{
type: Type;
}
>,
"type" | "~effect/ai/Prompt/Part" | "options"
> & {
readonly options?:
| Extract<
TextPart,
{
type: Type;
}
>
| Extract<
ReasoningPart,
{
type: Type;
}
>
| Extract<
FilePart,
{
type: Type;
}
>
| Extract<
ToolCallPart,
{
type: Type;
}
>
| Extract<
ToolResultPart,
{
type: Type;
}
>["options"];
},
):
| Extract<
TextPart,
{
type: Type;
}
>
| Extract<
ReasoningPart,
{
type: Type;
}
>
| Extract<
FilePart,
{
type: Type;
}
>
| Extract<
ToolCallPart,
{
type: Type;
}
>
| Extract<
ToolResultPart,
{
type: Type;
}
>;reasoningPart
Constructs a new reasoning part.
Signature
declare function reasoningPart(params: PartConstructorParams<ReasoningPart>): ReasoningPart;systemMessage
Constructs a new system message.
Signature
declare function systemMessage(params: MessageConstructorParams<SystemMessage>): SystemMessage;Constructs a new text part.
Signature
declare function textPart(params: PartConstructorParams<TextPart>): TextPart;toolCallPart
Constructs a new tool call part.
Signature
declare function toolCallPart(params: PartConstructorParams<ToolCallPart>): ToolCallPart;toolMessage
Constructs a new tool message.
Signature
declare function toolMessage(params: MessageConstructorParams<ToolMessage>): ToolMessage;toolResultPart
Constructs a new tool result part.
Signature
declare function toolResultPart(params: PartConstructorParams<ToolResultPart>): ToolResultPart;userMessage
Constructs a new user message.
Signature
declare function userMessage(params: MessageConstructorParams<UserMessage>): UserMessage;Guards
Type guard to check if a value is a Message.
Signature
declare function isMessage(u: unknown): u is Message;Type guard to check if a value is a Part.
Signature
declare function isPart(u: unknown): u is Part;Type guard to check if a value is a Prompt.
Signature
declare function isPrompt(u: unknown): u is Prompt;Models
AssistantMessage interface
Message representing large language model assistant responses.
Signature
interface AssistantMessage extends BaseMessage<"assistant", AssistantMessageOptions> {
readonly content: readonly Array<AssistantMessagePart>;
}Example
import { Prompt } from "@effect/ai"
const assistantMessage: Prompt.AssistantMessage = Prompt.makeMessage("assistant", {
content: [
Prompt.makePart("text", {
text: "The user is asking about the weather. I should use the weather tool.",
}),
Prompt.makePart("tool-call", {
id: "call_123",
name: "get_weather",
params: { city: "San Francisco" },
providerExecuted: false,
}),
Prompt.makePart("tool-result", {
id: "call_123",
name: "get_weather",
isFailure: false,
result: {
temperature: 72,
condition: "sunny",
},
providerExecuted: false,
}),
Prompt.makePart("text", {
text: "The weather in San Francisco is currently 72°F and sunny.",
}),
],
})AssistantMessageEncoded interface
Encoded representation of assistant messages for serialization.
Signature
interface AssistantMessageEncoded extends BaseMessageEncoded<"assistant", AssistantMessageOptions> {
readonly content: string | readonly Array<AssistantMessagePartEncoded>;
}AssistantMessagePart type
Union type of content parts allowed in assistant messages.
Signature
type AssistantMessagePart = TextPart | FilePart | ReasoningPart | ToolCallPart | ToolResultPart;AssistantMessagePartEncoded type
Union type of encoded content parts for assistant messages.
Signature
type AssistantMessagePartEncoded =
| TextPartEncoded
| FilePartEncoded
| ReasoningPartEncoded
| ToolCallPartEncoded
| ToolResultPartEncoded;BaseMessage interface
Base interface for all message types.
Provides common structure including role and provider options.
Signature
interface BaseMessage<Role extends string, Options extends ProviderOptions> {
readonly "~effect/ai/Prompt/Message": "~effect/ai/Prompt/Message";
readonly options: Options;
readonly role: Role;
}BaseMessageEncoded interface
Base interface for encoded message types.
Signature
interface BaseMessageEncoded<Role extends string, Options extends ProviderOptions> {
readonly options?: Options;
readonly role: Role;
}Base interface for all content parts.
Provides common structure including type and provider options.
Signature
interface BasePart<Type extends string, Options extends ProviderOptions> {
readonly "~effect/ai/Prompt/Part": "~effect/ai/Prompt/Part";
readonly options: Options;
readonly type: Type;
}BasePartEncoded interface
Base interface for encoded content parts.
Signature
interface BasePartEncoded<Type extends string, Options extends ProviderOptions> {
readonly options?: Options;
readonly type: Type;
}Content part representing a file attachment. Files can be provided as base64 strings of data, byte arrays, or URLs.
Supports various file types including images, documents, and binary data.
Signature
interface FilePart extends BasePart<"file", FilePartOptions> {
readonly data: string | Uint8Array<ArrayBufferLike> | URL;
readonly fileName?: string;
readonly mediaType: string;
}Example
import { Prompt } from "@effect/ai"
const imagePart: Prompt.FilePart = Prompt.makePart("file", {
mediaType: "image/jpeg",
fileName: "photo.jpg",
data: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...",
})
const documentPart: Prompt.FilePart = Prompt.makePart("file", {
mediaType: "application/pdf",
fileName: "report.pdf",
data: new Uint8Array([1, 2, 3]),
})FilePartEncoded interface
Encoded representation of file parts for serialization.
Signature
interface FilePartEncoded extends BasePartEncoded<"file", FilePartOptions> {
readonly data: string | Uint8Array<ArrayBufferLike> | URL;
readonly fileName?: string;
readonly mediaType: string;
}A type representing all possible message types in a conversation.
Signature
type Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage;MessageEncoded type
A type representing all possible encoded message types for serialization.
Signature
type MessageEncoded =
| SystemMessageEncoded
| UserMessageEncoded
| AssistantMessageEncoded
| ToolMessageEncoded;Union type representing all possible content parts within messages.
Parts are the building blocks of message content, supporting text, files, reasoning, tool calls, and tool results.
Signature
type Part = TextPart | ReasoningPart | FilePart | ToolCallPart | ToolResultPart;PartEncoded type
Encoded representation of a Part.
Signature
type PartEncoded =
| TextPartEncoded
| ReasoningPartEncoded
| FilePartEncoded
| ToolCallPartEncoded
| ToolResultPartEncoded;A Prompt contains a sequence of messages that form the context of a conversation with a large language model.
Signature
interface Prompt extends Pipeable {
readonly "~@effect/ai/Prompt": "~@effect/ai/Prompt";
readonly content: readonly Array<Message>;
}PromptEncoded interface
Encoded representation of prompts for serialization.
Signature
interface PromptEncoded {
readonly content: readonly Array<MessageEncoded>;
}ProviderOptions
Schema for provider-specific options which can be attached to both content parts and messages, enabling provider-specific behavior.
Provider-specific options are namespaced by provider and have the structure:
Signature
declare const ProviderOptions: $Record<Key, Constraint>;Example
{
"<provider-specific-key>": {
// Provider-specific options
}
}ProviderOptions type
Signature
type ProviderOptions = typeof ProviderOptions.Type;Raw input types that can be converted into a Prompt.
Supports various input formats for convenience, including simple strings, message arrays, response parts, and existing prompts.
Signature
type RawInput = string | Iterable<MessageEncoded> | Prompt;Example
import { Prompt } from "@effect/ai"
// String input - creates a user message
const stringInput: Prompt.RawInput = "Hello, world!"
// Message array input
const messagesInput: Prompt.RawInput = [
{ role: "system", content: "You are helpful." },
{ role: "user", content: [{ type: "text", text: "Hi!" }] },
]
// Existing prompt
declare const existingPrompt: Prompt.Prompt
const promptInput: Prompt.RawInput = existingPromptReasoningPart interface
Content part representing reasoning or chain-of-thought.
Signature
interface ReasoningPart extends BasePart<"reasoning", ReasoningPartOptions> {
readonly text: string;
}Example
import { Prompt } from "@effect/ai"
const reasoningPart: Prompt.ReasoningPart = Prompt.makePart("reasoning", {
text: "Let me think step by step: First I need to understand the user's question...",
})ReasoningPartEncoded interface
Encoded representation of reasoning parts for serialization.
Signature
interface ReasoningPartEncoded extends BasePartEncoded<"reasoning", ReasoningPartOptions> {
readonly text: string;
}SystemMessage interface
Message representing system instructions or context.
Signature
interface SystemMessage extends BaseMessage<"system", SystemMessageOptions> {
readonly content: string;
}Example
import { Prompt } from "@effect/ai"
const systemMessage: Prompt.SystemMessage = Prompt.makeMessage("system", {
content:
"You are a helpful assistant specialized in mathematics. " +
"Always show your work step by step.",
})SystemMessageEncoded interface
Encoded representation of system messages for serialization.
Signature
interface SystemMessageEncoded extends BaseMessageEncoded<"system", SystemMessageOptions> {
readonly content: string;
}Content part representing plain text.
The most basic content type used for textual information in messages.
Signature
interface TextPart extends BasePart<"text", TextPartOptions> {
readonly text: string;
}Example
import { Prompt } from "@effect/ai"
const textPart: Prompt.TextPart = Prompt.makePart("text", {
text: "Hello, how can I help you today?",
})TextPartEncoded interface
Encoded representation of text parts for serialization.
Signature
interface TextPartEncoded extends BasePartEncoded<"text", TextPartOptions> {
readonly text: string;
}ToolCallPart interface
Content part representing a tool call request.
Signature
interface ToolCallPart extends BasePart<"tool-call", ToolCallPartOptions> {
readonly id: string;
readonly name: string;
readonly params: unknown;
readonly providerExecuted: boolean;
}Example
import { Prompt } from "@effect/ai"
const toolCallPart: Prompt.ToolCallPart = Prompt.makePart("tool-call", {
id: "call_123",
name: "get_weather",
params: { city: "San Francisco", units: "celsius" },
providerExecuted: false,
})ToolCallPartEncoded interface
Encoded representation of tool call parts for serialization.
Signature
interface ToolCallPartEncoded extends BasePartEncoded<"tool-call", ToolCallPartOptions> {
readonly id: string;
readonly name: string;
readonly params: unknown;
readonly providerExecuted?: boolean;
}ToolMessage interface
Message representing tool execution results.
Signature
interface ToolMessage extends BaseMessage<"tool", ToolMessageOptions> {
readonly content: readonly Array<ToolResultPart>;
}Example
import { Prompt } from "@effect/ai"
const toolMessage: Prompt.ToolMessage = Prompt.makeMessage("tool", {
content: [
Prompt.makePart("tool-result", {
id: "call_123",
name: "search_web",
isFailure: false,
result: {
query: "TypeScript best practices",
results: [
{ title: "TypeScript Handbook", url: "https://..." },
{ title: "Effective TypeScript", url: "https://..." },
],
},
providerExecuted: false,
}),
],
})ToolMessageEncoded interface
Encoded representation of tool messages for serialization.
Signature
interface ToolMessageEncoded extends BaseMessageEncoded<"tool", ToolMessageOptions> {
readonly content: readonly Array<ToolResultPartEncoded>;
}ToolMessagePart type
Union type of content parts allowed in tool messages.
Signature
type ToolMessagePart = ToolResultPart;ToolMessagePartEncoded type
Union type of encoded content parts for tool messages.
Signature
type ToolMessagePartEncoded = ToolResultPartEncoded;ToolResultPart interface
Content part representing the result of a tool call.
Signature
interface ToolResultPart extends BasePart<"tool-result", ToolResultPartOptions> {
readonly id: string;
readonly isFailure: boolean;
readonly name: string;
readonly providerExecuted: boolean;
readonly result: unknown;
}Example
import { Prompt } from "@effect/ai"
const toolResultPart: Prompt.ToolResultPart = Prompt.makePart("tool-result", {
id: "call_123",
name: "get_weather",
isFailure: false,
result: {
temperature: 22,
condition: "sunny",
humidity: 65,
},
providerExecuted: false,
})ToolResultPartEncoded interface
Encoded representation of tool result parts for serialization.
Signature
interface ToolResultPartEncoded extends BasePartEncoded<"tool-result", ToolResultPartOptions> {
readonly id: string;
readonly isFailure: boolean;
readonly name: string;
readonly providerExecuted: boolean;
readonly result: unknown;
}UserMessage interface
Message representing user input or questions.
Signature
interface UserMessage extends BaseMessage<"user", UserMessageOptions> {
readonly content: readonly Array<UserMessagePart>;
}Example
import { Prompt } from "@effect/ai"
const textUserMessage: Prompt.UserMessage = Prompt.makeMessage("user", {
content: [
Prompt.makePart("text", {
text: "Can you analyze this image for me?",
}),
],
})
const multimodalUserMessage: Prompt.UserMessage = Prompt.makeMessage("user", {
content: [
Prompt.makePart("text", {
text: "What do you see in this image?",
}),
Prompt.makePart("file", {
mediaType: "image/jpeg",
fileName: "vacation.jpg",
data: "data:image/jpeg;base64,...",
}),
],
})UserMessageEncoded interface
Encoded representation of user messages for serialization.
Signature
interface UserMessageEncoded extends BaseMessageEncoded<"user", UserMessageOptions> {
readonly content: string | readonly Array<UserMessagePartEncoded>;
}UserMessagePart type
Union type of content parts allowed in user messages.
Signature
type UserMessagePart = TextPart | FilePart;UserMessagePartEncoded type
Union type of encoded content parts for user messages.
Signature
type UserMessagePartEncoded = TextPartEncoded | FilePartEncoded;ProviderOptions
AssistantMessageOptions interface
Represents provider-specific options that can be associated with a AssistantMessage through module augmentation.
Signature
interface AssistantMessageOptions extends ProviderOptions {
[key: string]: unknown;
[key: number]: unknown;
[key: symbol]: unknown;
}FilePartOptions interface
Represents provider-specific options that can be associated with a FilePart through module augmentation.
Signature
interface FilePartOptions extends ProviderOptions {
[key: string]: unknown;
[key: number]: unknown;
[key: symbol]: unknown;
}ReasoningPartOptions interface
Represents provider-specific options that can be associated with a ReasoningPart through module augmentation.
Signature
interface ReasoningPartOptions extends ProviderOptions {
[key: string]: unknown;
[key: number]: unknown;
[key: symbol]: unknown;
}SystemMessageOptions interface
Represents provider-specific options that can be associated with a SystemMessage through module augmentation.
Signature
interface SystemMessageOptions extends ProviderOptions {
[key: string]: unknown;
[key: number]: unknown;
[key: symbol]: unknown;
}TextPartOptions interface
Represents provider-specific options that can be associated with a TextPart through module augmentation.
Signature
interface TextPartOptions extends ProviderOptions {
[key: string]: unknown;
[key: number]: unknown;
[key: symbol]: unknown;
}ToolCallPartOptions interface
Represents provider-specific options that can be associated with a ToolCallPart through module augmentation.
Signature
interface ToolCallPartOptions extends ProviderOptions {
[key: string]: unknown;
[key: number]: unknown;
[key: symbol]: unknown;
}ToolMessageOptions interface
Represents provider-specific options that can be associated with a ToolMessage through module augmentation.
Signature
interface ToolMessageOptions extends ProviderOptions {
[key: string]: unknown;
[key: number]: unknown;
[key: symbol]: unknown;
}ToolResultPartOptions interface
Represents provider-specific options that can be associated with a ToolResultPart through module augmentation.
Signature
interface ToolResultPartOptions extends ProviderOptions {
[key: string]: unknown;
[key: number]: unknown;
[key: symbol]: unknown;
}UserMessageOptions interface
Represents provider-specific options that can be associated with a UserMessage through module augmentation.
Signature
interface UserMessageOptions extends ProviderOptions {
[key: string]: unknown;
[key: number]: unknown;
[key: symbol]: unknown;
}Schemas
AssistantMessage
Schema for validation and encoding of assistant messages.
Signature
declare const AssistantMessage: any;Schema for validation and encoding of file parts.
Signature
declare const FilePart: any;Schema for parsing a Prompt from JSON strings.
Signature
declare const FromJson: any;Schema for validation and encoding of messages.
Signature
declare const Message: any;MessageContentFromString
Schema for decoding message content (i.e. an array containing a single TextPart) from a string.
Signature
declare const MessageContentFromString: Schema.Schema<Arr.NonEmptyReadonlyArray<TextPart>, string>;Schema for validation and encoding of prompts.
Signature
declare const Prompt: any;PromptFromSelf
Describes a schema that represents a Prompt instance.
Signature
declare class PromptFromSelf extends any {
constructor();
}ReasoningPart
Schema for validation and encoding of reasoning parts.
Signature
declare const ReasoningPart: any;SystemMessage
Schema for validation and encoding of system messages.
Signature
declare const SystemMessage: any;Schema for validation and encoding of text parts.
Signature
declare const TextPart: any;ToolCallPart
Schema for validation and encoding of tool call parts.
Signature
declare const ToolCallPart: any;ToolMessage
Schema for validation and encoding of tool messages.
Signature
declare const ToolMessage: any;ToolResultPart
Schema for validation and encoding of tool result parts.
Signature
declare const ToolResultPart: any;UserMessage
Schema for validation and encoding of user messages.
Signature
declare const UserMessage: any;Type Ids
MessageTypeId
Unique identifier for Message instances.
Signature
declare const MessageTypeId: "~effect/ai/Prompt/Message";MessageTypeId type
Type-level representation of the Message identifier.
Signature
type MessageTypeId = typeof MessageTypeId;PartTypeId
Unique identifier for Part instances.
Signature
declare const PartTypeId: "~effect/ai/Prompt/Part";PartTypeId type
Type-level representation of the Part identifier.
Signature
type PartTypeId = typeof PartTypeId;Unique identifier for Prompt instances.
Signature
declare const TypeId: "~@effect/ai/Prompt";Type-level representation of the Prompt identifier.
Signature
type TypeId = typeof TypeId;Utility Types
MessageConstructorParams type
A utility type for specifying the parameters required to construct a specific message for a prompt.
Signature
type MessageConstructorParams<M extends Message> = Omit<M, MessageTypeId | "role" | "options"> & {
readonly options?: Part["options"];
};PartConstructorParams type
A utility type for specifying the parameters required to construct a specific part of a prompt.
Signature
type PartConstructorParams<P extends Part> = Omit<P, PartTypeId | "type" | "options"> & {
readonly options?: Part["options"];
};
Creates a new prompt from the specified prompt with the provided text content appended to the end of existing system message content.
If no system message exists in the specified prompt, the provided content will be used to create a system message.