Building AI Agents, Part 3: Prompts: Text, Instructions and Messages

Building AI Agents · Part 3 of 7 · Text, Instructions & Message Prompts · Oct 2026

Quick answer: A prompt is the instruction that tells a large language model what to do, and the clearer the prompt, the better the result. Agents use three kinds: simple text prompts, instructions (system prompts) that constrain behaviour, and message prompts that carry a whole conversation, including files, images and tool calls.

What Is a Prompt?

Prompts are instructions, written by a user or by an agent, that tell a large language model what to do. They set the path the model takes, and the clearer the prompt, the better the action.

Prompts written by people are generally more reliable than prompts written by agents, because they give you direct control over the model's output. When an agent writes prompts for another model, as in multi-agent systems, build in checks so errors don't compound.

Text Prompts

A text prompt is a plain string. It is ideal for simple generation tasks:

prompt: 'What is the capital city of Mpumalanga?',

Because it is a string, you can inject dynamic values with template literals:

prompt:
  `I am planning a trip to ${destination} for ${lengthOfStay} days. ` +
  `Please suggest the best tourist activities for me to do.`,

Instructions (System Prompts)

Instructions, traditionally called the system prompt, constrain the model's behaviour for the whole interaction: its role, tone, format and limits. In AI SDK 7 the setting is called instructions; older versions called it system.

instructions:
  'You help with South African tax questions in terms of SARS rules. ' +
  'Respond in point form only, and only with results relevant to tax law.',

Instructions are also an important security layer. Model providers publish specifications for how their models should rank instructions. These generally give system-level instructions priority over user messages, which helps an agent resist users trying to talk it out of its rules.

Message Prompts

Message prompts are what you will use most when building agents. A message prompt is an array of messages, each with a role (user, assistant, system or tool) and content:

messages: [
  { role: 'user', content: 'Hi!' },
  { role: 'assistant', content: 'Hello, how can I help?' },
  { role: 'user', content: 'Where can I register for VAT?' },
],

Messages let you carry the full history of a conversation, so the model knows what was said before. They also let you shape the flow of a chat by including earlier example turns.

Content Parts

Instead of a plain string, a message's content can be an array of parts that mix text with other content types. This lets you give the model much richer context:

messages: [
  {
    role: 'user',
    content: [
      { type: 'text', text: 'Describe the image in detail.' },
      {
        type: 'file',
        mediaType: 'image',
        data: fs.readFileSync('./data/invoice.png'),
      },
    ],
  },
],

Content parts come in three broad types:

• Text: plain instructions or questions.
• Images: photos, scans and screenshots.
• Files: PDFs, audio, video and other binary data, depending on what the model supports.

This is where agents become powerful for business. For example, you can give an agent a PDF bank statement and ask it to reconcile the transactions, post them to the general ledger using your chart of accounts and prepare financial statements. Or you can give it a photo of an invoice and have it record the transaction.

{
  role: 'user',
  content: [
    { type: 'text', text: 'Reconcile these transactions against the ledger.' },
    {
      type: 'file',
      mediaType: 'application/pdf',
      data: fs.readFileSync('./bank-statement.pdf'),
    },
  ],
},

Assistant and Tool Messages

Content parts work for the assistant role too. When the model decides to call a tool, the assistant message contains a tool-call part, with a tool call ID, the tool's name and the input the model chose. The result comes back in a tool message:

{
  role: 'assistant',
  content: [
    {
      type: 'tool-call',
      toolCallId: '12345',
      toolName: 'getAccountBalance',
      input: { accountCode: '1000' },
    },
  ],
},
{
  role: 'tool',
  content: [
    {
      type: 'tool-result',
      toolCallId: '12345',
      toolName: 'getAccountBalance',
      output: { type: 'json', value: { balance: 25400.5 } },
    },
  ],
},

You rarely write these by hand. The SDK creates them as the agent runs. But understanding them helps when you store conversation history, debug an agent or replay a conversation.

Prompting Tips for Agents

• Be specific about the role, the goal and the output format.
• Put rules that must never be broken in the instructions, not in user messages.
• Give examples of good output when the format matters.
• Pass the documents the agent needs as content parts rather than describing them.
• Test prompts with realistic, messy inputs, not just the happy path.

What's Next

In Part 4 we look at what an agent knows and what it can do: context, memory and tools.

Cover photo: Markus Winkler on Unsplash

Chainbook builds intelligent business systems for African professionals, and AI agents are at the heart of how we build them.