Constructing messages for language model requests
Building multi-turn conversation history
Adding system instructions to prompts
Integrating tool calls and results into conversations
Converting streaming responses to prompt history
Managing file/image attachments in messages
Implementing custom chat interfaces

Conceptual Model

-- Message hierarchy
type Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage
type Part = TextPart | ReasoningPart | FilePart | ToolCallPart | ToolResultPart

-- Composition
Prompt.make       :: RawInput → Prompt
Prompt.concat      :: (Prompt, RawInput) → Prompt
Prompt.setSystem  :: (Prompt, String) → Prompt

-- History transformation
fromResponseParts :: ReadonlyArray<Response.Part> → Prompt

Message Types

Each message has role and content. Content is an array of Part objects.

System Messages

import * as Prompt from 'effect/unstable/ai/Prompt';

// String content only
const system = Prompt.makeMessage('system', {
	content: 'You are a helpful assistant specialized in mathematics.'
});

// Shorthand constructor
const systemShorthand = Prompt.systemMessage({
	content: 'You are a helpful assistant specialized in mathematics.'
});

// System message with options
const systemWithOptions = Prompt.makeMessage('system', {
	content: 'You are an expert coder.',
	options: {
		anthropic: { cache_control: { type: 'ephemeral' } }
	}
});

User Messages

// Text-only user message
const userText = Prompt.makeMessage("user", {
  content: [
    Prompt.makePart("text", { text: "What is 2+2?" })
  ]
})

// Shorthand constructor
const userShorthand = Prompt.userMessage({
  content: [
    Prompt.makePart("text", { text: "What is 2+2?" })
  ]
})

// Multimodal user message (text + file)
const userMultimodal = Prompt.makeMessage("user", {
  content: [
    Prompt.makePart("text", { text: "What's in this image?" }),
    Prompt.makePart("file", {
      mediaType: "image/jpeg",
      fileName: "photo.jpg",
      data: new Uint8Array([...])
    })
  ]
})

Assistant Messages

// Assistant response with text and tool call
const assistant = Prompt.makeMessage('assistant', {
	content: [
		Prompt.makePart('reasoning', {
			text: 'I need to check the weather using the tool.'
		}),
		Prompt.makePart('tool-call', {
			id: 'call_123',
			name: 'get_weather',
			params: { city: 'Paris' },
			providerExecuted: false
		}),
		Prompt.makePart('text', {
			text: 'The weather in Paris is sunny, 22°C.'
		})
	]
});

// Shorthand constructor
const assistantShorthand = Prompt.assistantMessage({
	content: [
		Prompt.makePart('text', {
			text: 'The weather in Paris is sunny, 22°C.'
		})
	]
});

Tool Messages

// Tool execution results
const toolMessage = Prompt.makeMessage('tool', {
	content: [
		Prompt.makePart('tool-result', {
			id: 'call_123',
			name: 'get_weather',
			isFailure: false,
			result: { temperature: 22, condition: 'sunny' }
		})
	]
});

// Shorthand constructor
const toolShorthand = Prompt.toolMessage({
	content: [
		Prompt.makePart('tool-result', {
			id: 'call_123',
			name: 'get_weather',
			isFailure: false,
			result: { temperature: 22, condition: 'sunny' }
		})
	]
});

Part Types

Text Part

const textPart = Prompt.makePart('text', {
	text: 'Hello, world!'
});

Reasoning Part

const reasoningPart = Prompt.makePart('reasoning', {
	text: 'Let me think step by step...'
});

File Part

// From URL
const fileFromUrl = Prompt.makePart('file', {
	mediaType: 'image/png',
	fileName: 'screenshot.png',
	data: new URL('https://example.com/image.png')
});

// From bytes
const fileFromBytes = Prompt.makePart('file', {
	mediaType: 'application/pdf',
	fileName: 'report.pdf',
	data: new Uint8Array([1, 2, 3])
});

