Prompts

System prompts and user messages are how you communicate with the model. This guide covers writing both, sending multi-modal input, calling tools directly, and structuring complex instructions as agent SOPs.

System Prompts

A system prompt gives the model high-level instructions about its role, capabilities, and constraints, setting how it behaves across the whole conversation. Set it when you construct the agent:

Python
TypeScript

from strands import Agent

agent = Agent(
    system_prompt=(
        "You are a financial advisor specialized in retirement planning. "
        "Use tools to gather information and provide personalized advice. "
        "Always explain your reasoning and cite sources when possible."
    )
)

const agent = new Agent({
  systemPrompt:
    'You are a financial advisor specialized in retirement planning. ' +
    'Use tools to gather information and provide personalized advice. ' +
    'Always explain your reasoning and cite sources when possible.',
})

Without a system prompt, the model behaves according to its default settings.

User Messages

User messages are your queries and requests to the agent. You can send them several ways.

Python
TypeScript

Text Prompt

The simplest way to interact with an agent is through a text prompt:

Python
TypeScript

response = agent("What is the time in Seattle")

const response = await agent.invoke('What is the time in Seattle')

Include images, documents, and other content types alongside text in a single message:

Python
TypeScript

with open("path/to/image.png", "rb") as fp:
    image_bytes = fp.read()

response = agent([
    {"text": "What can you see in this image?"},
    {
        "image": {
            "format": "png",
            "source": {
                "bytes": image_bytes,
            },
        },
    },
])

const imageBytes = readFileSync('path/to/image.png')

const response = await agent.invoke([
  new TextBlock('What can you see in this image?'),
  new ImageBlock({
    format: 'png',
    source: {
      bytes: new Uint8Array(imageBytes),
    },
  }),
])

For a complete list of supported content types, refer to the API Reference: Python | TypeScript.

Direct Tool Calls

Natural-language prompting is the usual way to invoke tools. When you need programmatic control instead, call a tool directly:

Python
TypeScript

result = agent.tool.current_time(timezone="US/Pacific")

// Not supported in TypeScript

Direct tool calls bypass the natural-language interface and run the tool with the parameters you pass. Strands records them in the conversation history by default; opt out with record_direct_tool_call=FalserecordDirectToolCall: false.

Prompt Engineering

Simple text instructions work for basic tasks. Getting complex, repeatable behavior out of an agent benefits from more structure.

Prompting with Agent SOPs

Agent SOPs (Standard Operating Procedures) are a standardized markdown format for defining agent workflows in natural language. They hit a “determin-ish-tic” sweet spot between fully code-defined workflows and open-ended model-driven agents, providing structure for consistency while preserving the agent’s reasoning ability.

Here is a minimal example of an Agent SOP:

# Code Review SOP

## Parameters
- repo_path (REQUIRED): Path to the repository to review

## Steps

### Step 1: Understand the Changes
- MUST read the diff of all changed files
- SHOULD summarize what the changes are doing at a high level

### Step 2: Review for Issues
- MUST check for bugs, security vulnerabilities, and logic errors
- SHOULD flag any style or readability concerns
- MAY suggest alternative approaches where appropriate

### Step 3: Provide Feedback
- MUST output a structured review with file-level comments
- SHOULD categorize findings by severity (critical, warning, suggestion)

Writing to the Agent SOP format makes the agent’s behavior easier to understand, easier to debug when it strays from instructions, and steerable across different underlying models.

Debugging system prompts is hard and expensive, usually involving costly evaluations to confirm the agent still works as expected. Structuring the system prompt as an SOP turns that editing process into targeted, step-level changes.

For more on authoring and using Agent SOPs, including SOP chaining for multi-phase workflows, see the Agent SOPs GitHub repository.

Safety and Security

For guidance on writing safe and responsible prompts, including defending against prompt injection and adversarial attacks, refer to our Safety & Security - Prompt Engineering documentation.