Agent SOPs

[zastrowm]

Overview

The docs page needs to refactor its guidance for prompting agents. The current guidance is quite general, so I want to include specific instructions about prompting using Agent SOPs: https://github.com/strands-agents/agent-sop/blob/main/README.md

Here is a related blog post: https://aws.amazon.com/blogs/opensource/introducing-strands-agent-sops-natural-language-workflows-for-ai-agents/

---

Implementation Requirements

Based on clarification discussion:

Documentation Structure

Create a new "Guides" section in the documentation navigation containing an "Effective Prompting" page that covers:

1. General prompting paradigms and best practices
2. Agent SOPs as one of the key prompting paradigms
3. Update the existing prompts.md page to reference the new guide

Technical Approach

Files to Create

• docs/user-guide/guides/effective-prompting.md - New comprehensive prompting guide

Files to Modify

• mkdocs.yml - Add new "Guides" section to navigation
• docs/user-guide/concepts/agents/prompts.md - Add reference/link to the new Effective Prompting guide

Content Requirements for Effective Prompting Guide

1. Prompting Paradigms Overview

• Cover different approaches to prompting agents
• Explain when to use different techniques

2. Agent SOPs Section

Include the following for Agent SOPs:

• What are Agent SOPs: Brief explanation of markdown-based natural language workflows with RFC 2119 constraints (MUST, SHOULD, MAY), parameterized inputs, and progress tracking

• Using Agent SOPs with Strands: Show how to use SOPs as the system_prompt parameter:

  from strands import Agent
  from strands_tools import editor, shell
  from strands_agents_sops import code_assist
  
  agent = Agent(
    system_prompt=code_assist,
    tools=[editor, shell]
  )

• Example: codebase_summary SOP: Highlight the codebase_summary SOP as a practical example use case

• Custom SOP Authoring: Include guidance on creating custom SOPs (reference the SOP format and RFC 2119 constraints)

• Package Reference: Link to strands-agents-sops PyPI package and agent-sop repository for detailed documentation on available SOPs

Code Examples

• Use Python examples with the {{ ts_not_supported() }} macro for TypeScript tabs (since strands-agents-sops is Python-only)

Navigation Structure (mkdocs.yml)

Add a new "Guides" section, suggested placement after "Concepts":

- Guides:
  - Effective Prompting: user-guide/guides/effective-prompting.md

---

Acceptance Criteria

• New "Guides" section appears in documentation navigation
• "Effective Prompting" page created with prompting paradigms overview
• Agent SOPs documented with Strands integration example
• codebase_summary SOP highlighted as example use case
• Custom SOP authoring guidance included
• Links to strands-agents-sops package and repo
• Existing prompts.md updated to reference new guide
• TypeScript tabs show {{ ts_not_supported() }} message
• Documentation builds successfully with mkdocs build
• Local preview works with mkdocs serve

---

Resources

• Agent SOP Repository
• Agent SOP Blog Post
• strands-agents-sops on PyPI

[Unshure]

/strands

[github-actions]

📋 Repository Analysis & Clarifying Questions

Repository Analysis

I've analyzed the repository structure and the provided links to understand the implementation requirements:

Current State

• Existing prompts documentation:
  • docs/user-guide/concepts/agents/prompts.md - Basic system prompts and user messages
  • docs/user-guide/safety-security/prompt-engineering.md - Security-focused prompt engineering
• Navigation: Prompts page is under User Guide > Concepts > Agents
• Technology: MkDocs with Python/TypeScript tabbed code examples

Agent SOP Overview (from provided links)

Agent SOPs are markdown-based natural language workflows that:

• Use RFC 2119 constraints (MUST, SHOULD, MAY)
• Accept parameterized inputs
• Support progress tracking and resumability
• Can be used as Strands Agent system prompts, MCP prompts, Claude Skills, Cursor commands

---

Clarifying Questions

Documentation Structure

1. Location: Should the Agent SOPs documentation be:

   • (A) A new standalone page (e.g., docs/user-guide/concepts/agents/agent-sops.md)?
   • (B) An expansion of the existing prompts.md page?
   • (C) A new top-level section in the navigation?

2. Depth of Content: How much detail should be included versus linking to the agent-sop repository?

   • (A) Comprehensive guide duplicating key information from the repo README
   • (B) Overview with examples, linking out for advanced topics (authoring, SOP chaining, etc.)
   • (C) Brief introduction with quick start, primarily linking to external resources

Scope

3. Integration Coverage: Which integrations should be documented?

   • (A) Strands Agents only (using SOPs as system_prompt)
   • (B) Strands + MCP Server (both primary Strands use cases)
   • (C) All integrations (Strands, MCP, Claude Skills, Cursor commands)

4. Available SOPs: Should the documentation:

   • List and briefly describe all available SOPs (codebase-summary, pdd, code-task-generator, code-assist, eval)?
   • Or simply reference the package and link to the repo for details?

Technical Details

5. TypeScript Examples: The strands-agents-sops package is Python-only. Should the documentation:

   • (A) Include Python examples only with a note about TypeScript availability
   • (B) Show Python examples with a {{ ts_not_supported() }} macro for TypeScript tabs

6. Custom SOP Authoring: Should we include guidance on creating custom SOPs, or defer to the agent-sop repo documentation?

Additional Considerations