// From base64
const fileFromBase64 = Prompt.makePart('file', {
	mediaType: 'image/jpeg',
	data: 'data:image/jpeg;base64,/9j/4AAQ...'
});

Tool Call Part

const toolCall = Prompt.makePart('tool-call', {
	id: 'call_abc123',
	name: 'calculate',
	params: { expression: '2 + 2' },
	providerExecuted: false
});

Tool Result Part

const toolResult = Prompt.makePart('tool-result', {
	id: 'call_abc123',
	name: 'calculate',
	isFailure: false,
	result: 4
});

Prompt Construction

From String

// Creates a user message with text part
const prompt = Prompt.make('Hello, how are you?');

From Messages

const prompt = Prompt.make([
	{ role: 'system', content: 'You are helpful.' },
	{ role: 'user', content: [{ type: 'text', text: 'Hi!' }] }
]);

From Existing Prompt

const copy = Prompt.make(existingPrompt);

Empty Prompt

const empty = Prompt.empty;

From Messages Array

// Using fromMessages constructor
const messages: ReadonlyArray<Prompt.Message> = [
	Prompt.systemMessage({ content: 'You are an expert.' }),
	Prompt.userMessage({
		content: [Prompt.makePart('text', { text: 'Help me.' })]
	})
];

const prompt = Prompt.fromMessages(messages);

// Alternative: Using make with messages array
const prompt2 = Prompt.make([
	Prompt.makeMessage('system', { content: 'You are an expert.' }),
	Prompt.makeMessage('user', {
		content: [Prompt.makePart('text', { text: 'Help me.' })]
	})
]);

Prompt Composition

Merge Prompts

import { pipe } from 'effect';

const systemPrompt = Prompt.make([
	{
		role: 'system',
		content: 'You are a coding assistant.'
	}
]);

const userPrompt = Prompt.make('Write a function');

// Data-last (pipeline)
const combined = pipe(systemPrompt, Prompt.concat(userPrompt));

// Data-first
const combined2 = Prompt.concat(systemPrompt, userPrompt);

System Message Manipulation

import { pipe } from 'effect';

const prompt = Prompt.make([
	{ role: 'system', content: 'You are helpful.' },
	{ role: 'user', content: [{ type: 'text', text: 'Hi' }] }
]);

// Replace system message
const replaced = pipe(
	prompt,
	Prompt.setSystem('You are an expert in TypeScript.')
);

// Prepend to system message
const prepended = pipe(prompt, Prompt.prependSystem('IMPORTANT: '));
// Result: "IMPORTANT: You are helpful."

// Append to system message
const appended = pipe(prompt, Prompt.appendSystem(' Be concise.'));
// Result: "You are helpful. Be concise."

History Management

Convert AI Response to Prompt

import * as Response from 'effect/unstable/ai/Response';

const responseParts: ReadonlyArray<Response.AnyPart> = [
	Response.makePart('text', { text: 'Hello!' }),
	Response.makePart('tool-call', {
		id: 'call_1',
		name: 'get_time',
		params: {},
		providerExecuted: false
	}),
	Response.makePart('tool-result', {
		id: 'call_1',
		name: 'get_time',
		isFailure: false,
		result: '10:30 AM',
		encodedResult: '10:30 AM',
		providerExecuted: false
	})
];

// Converts to assistant + tool messages
const historyPrompt = Prompt.fromResponseParts(responseParts);

Effect-Returning Prompt/Message Helpers

Keep pure prompt helpers pure. But when prompt or message transformation depends on services, model metadata, truncation policy, storage, or other runtime state, wrap the transformation in Effect.fn(...) so orchestrators can yield* it directly.

import { Effect } from 'effect';

export const toModelMessagesEffect = Effect.fn('Prompt.toModelMessages')(
	function* (messages: ReadonlyArray<AppMessage>) {
		const policy = yield* MessagePolicy.Service;
		return convertMessages(messages, policy);
	}
);

