feat(steering): add experimental steering for modular prompting

[dbschmigelski]

Description

This PR introduces Strands Steering, an experimental feature that solves the prompt bloat problem in complex multi-step agent tasks through modular prompting with progressive disclosure.

Traditional agent prompting requires front-loading all instructions into monolithic prompts. For complex workflows with 30+ steps, this leads to prompt bloat where agents ignore instructions, hallucinated behaviors, failed adherence to intended procedures.

Existing solutions like workflow frameworks improve predictability but sacrifice the adaptive reasoning that makes AI valuable.

Solution

Steering provides context-aware guidance that appears when relevant, rather than upfront. Key components:

SteeringHandler Base Class: Abstract base for implementing custom steering logic with steer() method that returns SteeringActions

LLMSteeringHandler: Concrete implementation using natural language guidance via system prompts

Context Provider Architecture:

• SteeringContextCallback protocol for event-specific context updates
• SteeringContextProvider protocol for multi-event context management
• Built-in LedgerProvider tracks comprehensive tool call history and timing

SteeringActions: Proceed, Guide (cancel + feedback), or Interrupt (human input)

Decision

We are leveraging Hooks as the extension mechanism for this feature. This architectural choice allows Steering to integrate seamlessly with the existing agent lifecycle by intercepting tool calls through the BeforeToolCallEvent, enabling context-aware guidance without modifying core agent behavior.

We focus on tool calls because they represent the only decision points where we can intervene and continue the agent loop - the agent loop is tool-focused, and when the LLM returns anything other than a tool call request, it becomes terminal.

Usage

from strands.experimental.steering import LLMSteeringHandler

handler = LLMSteeringHandler(
    system_prompt="Ensure emails maintain cheerful tone..."
)

agent = Agent(tools=[send_email], hooks=[handler])

Documentation PR

TODO

Type of Change

New feature

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[codecov]

Codecov Report

❌ Patch coverage is 96.74419% with 7 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/strands/experimental/steering/core/context.py	86.95%	1 Missing and 2 partials ⚠️
src/strands/experimental/steering/core/handler.py	93.61%	3 Missing ⚠️
src/strands/types/_events.py	75.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!