7. Is there any specific example use case or SOP you'd like highlighted in the documentation?

8. Should this documentation include the blog post content about Amazon's internal adoption story, or focus purely on technical usage?

[Unshure]

/strands

1. Can you add a new category called "Guides", and add a page called "Effective Prompting"? You can update the existing Prompts page to point to it.
2. This page should cover prompting in general, and talk about a few different paradigms when prompting. One of them can be Agent SOPs
3. Strands Agents only
4. reference the package and link ot the repo
5. B
6. Yes
7. codebase_summary
8. technical usage

[Unshure]

/strands can you help me decide what content should be included on the new page?

[github-actions]

📝 Proposed Content Structure for "Effective Prompting" Guide

Based on my research of prompting paradigms and the existing Strands documentation, here's a proposed content structure for your review:

---

Proposed Page Structure: Effective Prompting

1. Introduction

Brief overview explaining:

• The importance of effective prompting for AI agents
• How this guide complements the existing Prompts page (mechanics) and Prompt Engineering page (security)
• Overview of the prompting paradigms covered

---

2. Prompting Paradigms

2.1 Simple Role-Based Prompting

When to use: Quick prototypes, simple agents, single-purpose tasks

agent = Agent(
    system_prompt="You are a helpful customer support agent for an e-commerce company."
)

• Pros: Easy to write, quick iteration
• Cons: Less predictable for complex tasks

---

2.2 Structured Prompting

When to use: Tasks requiring specific output formats, multi-step processes

agent = Agent(
    system_prompt="""You are a code reviewer. For each code snippet:

## Analysis Steps
1. Identify potential bugs
2. Check for security vulnerabilities  
3. Suggest improvements

## Output Format
- **Issues Found**: List each issue
- **Severity**: Critical/Medium/Low
- **Recommendation**: How to fix"""
)

• Pros: Consistent output structure, easier to parse
• Cons: More upfront effort to design

---

2.3 Few-Shot Prompting

When to use: When you need the agent to follow a specific pattern, classification tasks

agent = Agent(
    system_prompt="""Classify customer feedback as positive, negative, or neutral.

Example 1:
Input: "Great product, fast shipping!"
Output: positive

Example 2:
Input: "The item arrived broken."
Output: negative

Example 3:
Input: "It works as expected."
Output: neutral"""
)

• Pros: Teaches by example, reduces ambiguity
• Cons: Uses more tokens, examples must be representative

---

2.4 Chain-of-Thought Prompting

When to use: Complex reasoning, multi-step problem solving, math/logic tasks

agent = Agent(
    system_prompt="""You are an analytical assistant. When solving problems:

1. First, identify what information is given
2. Then, determine what needs to be found
3. Break down the problem into smaller steps
4. Work through each step, showing your reasoning
5. Verify your answer makes sense
6. Provide the final answer"""
)

• Pros: Better accuracy on complex tasks, transparent reasoning
• Cons: More verbose responses, slower

---

2.5 Agent SOPs (Standard Operating Procedures)

When to use: Complex multi-step workflows, consistent repeatable behavior, team collaboration

Agent SOPs are markdown-based natural language workflows that provide structured guidance using RFC 2119 keywords (MUST, SHOULD, MAY) for precise control over agent behavior.

from strands import Agent
from strands_tools import editor, shell
from strands_agents_sops import codebase_summary

agent = Agent(
    system_prompt=codebase_summary,
    tools=[editor, shell]
)

agent("Analyze this codebase and generate documentation")

Key Features:

• Parameterized inputs for flexibility
• Constraint-based execution (MUST/SHOULD/MAY)
• Progress tracking and resumability
• Reusable across projects and teams

Available SOPs: The strands-agents-sops package includes pre-built SOPs for common development workflows.

Creating Custom SOPs: [Brief guidance on authoring + link to repo]

→ Full documentation: Agent SOP Repository

• Pros: Highly consistent, shareable, supports complex workflows
• Cons: More setup required, primarily for sophisticated use cases

---

3. Choosing the Right Paradigm

Paradigm	Best For	Complexity	Consistency
Simple Role-Based	Quick prototypes, simple tasks	Low	Variable
Structured	Formatted outputs, parsing	Medium	High
Few-Shot	Pattern matching, classification	Medium	High
Chain-of-Thought	Complex reasoning, math	Medium	Medium
Agent SOPs	Multi-step workflows, team use	High	Very High

---

4. Combining Paradigms

Brief section on how paradigms can be combined (e.g., Agent SOPs often incorporate structured prompting and chain-of-thought internally)

---

5. Further Resources

• Link to Safety & Security - Prompt Engineering
• Link to Agent SOP Repository
• External resources (Anthropic, OpenAI, etc.)

---

Questions for You

1. Paradigm selection: Are there any paradigms you'd like to add or remove from this list?

2. Depth per paradigm: Should all paradigms get equal coverage, or should Agent SOPs get more detailed treatment?

3. Practical examples: Would you like domain-specific examples (e.g., customer support agent, code assistant, data analyst)?

4. Comparison table: Is the "Choosing the Right Paradigm" comparison table helpful, or too prescriptive?

5. Custom SOP authoring: How much detail on creating custom SOPs? Options:

   • (A) Just mention it's possible + link to repo
   • (B) Include the basic SOP structure/template
   • (C) Full walkthrough with example custom SOP