This keeps prompt assembly inside the Effect graph instead of forcing Promise islands through session orchestration code.

Typical Chat Pattern

import { Effect } from 'effect';
import * as SubscriptionRef from 'effect/SubscriptionRef';
import * as LanguageModel from 'effect/unstable/ai/LanguageModel';

const chat = Effect.gen(function* () {
	const history = yield* SubscriptionRef.make(Prompt.empty);

	function* generateText(userInput: string) {
		const currentHistory = yield* SubscriptionRef.get(history);
		const prompt = pipe(currentHistory, Prompt.concat(userInput));

		const response = yield* LanguageModel.generateText({ prompt });

		// Update history with user input + response
		const newHistory = pipe(
			prompt,
			Prompt.concat(Prompt.fromResponseParts(response.content))
		);
		yield* SubscriptionRef.set(history, newHistory);

		return response;
	}

	return { generateText };
});

Usage with LanguageModel

Generate Text

import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
import { Effect } from 'effect';

const program = Effect.gen(function* () {
	const prompt = Prompt.make([
		{ role: 'system', content: 'You are helpful.' },
		{ role: 'user', content: [{ type: 'text', text: 'Explain Effect' }] }
	]);

	const response = yield* LanguageModel.generateText({ prompt });

	return response.content;
});

Stream Text

import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
import { Effect, Stream } from 'effect';

const program = Effect.gen(function* () {
	const prompt = Prompt.make('Write a story');

	yield* LanguageModel.streamText({ prompt }).pipe(
		Stream.runForEach((part) =>
			part.type === 'text-delta'
				? Effect.sync(() => process.stdout.write(part.delta))
				: Effect.void
		)
	);
});

Generate Object

import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
import { Effect, Schema } from 'effect';

const Contact = Schema.Struct({
	name: Schema.String,
	email: Schema.String,
	phone: Schema.optional(Schema.String)
});

const program = Effect.gen(function* () {
	const prompt = Prompt.make('Extract: John Doe, john@example.com, 555-1234');

	const response = yield* LanguageModel.generateObject({
		prompt,
		schema: Contact
	});

	return response.value;
});

Provider-Specific Options

// Augment options interfaces via module augmentation
declare module 'effect/unstable/ai/Prompt' {
	interface TextPartOptions {
		readonly anthropic?: {
			readonly cache_control?: {
				readonly type: 'ephemeral';
			};
		};
	}
}

// Use in parts
const cachedPart = Prompt.makePart('text', {
	text: 'Large document...',
	options: {
		anthropic: { cache_control: { type: 'ephemeral' } }
	}
});

// Use in messages
const cachedMessage = Prompt.makeMessage('system', {
	content: 'You are an expert.',
	options: {
		anthropic: { cache_control: { type: 'ephemeral' } }
	}
});

Serialization

Export/Import

import * as Schema from 'effect/Schema';
import { Effect } from 'effect';

// Prompt.Prompt is a Schema.Codec<Prompt, PromptEncoded>
const encode = Schema.encodeEffect(Prompt.Prompt);
const decode = Schema.decodeUnknownEffect(Prompt.Prompt);

const program = Effect.gen(function* () {
	const prompt = Prompt.make('Hello');

	// Export to structured data
	const exported = yield* encode(prompt);

	// Import from structured data
	const imported = yield* decode(exported);

	return imported;
});

JSON Serialization

Use Schema.fromJsonString with Prompt.Prompt to create a JSON codec:

import * as Schema from 'effect/Schema';
import { Effect } from 'effect';

const PromptJson = Schema.fromJsonString(Prompt.Prompt);
const encodeJson = Schema.encodeEffect(PromptJson);
const decodeJson = Schema.decodeUnknownEffect(PromptJson);

