effect-ai-prompt

name	effect-ai-prompt
description	Build prompts for Effect AI using messages, parts, and composition operators. Covers the complete Prompt API for constructing, merging, and manipulating conversations with language models.

Effect AI Prompt Construction

Master the Effect AI Prompt API for building type-safe conversations with language models.

Import Patterns

CRITICAL: Always use namespace imports:

import * as Prompt from 'effect/unstable/ai/Prompt';
import * as Response from 'effect/unstable/ai/Response';
import { pipe } from 'effect';

When to Use This Skill

• 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
  | ToolApprovalRequestPart
  | ToolApprovalResponsePart

-- 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('tool-approval-request', {
			approvalId: 'approval_123',
			toolCallId: 'call_123'
		}),
		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...'
});

For OpenAI file parts, strings are provider file IDs only when OpenAiLanguageModel.Config.fileIdPrefixes matches the string prefix (for example file-). Use URL or Uint8Array for inline content; the OpenAI adapter encodes bytes as base64 data.

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
});

Tool Approval Parts

const approvalRequest = Prompt.makePart('tool-approval-request', {
	approvalId: 'approval_abc123',
	toolCallId: 'call_abc123'
});

const approvalResponse = Prompt.toolApprovalResponsePart({
	approvalId: 'approval_abc123',
	approved: true
});

const denialResponse = Prompt.toolApprovalResponsePart({
	approvalId: 'approval_def456',
	approved: false,
	reason: 'Operation not allowed'
});

Tool approval requests live in assistant messages. Approval responses live in tool messages and are collected on the next model call.

Prompt Construction

From String

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

From Encoded Messages

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

Prompt.RawInput is exactly string | Iterable<Prompt.MessageEncoded> | Prompt.Prompt: strings become one user text message, iterables are decoded encoded messages, and existing prompts pass through unchanged.

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-start', { id: 'text_1' }),
	Response.makePart('text-delta', { id: 'text_1', delta: 'Hello' }),
	Response.makePart('text-delta', { id: 'text_1', delta: '!' }),
	Response.makePart('text-end', { id: 'text_1' }),
	Response.makePart('tool-call', {
		id: 'call_1',
		name: 'get_time',
		params: {},
		providerExecuted: false
	}),
	Response.makePart('tool-approval-request', {
		approvalId: 'approval_1',
		toolCallId: 'call_1'
	}),
	Response.makePart('tool-result', {
		id: 'call_1',
		name: 'get_time',
		isFailure: false,
		result: '10:30 AM',
		encodedResult: '10:30 AM',
		providerExecuted: false,
		preliminary: false
	})
];

// Folds complete streaming text/reasoning and splits assistant/tool messages.
const historyPrompt = Prompt.fromResponseParts(responseParts);

Prompt.fromResponseParts folds streaming text/reasoning only when the matching start/delta/end parts are present in the same input, places tool calls and approval requests in assistant messages, places non-preliminary tool results in tool messages using encodedResult, and skips preliminary tool results.

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, [e-mail], 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