> ## Documentation Index
> Fetch the complete documentation index at: https://docs.re-factor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompts

> Composable building blocks of AI interaction and execution in re-factor.

## Foundations

Prompts are the vehicle for delivering context, instructions, and embedded resources to a large language model. At their core, prompts are a collection of system instructions that govern the behavior of the LLM and the messages that are exchanged between the user and the LLM. Within `re-factor`, these basic prompt components make up the [`CompletionPrompt`](#completionprompt) type.

In the case of agents, prompts also include tools that can be used by the LLM to complete the request outlined in the system and user messages. These prompts make up the [`AgentPrompt`](#agentprompt) type.

## Types

### CompletionPrompt

A completion prompt is one that contains only `system`, `user`, and `assistant` messages. It does not contain `tools`.

<ParamField path="system" type="string">
  A system message that provides context and instructions for the LLM. This is often used to set the overall tone and direction of the conversation.
</ParamField>

<ParamField path="messages" type="array<UserMessage | AssistantMessage>" required>
  An array of messages that define the conversation between the user and the LLM. Each message has a role, content, and optional metadata.

  Can be a [`UserMessage`](#usermessage) or [`AssistantMessage`](#assistantmessage). This field is required and must contain at least one user message and one assistant message.
</ParamField>

### AgentPrompt

Like a completion prompt, an agent prompt may contain `system`, `user`, and `assistant` messages, but it differs in that it also contains a `tools` parameter, which is an array of tools that can be used by the LLM to complete the request outlined in the system and user messages.

<ParamField path="system" type="string">
  A system message that provides context and instructions for the LLM. This is often used to set the overall tone and direction of the conversation.
</ParamField>

<ParamField path="messages" type="array<UserMessage | AssistantMessage>" required>
  An array of messages that define the conversation between the user and the LLM. Each message has a role, content, and optional metadata.

  Can be a [`UserMessage`](#usermessage) or [`AssistantMessage`](#assistantmessage). This field is required and must contain at least one user message and one assistant message.
</ParamField>

<ParamField path="tools" type="array<Tool>" required>
  An array of tools that can be used by the LLM to complete the request outlined in the system and user messages.

  Each item in the array must be a [`Tool`](/guides/runnables/tools#structure) object. This field is required and must contain at least one tool.
</ParamField>

### UserMessage

A user message is a message sent by the user to the LLM. It typically contains a role, content, and optional metadata.

<ParamField path="role" type="string" required>
  The role of the message. For a user message, this should be `"user"`.
</ParamField>

<ParamField path="content" type="string | object" required>
  The content of the message. This is the text that the LLM will process.

  In many cases, this will be a string as you can use [Resource Embedding](/core-concepts/resources#resource-embedding) to interpolate resources into your prompts. However, in the event you want fine grained control, you can also provide any [`Vercel AI SDK CoreUserMessage`](https://sdk.vercel.ai/docs/reference/ai-sdk-core/core-message#coreusermessage) object.
</ParamField>

### AssistantMessage

An assistant message is a message sent by the LLM to the user. It typically contains a role, content, and optional metadata.

<ParamField path="role" type="string" required>
  The role of the message. For an assistant message, this should be `"assistant"`.
</ParamField>

<ParamField path="generate" type="boolean" required>
  A flag indicating whether the message should be generated by the LLM. If `true`, the `content` field should be omitted. If `false`, the `content` field should be provided.
</ParamField>

<ParamField path="format" type="enum<text, object>" default="text">
  The format of the message that will be generated by the LLM. This is required if `generate: true`.
</ParamField>

<ParamField path="set_output" type="string">
  The name of the output variable that will be set with the generated message. This is optional and should be omitted if `generate: false`.
</ParamField>

<ParamField path="schema" type="object">
  The schema of the message. This is required if `generate: true` and `format: object`. Should be a valid [JSONSchema Draft-07](https://json-schema.org/draft-07) object.
</ParamField>

<ParamField path="content" type="string">
  The content of the message. This can be used to set a synthetic response from the LLM. It is optional and should be omitted if `generate: true`.
</ParamField>