const program = Effect.gen(function* () {
	const prompt = Prompt.make([
		{ role: 'system', content: 'You are helpful.' },
		{ role: 'user', content: [{ type: 'text', text: 'Hi' }] }
	]);

	// To JSON string
	const json = yield* encodeJson(prompt);
	yield* Effect.log(json); // string

	// From JSON string
	const restored = yield* decodeJson(json);

	return restored;
});

Note: There is no Prompt.FromJson in v4. Use Schema.fromJsonString(Prompt.Prompt) instead.

Common Patterns

Multi-turn Conversation

const conversation = Prompt.make([
	{ role: 'system', content: 'You are a math tutor.' },
	{ role: 'user', content: [{ type: 'text', text: 'What is 2+2?' }] },
	{ role: 'assistant', content: [{ type: 'text', text: '2+2 equals 4.' }] },
	{ role: 'user', content: [{ type: 'text', text: 'What about 3+3?' }] }
]);

Dynamic System Prompt

import { pipe } from 'effect';

function withSystemPrompt(content: string) {
	return (prompt: Prompt.Prompt) => pipe(prompt, Prompt.setSystem(content));
}

const userPrompt = Prompt.make('Help me code');
const withContext = pipe(
	userPrompt,
	withSystemPrompt('You are an expert TypeScript developer.')
);

Tool Interaction History

const toolInteraction = Prompt.make([
	{ role: 'user', content: [{ type: 'text', text: "What's the weather?" }] },
	{
		role: 'assistant',
		content: [
			{
				type: 'tool-call',
				id: '1',
				name: 'weather',
				params: {},
				providerExecuted: false
			}
		]
	},
	{
		role: 'tool',
		content: [
			{
				type: 'tool-result',
				id: '1',
				name: 'weather',
				isFailure: false,
				result: 'Sunny, 22°C'
			}
		]
	},
	{
		role: 'assistant',
		content: [{ type: 'text', text: "It's sunny and 22°C." }]
	}
]);

Type Guards

import * as Prompt from 'effect/unstable/ai/Prompt';

declare const value: unknown;

if (Prompt.isPrompt(value)) {
	// value: Prompt.Prompt
	value.content; // narrowed to Prompt.Prompt
}

if (Prompt.isMessage(value)) {
	// value: Prompt.Message
	value.role; // narrowed to Prompt.Message
}

if (Prompt.isPart(value)) {
	// value: Prompt.Part
	value.type; // narrowed to Prompt.Part
}

Anti-Patterns

// DON'T: Manually construct messages without constructors
const bad = {
	role: 'user',
	content: [{ type: 'text', text: 'Hello' }]
} as Prompt.UserMessage;

// DO: Use constructors
const good = Prompt.makeMessage('user', {
	content: [Prompt.makePart('text', { text: 'Hello' })]
});

// DO: Use shorthand constructors
const better = Prompt.userMessage({
	content: [Prompt.makePart('text', { text: 'Hello' })]
});

// DON'T: Mutate prompt content
const prompt = Prompt.make('Hi');
prompt.content.push(someMessage); // Error: readonly

// DO: Use merge for composition
const extended = Prompt.concat(prompt, 'Additional message');

// DON'T: Manually filter response parts
const filtered = responseParts.filter((p) => p.type === 'text');

// DO: Use fromResponseParts (handles streaming deltas, tool results, etc.)
const historyPrompt = Prompt.fromResponseParts(responseParts);

Related Skills

effect-ai-language-model - Using prompts with LanguageModel service
effect-ai-streaming - Converting streaming responses to prompt history
effect-ai-tool - Integrating tool call/result messages

Quality Checklist

Messages use Prompt.makeMessage or shorthand constructors
Parts use Prompt.makePart constructors
System messages managed with setSystem/prependSystem/appendSystem
History updates use Prompt.fromResponseParts
Prompt composition uses Prompt.concat (not mutation)
Namespace imports for all Effect AI modules

effect-ai-prompt

Effect AI Prompt Construction

Import Patterns

When to Use This Skill