Agent prompting patterns

Agent Prompting Patterns

Prompting is the most fundamental skill in building agents. A well-crafted prompt transforms a general-purpose LLM into a specialized agent. These patterns cover the core techniques.

System Prompt Design

The system prompt defines your agent's identity, capabilities, and constraints. It is the single most important piece of configuration.

Anatomy of a Good System Prompt

1. Role definition: Who the agent is and what it does
2. Constraints: What the agent should NOT do
3. Output format: How responses should be structured
4. Context: Domain-specific knowledge the agent needs
5. Examples: Reference outputs the agent should emulate

Key Principles

• Be specific, not vague: "You are a customer support agent for Acme Corp that handles billing inquiries" beats "You are a helpful assistant"
• Set boundaries: Explicitly state what the agent should refuse or redirect
• Include domain knowledge: Add facts, rules, and conventions the LLM wouldn't know
• Test iteratively: Small prompt changes can have large behavioral effects

Example: Before vs. After

# Vague (bad)
You are a helpful assistant that answers questions.

# Specific (good)
You are a billing support agent for Acme Corp. You help customers
with invoice questions, payment issues, and subscription changes.

Rules:
- Never share internal pricing formulas
- For refund requests over $500, escalate to a human manager
- Always confirm the customer's account email before making changes
- Use a friendly but professional tone

When you don't know the answer, say "Let me connect you with a
specialist" rather than guessing.

Structured Output

Instead of parsing free-form text, use schema-based structured output for reliable, predictable agent responses.

Why Structured Output Matters

• Reliable parsing: JSON/object responses can be consumed by code
• Type safety: Schema validation catches malformed responses
• Consistency: Same structure every time, no format drift
• Composability: Output of one step feeds cleanly into the next

Implementation Pattern

Define a schema (Zod, JSON Schema, etc.) and pass it to your LLM call:

const schema = z.object({
  sentiment: z.enum(["positive", "negative", "neutral"]),
  confidence: z.number().min(0).max(1),
  summary: z.string(),
  actionItems: z.array(z.string()),
});

const result = await generateText({
  model,
  prompt: userInput,
  output: Output.object({ schema }),
});

Best Practices

• Start with simple schemas and add complexity as needed
• Use enums for classification tasks (more reliable than open-ended strings)
• Include descriptions in your schema fields to guide the model
• Validate output and retry on schema violations

Few-Shot and Many-Shot Prompting

Few-Shot (2-5 examples)

Provide a small number of input/output pairs to demonstrate the pattern:

Given a customer message, classify the intent.

Example 1:
Input: "I can't log in to my account"
Output: { "intent": "account_access", "urgency": "high" }

Example 2:
Input: "What are your business hours?"
Output: { "intent": "general_inquiry", "urgency": "low" }

Now classify:
Input: "{user_message}"

Many-Shot (10-100+ examples)

When you have more data, more examples improve accuracy. Works especially well for:

• Classification with many categories
• Edge cases that need explicit coverage
• Domain-specific patterns

Guidelines

• Choose diverse examples covering different categories and edge cases
• Order matters: put the most representative examples first
• Quality over quantity: wrong examples teach wrong patterns
• Match the format: examples should mirror the exact output format you want

Agent UX Patterns

Confirmations

Before taking high-stakes actions, agents should confirm with the user:

Agent: "I'm about to send a refund of $350 to [email protected].
        Should I proceed? (yes/no)"

Transparency

Show users what the agent is doing:

• Display which tools are being called
• Show intermediate reasoning steps
• Stream responses token-by-token rather than waiting for completion

Guardrails in Prompts

Add explicit behavioral rules:

## Safety Rules
- Never execute database DELETE operations without explicit user confirmation
- If asked to do something outside your capabilities, say so clearly
- When uncertain, ask a clarifying question instead of guessing

Streaming for Responsiveness

Users should see progress, not a blank screen:

• Stream LLM output as tokens arrive
• Show workflow step updates ("Searching... Analyzing... Writing...")
• Use escape hatches -- push partial results if a function is slow

Decision Framework

Situation	Technique
Agent needs a clear identity and constraints	System prompt design
Output must be consumed by code	Structured output with schema
Model struggles with a specific task format	Few-shot examples
Many categories or domain-specific patterns	Many-shot examples
High-stakes actions	Confirmation prompts
Long-running tasks	Streaming + progress updates

Gotchas

• Small prompt changes can have outsized behavioral effects. Test after every change.
• Don't over-constrain the prompt. Too many rules can confuse the model.
• Structured output with enums is more reliable than asking for classifications in prose.
• Few-shot examples with wrong answers teach wrong patterns -- verify your examples.
• Streaming is critical for UX. A 10-second wait feels broken; streaming the same content feels fast.
• Put the most important instructions at the beginning and end of the system prompt (primacy/recency effects).

For detailed examples, see references/prompting-examples.md.