strands-agents/agent-sop: SOPs as Markdown Prompts for Strands Agents

The problem Agent SOPs address is prompt drift across multi-step agent work

Ask an agent to implement a feature and the result depends heavily on how you phrase the request that day. Agent SOPs try to remove that variance by writing the procedure down once as a markdown document with named parameters and explicit constraints, then reusing that document as the agent's system prompt. The README describes them as "markdown-based instruction sets that guide AI agents through sophisticated workflows using natural language, parameterized inputs, and constraint-based execution." The intended audience is teams already building on Strands Agents who repeat the same class of task (codebase analysis, task breakdown, TDD implementation, evaluation) and want the steps to be the same each time. It is not a general-purpose agent framework. It is a prompt library plus a small distribution layer.

The mechanism is a markdown file with RFC 2119 constraints, not an execution engine

Each SOP is a single .sop.md file. The README shows the shape of one, an SOP named Code Assist, with an Overview section, a Parameters section, and numbered Steps. Parameters carry a name, a required or optional marker, and sometimes a default, for example task_description as required and mode as optional with a default of "interactive" or "fsc" (Full Self-Coding). Steps carry Constraints written in RFC 2119 language: "You MUST validate and create the documentation directory structure", "You MUST discover existing instruction files using find commands", "You MUST NOT proceed if directory creation fails". That vocabulary is the whole control surface. There is no state machine, no step runner, no checkpoint store. The agent reads the constraints and is expected to honour them, so compliance depends on the model's instruction-following rather than on code that blocks a transition. The repository ships five SOPs: codebase-summary for codebase analysis and documentation generation, pdd for prompt-driven development, code-task-generator for breaking requirements into tasks, code-assist for TDD implementation, and eval for evaluation planning, test data generation, execution and result analysis against the Strands Evals SDK.

The .agents/ directory encodes a commit policy, which is the most opinionated part of the project

The PDD family (codebase-summary, pdd, code-task-generator, code-assist) writes artifacts into .agents/ with a fixed layout. summary/ holds codebase-summary output and the README says to always commit it. planning/{project_name}/ holds pdd output with rough-idea.md, idea-honing.md, and research/, design/ and implementation/ subdirectories, described as often worth committing. tasks/{project_name}/step01/task-*.code-task.md holds code-task-generator output, optionally committed or tracked in an issue tracker instead. scratchpad/{project_name}/{task_name}/ holds code-assist working files and the README says to add it to .gitignore. Auto-generated project names get a YYYY-MM-DD prefix so they sort chronologically. That split is a real design decision rather than a directory convention: it separates durable design rationale from transient implementation notes, and it lets you point an AI tool's context at only the durable part. The README gives the Kiro CLI example of pinning planning docs with /context add .agents/planning/{project_name}/**/*.md.

Installing and wiring an SOP into a Strands agent

The package is strands-agents-sops on PyPI. The README gives two install paths: brew install strands-agents-sops, or pip install strands-agents-sops. To use it with a Strands agent you also install the SDK and tools, shown as pip install strands-agents strands-agents-tools. The usage example imports the SOP as a Python module and passes it as the system prompt:

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])

So code_assist is imported directly from the package, which means the SOP text ships as an importable string. The README also states there is an MCP server that exposes SOPs as prompts for on-demand discovery, launched with strands-agents-sops mcp, and that some clients start that command themselves from their MCP configuration. The Kiro CLI example adds strands-agents-sops mcp to ~/.kiro/settings/mcp.json. The README's MCP section is cut off mid-command in the material available here, so treat the exact invocation as something to confirm against the published documentation rather than something I can quote in full.

Where this breaks down: constraints are advisory and the SOPs are not equally mature

The MUST and MUST NOT wording looks like enforcement but is not. If a model skips the directory validation step in Code Assist, nothing in this repository stops it; the failure surfaces later as a missing path or an overwritten file. For long workflows with many steps, that is exactly the class of error a workflow engine exists to prevent, and Agent SOPs do not attempt it. The second limitation is coverage. The five SOPs cluster tightly around software development and evaluation. There is no SOP for data pipelines, incident response, or anything outside a code repository, and the README does not describe a schema or validation tool for authoring your own, so a custom SOP is a markdown file you write and hope the model follows. Third, the directory layout is hardcoded into the SOP text rather than configurable through a documented key, so if .agents/ collides with an existing convention in your repo you are editing the SOP itself. Finally, the eval SOP depends on the separate Strands Evals SDK, which is a second project to track.

Compared with LangGraph, the difference is who holds the control flow

LangGraph is the obvious contrast for anyone evaluating this. In LangGraph you build a graph in Python: nodes are functions, edges are explicit transitions, and the runtime decides what executes next. State is passed between nodes by the framework, and a conditional edge is code. Agent SOPs put the same decisions in prose and let the model choose the path, which is why an SOP can be handed to a different AI system without a rewrite, as the README claims, and why it cannot guarantee that step 3 runs before step 4. The trade is expressiveness against determinism. If your procedure has branches that must not be skipped, a graph is the right shape. If your procedure is a sequence of judgement calls where you want consistency in approach rather than a hard guarantee, an SOP is cheaper to write and easier to share with people who do not read Python. The two are not mutually exclusive: you could call an SOP from inside a graph node.

Maintenance cost and licence

The repository is active, with v1.1.3 released on 2026-08-07, following v1.1.2 in April 2026 and v1.1.1 in March 2026. That cadence suggests the SOP texts are still being revised, which matters because an SOP is a prompt: when the underlying model changes, wording that worked can start failing, and the fix is an edit to a .sop.md file rather than a dependency bump. Budget for re-reading an SOP after a model upgrade. The licence is Apache-2.0, which permits commercial use and modification and includes a patent grant; if you fork the SOPs and redistribute them, the usual Apache obligations around notices and attribution apply. That is a description of the licence, not legal advice.

Editorial conclusion

Adopt Agent SOPs if you already run Strands Agents and want your multi-step procedures written down in a format both humans and models can read, especially the PDD family that writes into .agents/. Do not adopt it if you need a deterministic workflow engine, a scheduler, or retries: this repository distributes prompts, and the model still decides what happens at each step. Before committing, read agent-sops/code-assist.sop.md end to end and confirm the MUST and MUST NOT constraints are ones you can actually enforce, then check the .agents/scratchpad/ path against your .gitignore.

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. strands-agents/agent-sop on GitHub