strands.experimental.steering.handlers.llm.mappers

LLM steering prompt mappers for generating evaluation prompts.

_STEERING_PROMPT_TEMPLATE = '# Steering Evaluation\n\n## Overview\n\nYou are a STEERING AGENT that evaluates a {action_type} that ANOTHER AGENT is attempting to make.\nYour job is to provide contextual guidance to help the other agent navigate workflows effectively.\nYou act as a safety net that can intervene when patterns in the context data suggest the agent\nshould try a different approach or get human input.\n\n**YOUR ROLE:**\n- Analyze context data for concerning patterns (repeated failures, inappropriate timing, etc.)\n- Provide just-in-time guidance when the agent is going down an ineffective path\n- Allow normal operations to proceed when context shows no issues\n\n**CRITICAL CONSTRAINTS:**\n- Base decisions ONLY on the context data provided below\n- Do NOT use external knowledge about domains, URLs, or tool purposes\n- Do NOT make assumptions about what tools "should" or "shouldn\'t" do\n- Focus ONLY on patterns in the context data\n\n## Context\n\n{context_str}\n\n### Understanding Ledger Tool States\n\nIf the context includes a ledger with tool_calls, the "status" field indicates:\n\n- **"pending"**: The tool is CURRENTLY being evaluated by you (the steering agent).\nThis is NOT a duplicate call - it\'s the tool you\'re deciding whether to approve.\nThe tool has NOT started executing yet.\n- **"success"**: The tool completed successfully in a previous turn\n- **"error"**: The tool failed or was cancelled in a previous turn\n\n**IMPORTANT**: When you see a tool with status="pending" that matches the tool you\'re evaluating,\nthat IS the current tool being evaluated.\nIt is NOT already executing or a duplicate.\n\n## Event to Evaluate\n\n{event_description}\n\n## Steps\n\n### 1. Analyze the {action_type_title}\n\nReview ONLY the context data above. Look for patterns in the data that indicate:\n\n- Previous failures or successes with this tool\n- Frequency of attempts\n- Any relevant tracking information\n\n**Constraints:**\n- You MUST base analysis ONLY on the provided context data\n- You MUST NOT use external knowledge about tool purposes or domains\n- You SHOULD identify patterns in the context data\n- You MAY reference relevant context data to inform your decision\n\n### 2. Make Steering Decision\n\n**Constraints:**\n- You MUST respond with exactly one of: "proceed", "guide", or "interrupt"\n- You MUST base the decision ONLY on context data patterns\n- Your reason will be shown to the AGENT as guidance\n\n**Decision Options:**\n- "proceed" if context data shows no concerning patterns\n- "guide" if context data shows patterns requiring intervention\n- "interrupt" if context data shows patterns requiring human input\n' module-attribute

DefaultPromptMapper

Bases: LLMPromptMapper

Default prompt mapper for steering evaluation.

Source code in strands/experimental/steering/handlers/llm/mappers.py

class DefaultPromptMapper(LLMPromptMapper):
    """Default prompt mapper for steering evaluation."""

    def create_steering_prompt(
        self, steering_context: SteeringContext, tool_use: ToolUse | None = None, **kwargs: Any
    ) -> str:
        """Create default steering prompt using Agent SOP structure.

        Uses Agent SOP format for structured, constraint-based prompts.
        See: https://github.com/strands-agents/agent-sop
        """
        context_str = (
            json.dumps(steering_context.data.get(), indent=2) if steering_context.data.get() else "No context available"
        )

        if tool_use:
            event_description = (
                f"Tool: {tool_use['name']}\nArguments: {json.dumps(tool_use.get('input', {}), indent=2)}"
            )
            action_type = "tool call"
        else:
            event_description = "General evaluation"
            action_type = "action"

        return _STEERING_PROMPT_TEMPLATE.format(
            action_type=action_type,
            action_type_title=action_type.title(),
            context_str=context_str,
            event_description=event_description,
        )

create_steering_prompt(steering_context, tool_use=None, **kwargs)

