feat(steering): move steering from experimental to production (#1853)

Author: dbschmigelski

AGENTS.md

@@ -130,15 +130,18 @@ strands-agents/
 │   ├── plugins/                          # Plugin system
 │   │   ├── plugin.py                     # Plugin base class
 │   │   ├── decorator.py                  # @hook decorator
-│   │   ├── registry.py                   # PluginRegistry for tracking plugins
-│   │   └── skills/                       # Agent Skills integration
-│   │       ├── __init__.py               # Skills package exports
-│   │       ├── skill.py                  # Skill dataclass
-│   │       └── agent_skills.py            # AgentSkills plugin implementation
+│   │   └── registry.py                   # PluginRegistry for tracking plugins
 │   │
 │   ├── handlers/                         # Event handlers
 │   │   └── callback_handler.py           # Callback handling
 │   │
+│   ├── vended_plugins/                   # Production plugin implementations
+│   │   ├── steering/                     # Agent steering system
+│   │   │   ├── context_providers/        # Context data providers (e.g., ledger)
+│   │   │   ├── core/                     # Base classes, actions, context
+│   │   │   └── handlers/                 # Handler implementations (e.g., LLM)
+│   │   └── skills/                       # AgentSkills.io integration (Skill, AgentSkills)
+│   │
 │   ├── experimental/                     # Experimental features (API may change)
 │   │   ├── agent_config.py               # Experimental agent config
 │   │   ├── bidi/                         # Bidirectional streaming
@@ -151,11 +154,8 @@ strands-agents/
 │   │   ├── hooks/                        # Experimental hooks
 │   │   │   ├── events.py
 │   │   │   └── multiagent/
-│   │   ├── steering/                     # Agent steering
-│   │   │   ├── context_providers/
-│   │   │   ├── core/
-│   │   │   └── handlers/
-│   │   └── tools/                        # Experimental tools (deprecation shims)
+│   │   ├── steering/                     # Deprecated aliases for vended_plugins/steering
+│   │   └── tools/                        # Deprecated aliases for strands.tools
 │   │
 │   ├── __init__.py                       # Public API exports
 │   ├── interrupt.py                      # Interrupt handling

src/strands/__init__.py

@@ -4,9 +4,10 @@
 from .agent.agent import Agent
 from .agent.base import AgentBase
 from .event_loop._retry import ModelRetryStrategy
-from .plugins import AgentSkills, Plugin, Skill
+from .plugins import Plugin
 from .tools.decorator import tool
 from .types.tools import ToolContext
+from .vended_plugins.skills import AgentSkills, Skill
 
 __all__ = [
     "Agent",

src/strands/experimental/steering/__init__.py

@@ -1,36 +1,12 @@
-"""Steering system for Strands agents.
+"""Deprecated: Steering has moved to strands.vended_plugins.steering.
 
-Provides contextual guidance for agents through modular prompting with progressive disclosure.
-Instead of front-loading all instructions, steering handlers provide just-in-time feedback
-based on local context data populated by context callbacks.
-
-Core components:
-
-- SteeringHandler: Base class for guidance logic with local context
-- SteeringContextCallback: Protocol for context update functions
-- SteeringContextProvider: Protocol for multi-event context providers
-- ToolSteeringAction/ModelSteeringAction: Proceed/Guide/Interrupt decisions
-
-Usage:
-    handler = LLMSteeringHandler(system_prompt="...")
-    agent = Agent(tools=[...], plugins=[handler])
+This module provides backwards-compatible aliases that emit deprecation warnings.
 """
 
-# Core primitives
-# Context providers
-from .context_providers.ledger_provider import (
-    LedgerAfterToolCall,
-    LedgerBeforeToolCall,
-    LedgerProvider,
-)
-from .core.action import Guide, Interrupt, ModelSteeringAction, Proceed, ToolSteeringAction
-from .core.context import SteeringContextCallback, SteeringContextProvider
-from .core.handler import SteeringHandler
-
-# Handler implementations
-from .handlers.llm import LLMPromptMapper, LLMSteeringHandler
-
-__all__ = [
+import warnings
+from typing import Any
+
+_DEPRECATED_NAMES = {
     "ToolSteeringAction",
     "ModelSteeringAction",
     "Proceed",
@@ -44,4 +20,20 @@
     "LedgerProvider",
     "LLMSteeringHandler",
     "LLMPromptMapper",
-]
+}
+
+
+def __getattr__(name: str) -> Any:
+    if name in _DEPRECATED_NAMES:
+        from strands.vended_plugins import steering
+
+        warnings.warn(
+            f"{name} has been moved to production. Use {name} from strands.vended_plugins.steering instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return getattr(steering, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__: list[str] = []

src/strands/experimental/steering/context_providers/__init__.py

@@ -1,13 +1,23 @@
-"""Context providers for steering evaluation."""
-
-from .ledger_provider import (
-    LedgerAfterToolCall,
-    LedgerBeforeToolCall,
-    LedgerProvider,
-)
-
-__all__ = [
-    "LedgerAfterToolCall",
-    "LedgerBeforeToolCall",
-    "LedgerProvider",
-]
+"""Deprecated: Use strands.vended_plugins.steering.context_providers instead."""
+
+import warnings
+from typing import Any
+
+_TARGET_MODULE = "strands.vended_plugins.steering.context_providers"
+
+
+def __getattr__(name: str) -> Any:
+    from strands.vended_plugins.steering import context_providers
+
+    obj = getattr(context_providers, name, None)
+    if obj is not None:
+        warnings.warn(
+            f"{name} has been moved to production. Use {name} from {_TARGET_MODULE} instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return obj
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__: list[str] = []

src/strands/experimental/steering/context_providers/ledger_provider.py

@@ -1,91 +1,23 @@
-"""Ledger context provider for comprehensive agent activity tracking.
+"""Deprecated: Use strands.vended_plugins.steering.context_providers.ledger_provider instead."""
 
-Tracks complete agent activity ledger including tool calls, conversation history,
-and timing information. This comprehensive audit trail enables steering handlers
-to make informed guidance decisions based on agent behavior patterns and history.
-
-Data captured:
-
-    - Tool call history with inputs, outputs, timing, success/failure
-    - Conversation messages and agent responses
-    - Session metadata and timing information
-    - Error patterns and recovery attempts
-
-Usage:
-    Use as context provider functions or mix into steering handlers.
-"""
-
-import logging
-from datetime import datetime
+import warnings
 from typing import Any
 
-from ....hooks.events import AfterToolCallEvent, BeforeToolCallEvent
-from ..core.context import SteeringContext, SteeringContextCallback, SteeringContextProvider
-
-logger = logging.getLogger(__name__)
-
-
-class LedgerBeforeToolCall(SteeringContextCallback[BeforeToolCallEvent]):
-    """Context provider for ledger tracking before tool calls."""
-
-    def __init__(self) -> None:
-        """Initialize the ledger provider."""
-        self.session_start = datetime.now().isoformat()
-
-    def __call__(self, event: BeforeToolCallEvent, steering_context: SteeringContext, **kwargs: Any) -> None:
-        """Update ledger before tool call."""
-        ledger = steering_context.data.get("ledger") or {}
-
-        if not ledger:
-            ledger = {
-                "session_start": self.session_start,
-                "tool_calls": [],
-                "conversation_history": [],
-                "session_metadata": {},
-            }
-
-        tool_call_entry = {
-            "timestamp": datetime.now().isoformat(),
-            "tool_use_id": event.tool_use.get("toolUseId"),
-            "tool_name": event.tool_use.get("name"),
-            "tool_args": event.tool_use.get("input", {}),
-            "status": "pending",
-        }
-        ledger["tool_calls"].append(tool_call_entry)
-        steering_context.data.set("ledger", ledger)
-
-
-class LedgerAfterToolCall(SteeringContextCallback[AfterToolCallEvent]):
-    """Context provider for ledger tracking after tool calls."""
-
-    def __call__(self, event: AfterToolCallEvent, steering_context: SteeringContext, **kwargs: Any) -> None:
-        """Update ledger after tool call."""
-        ledger = steering_context.data.get("ledger") or {}
+_TARGET_MODULE = "strands.vended_plugins.steering.context_providers.ledger_provider"
 
-        if ledger.get("tool_calls"):
-            tool_use_id = event.tool_use.get("toolUseId")
 
-            # Search for the matching tool call in the ledger to update it
-            for call in reversed(ledger["tool_calls"]):
-                if call.get("tool_use_id") == tool_use_id and call.get("status") == "pending":
-                    call.update(
-                        {
-                            "completion_timestamp": datetime.now().isoformat(),
-                            "status": event.result["status"],
-                            "result": event.result["content"],
-                            "error": str(event.exception) if event.exception else None,
-                        }
-                    )
-                    steering_context.data.set("ledger", ledger)
-                    break
+def __getattr__(name: str) -> Any:
+    from strands.vended_plugins.steering.context_providers import ledger_provider
 
+    obj = getattr(ledger_provider, name, None)
+    if obj is not None:
+        warnings.warn(
+            f"{name} has been moved to production. Use {name} from {_TARGET_MODULE} instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return obj
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
-class LedgerProvider(SteeringContextProvider):
-    """Combined ledger context provider for both before and after tool calls."""
 
-    def context_providers(self, **kwargs: Any) -> list[SteeringContextCallback]:
-        """Return ledger context providers with shared state."""
-        return [
-            LedgerBeforeToolCall(),
-            LedgerAfterToolCall(),
-        ]
+__all__: list[str] = []

src/strands/experimental/steering/core/__init__.py

@@ -1,6 +1,23 @@
-"""Core steering system interfaces and base classes."""
+"""Deprecated: Use strands.vended_plugins.steering.core instead."""
 
-from .action import Guide, Interrupt, ModelSteeringAction, Proceed, ToolSteeringAction
-from .handler import SteeringHandler
+import warnings
+from typing import Any
 
-__all__ = ["ToolSteeringAction", "ModelSteeringAction", "Proceed", "Guide", "Interrupt", "SteeringHandler"]
+_TARGET_MODULE = "strands.vended_plugins.steering.core"
+
+
+def __getattr__(name: str) -> Any:
+    from strands.vended_plugins.steering import core
+
+    obj = getattr(core, name, None)
+    if obj is not None:
+        warnings.warn(
+            f"{name} has been moved to production. Use {name} from {_TARGET_MODULE} instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return obj
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__: list[str] = []

src/strands/experimental/steering/core/action.py

@@ -1,76 +1,23 @@
-"""SteeringAction types for steering evaluation results.
+"""Deprecated: Use strands.vended_plugins.steering.core.action instead."""
 
-Defines structured outcomes from steering handlers that determine how agent actions
-should be handled. SteeringActions enable modular prompting by providing just-in-time
-feedback rather than front-loading all instructions in monolithic prompts.
+import warnings
+from typing import Any
 
-Flow:
-    SteeringHandler.steer_*() → SteeringAction → Event handling
-                    ↓                     ↓              ↓
-              Evaluate context      Action type    Execution modified
+_TARGET_MODULE = "strands.vended_plugins.steering.core.action"
 
-SteeringAction types:
-    Proceed: Allow execution to continue without intervention
-    Guide: Provide contextual guidance to redirect the agent
-    Interrupt: Pause execution for human input
 
-Extensibility:
-    New action types can be added to the union. Always handle the default
-    case in pattern matching to maintain backward compatibility.
-"""
+def __getattr__(name: str) -> Any:
+    from strands.vended_plugins.steering.core import action
 
-from typing import Annotated, Literal
+    obj = getattr(action, name, None)
+    if obj is not None:
+        warnings.warn(
+            f"{name} has been moved to production. Use {name} from {_TARGET_MODULE} instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return obj
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
-from pydantic import BaseModel, Field
 
-
-class Proceed(BaseModel):
-    """Allow execution to continue without intervention.
-
-    The action proceeds as planned. The reason provides context
-    for logging and debugging purposes.
-    """
-
-    type: Literal["proceed"] = "proceed"
-    reason: str
-
-
-class Guide(BaseModel):
-    """Provide contextual guidance to redirect the agent.
-
-    The agent receives the reason as contextual feedback to help guide
-    its behavior. The specific handling depends on the steering context
-    (e.g., tool call vs. model response).
-    """
-
-    type: Literal["guide"] = "guide"
-    reason: str
-
-
-class Interrupt(BaseModel):
-    """Pause execution for human input via interrupt system.
-
-    Execution is paused and human input is requested through Strands'
-    interrupt system. The human can approve or deny the operation, and their
-    decision determines whether execution continues or is cancelled.
-    """
-
-    type: Literal["interrupt"] = "interrupt"
-    reason: str
-
-
-# Context-specific steering action types
-ToolSteeringAction = Annotated[Proceed | Guide | Interrupt, Field(discriminator="type")]
-"""Steering actions valid for tool steering (steer_before_tool).
-
-- Proceed: Allow tool execution to continue
-- Guide: Cancel tool and provide feedback for alternative approaches
-- Interrupt: Pause for human input before tool execution
-"""
-
-ModelSteeringAction = Annotated[Proceed | Guide, Field(discriminator="type")]
-"""Steering actions valid for model steering (steer_after_model).
-
-- Proceed: Accept model response without modification
-- Guide: Discard model response and retry with guidance
-"""
+__all__: list[str] = []