Create default steering prompt using Agent SOP structure.

Uses Agent SOP format for structured, constraint-based prompts. See: https://github.com/strands-agents/agent-sop

Source code in strands/experimental/steering/handlers/llm/mappers.py

def create_steering_prompt(
    self, steering_context: SteeringContext, tool_use: ToolUse | None = None, **kwargs: Any
) -> str:
    """Create default steering prompt using Agent SOP structure.

    Uses Agent SOP format for structured, constraint-based prompts.
    See: https://github.com/strands-agents/agent-sop
    """
    context_str = (
        json.dumps(steering_context.data.get(), indent=2) if steering_context.data.get() else "No context available"
    )

    if tool_use:
        event_description = (
            f"Tool: {tool_use['name']}\nArguments: {json.dumps(tool_use.get('input', {}), indent=2)}"
        )
        action_type = "tool call"
    else:
        event_description = "General evaluation"
        action_type = "action"

    return _STEERING_PROMPT_TEMPLATE.format(
        action_type=action_type,
        action_type_title=action_type.title(),
        context_str=context_str,
        event_description=event_description,
    )

LLMPromptMapper

Bases: Protocol

Protocol for mapping context and events to LLM evaluation prompts.

Source code in strands/experimental/steering/handlers/llm/mappers.py

class LLMPromptMapper(Protocol):
    """Protocol for mapping context and events to LLM evaluation prompts."""

    def create_steering_prompt(
        self, steering_context: SteeringContext, tool_use: ToolUse | None = None, **kwargs: Any
    ) -> str:
        """Create steering prompt for LLM evaluation.

        Args:
            steering_context: Steering context with populated data
            tool_use: Tool use object for tool call events (None for other events)
            **kwargs: Additional event data for other steering events

        Returns:
            Formatted prompt string for LLM evaluation
        """
        ...

create_steering_prompt(steering_context, tool_use=None, **kwargs)

Create steering prompt for LLM evaluation.

Parameters:

Name	Type	Description	Default
steering_context	SteeringContext	Steering context with populated data	required
tool_use	ToolUse | None	Tool use object for tool call events (None for other events)	None
**kwargs	Any	Additional event data for other steering events	{}

Returns:

Type	Description
str	Formatted prompt string for LLM evaluation

Source code in strands/experimental/steering/handlers/llm/mappers.py

def create_steering_prompt(
    self, steering_context: SteeringContext, tool_use: ToolUse | None = None, **kwargs: Any
) -> str:
    """Create steering prompt for LLM evaluation.

    Args:
        steering_context: Steering context with populated data
        tool_use: Tool use object for tool call events (None for other events)
        **kwargs: Additional event data for other steering events

    Returns:
        Formatted prompt string for LLM evaluation
    """
    ...

SteeringContext dataclass

Container for steering context data.

Source code in strands/experimental/steering/core/context.py

@dataclass
class SteeringContext:
    """Container for steering context data."""

    """Container for steering context data.

    This class should not be instantiated directly - it is intended for internal use only.
    """

    data: JSONSerializableDict = field(default_factory=JSONSerializableDict)

ToolUse

Bases: TypedDict

A request from the model to use a specific tool with the provided input.

Attributes:

Name	Type	Description
input	Any	The input parameters for the tool. Can be any JSON-serializable type.
name	str	The name of the tool to invoke.
toolUseId	str	A unique identifier for this specific tool use request.
reasoningSignature	NotRequired[str]	Token that ties the model's reasoning to this tool call.

Source code in strands/types/tools.py

class ToolUse(TypedDict):
    """A request from the model to use a specific tool with the provided input.

    Attributes:
        input: The input parameters for the tool.
            Can be any JSON-serializable type.
        name: The name of the tool to invoke.
        toolUseId: A unique identifier for this specific tool use request.
        reasoningSignature: Token that ties the model's reasoning to this tool call.
    """

    input: Any
    name: str
    toolUseId: str
    reasoningSignature: NotRequired[str]