---
title: Steering
description: "LLM-based contextual guidance for agents using the interventions framework — just-in-time feedback instead of front-loaded prompts."
tags: [hooks, event-loop, tool-execution]
---

Steering provides modular prompting for complex agent tasks through context-aware guidance that appears when relevant, rather than front-loading all instructions in monolithic prompts. Steering handlers observe agent activity and intervene at key moments — before a tool call or after a model response — with targeted feedback. They are built on the [interventions](./index.mdx) framework and use the same typed action model.

:::note[Python SDK]
In Python, steering handlers use the [plugins](../../plugins/steering/) interface rather than interventions. See [Steering (Plugins)](../../plugins/steering/) for the Python API reference including `LLMSteeringHandler` and context providers.
:::

## What Is Steering?

Building agents for complex multi-step tasks runs into a prompting wall. Traditional approaches require front-loading all instructions, business rules, and operational guidance into a single prompt. For tasks with 30+ steps, monolithic prompts become unwieldy: agents ignore instructions, hallucinate behaviors, or fail to follow critical procedures.

A common workaround is decomposing the agent into a graph with predefined nodes and edges that control execution flow. While this improves predictability and reduces prompt complexity, it limits the adaptive reasoning that makes agents valuable in the first place, and it is costly to maintain as requirements change.

Steering takes a different approach: **modular prompting**. Instead of front-loading all instructions, you define context-aware steering handlers that provide feedback at the right moment. Each handler defines the business rules to enforce and the lifecycle hooks where agent behavior should be validated, like before a tool call or before returning output to the user.

## Comparison with Other Approaches

### Steering vs. Workflow Frameworks

Workflow frameworks force you to specify discrete steps and control flow logic upfront, making agents brittle and requiring extensive developer time to define complex decision trees. When business requirements change, you rebuild the workflow logic. Steering uses modular prompting where you define contextual guidance that appears when relevant rather than prescribing exact execution paths. This maintains the adaptive reasoning that makes agents valuable while enabling reliable execution of complex procedures.

### Steering vs. Traditional Prompting

Traditional prompting requires front-loading all instructions into a single prompt. For complex tasks with 30+ steps, this leads to prompt bloat where agents ignore instructions, hallucinate behaviors, or fail to follow critical procedures. Steering provides context-aware reminders that appear at the right moment, like post-it notes that guide agents when they need specific information. This keeps context windows lean while maintaining agent effectiveness on complex tasks.

## Context Population

To give the handler something to reason about, attach a provider that observes agent activity and records it as steering context.

```mermaid
flowchart LR
    A[Hook Events] --> B[Context Providers]
    B --> C[Update Steering Context]
    C --> D[Handler Access]
```

**Context Providers** observe agent activity and contribute structured data into the handler's steering context. The built-in `ToolLedgerProvider` tracks tool call history, timing, and results. Steering handlers read from this context when deciding whether to intervene.

## Intervention Points

### Before a Tool Call

When you want the handler to validate a tool call before it runs, return a steering action from `beforeToolCall`:

```mermaid
flowchart LR
    A[Tool Call Attempt] --> B[BeforeToolCallEvent]
    B --> C[Handler Evaluates Call]
    C --> D{Steering Action}
    D -->|Approve| E[Tool Executes]
    D -->|Guide| F[Cancel + Feedback]
    D -->|Pause for Human| G[Human Input]
```

The handler returns one of three actions:

- **`InterventionActions.proceed()`**: tool executes immediately
- **`InterventionActions.guide(feedback)`**: tool is cancelled, agent receives contextual feedback and retries
- **`InterventionActions.confirm(prompt)`**: tool execution pauses for human approval

### After a Model Response

When you want the handler to validate the model's output before it reaches the user, return a steering action from `afterModelCall`:

```mermaid
flowchart LR
    A[Model Response] --> B[AfterModelCallEvent]
    B --> C[Handler Evaluates Output]
    C --> D{Steering Action}
    D -->|Approve| E[Response Accepted]
    D -->|Guide| F[Discard + Retry]
```

The handler returns one of two actions:

- **`InterventionActions.proceed()`**: accept the response as-is
- **`InterventionActions.guide(feedback)`**: discard the response and retry with guidance injected into the conversation

## Writing Custom Steering Logic

`SteeringHandler` extends `InterventionHandler` and narrows the return types to enforce a steering-specific contract:

| Method | Valid Returns | Purpose |
|--------|-------------|---------|
| `beforeToolCall` | `Proceed \| Guide \| Confirm` | Gate or redirect a tool call |
| `afterModelCall` | `Proceed \| Guide` | Validate model output before delivery |

The wider intervention vocabulary (`Deny`, `Transform`) is excluded at the type level — out-of-contract actions are caught at compile time. Subclass `SteeringHandler` when you want to write imperative steering logic:

```typescript
--8<-- "user-guide/concepts/agents/interventions/steering_imports.ts:basic_steering_imports"

--8<-- "user-guide/concepts/agents/interventions/steering.ts:basic_steering"
```

`SteeringHandler` also implements `LifecycleObserver`. When the agent initializes, it calls `observeAgent(agent)` on each intervention handler that implements this interface. `SteeringHandler` forwards this call to its registered context providers, allowing them to self-subscribe to agent hooks.

## Steering with Natural Language

When you want to express steering rules in natural language rather than imperative code, use `LLMSteeringHandler`. It delegates decisions to an LLM that evaluates each tool call against your system prompt and the accumulated steering context.

```typescript
--8<-- "user-guide/concepts/agents/interventions/steering_imports.ts:llm_steering_imports"

--8<-- "user-guide/concepts/agents/interventions/steering.ts:llm_steering"
```

```mermaid
sequenceDiagram
    participant U as User
    participant A as Agent
    participant S as Steering Handler
    participant T as Tool

    U->>A: "Send frustrated email to client"
    A->>A: Reason about request
    A->>S: Evaluate send_email tool call
    S->>S: Evaluate tone in message
    S->>A: Guide toward professional tone
    A->>A: Revise approach
    A->>S: Evaluate revised send_email
    S->>A: Proceed
    A->>T: Execute send_email
    T->>A: Email sent
    A->>U: "I've sent a professional email..."
```

### Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `systemPrompt` | `string \| SystemContentBlock[]` | *(required)* | Steering rules for the evaluation LLM |
| `model` | `Model` | Parent agent's model | Model used for steering evaluation |
| `contextProviders` | `SteeringContextProvider[]` | `[new ToolLedgerProvider()]` | Providers that supply evaluation context. Pass `[]` to disable |
| `promptBuilder` | `PromptBuilder` | Built-in builder with cache points | Custom function to build evaluation prompts |
| `name` | `string` | `'strands:llm-steering-handler'` | Unique handler name (must be distinct if multiple handlers are attached) |

### How it works

1. Before each tool call, the handler collects context snapshots from all registered providers.
2. It builds an evaluation prompt combining your system prompt, the context data, and the pending tool call details.
3. A **fresh inner Agent** evaluates the prompt and returns a structured decision: `proceed`, `guide`, or `confirm`.
4. The decision maps to the corresponding intervention action.

The inner agent is constructed fresh per evaluation — this keeps the handler stateless and safe for concurrent evaluations across multiple parent agents.

The default prompt builder uses **prompt caching**: static instructions are separated from dynamic context with a `CachePointBlock`, reducing API costs for repeated evaluations within the same session.

For best practices on writing steering prompts, see the [Agent Standard Operating Procedures (SOP)](https://github.com/strands-agents/agent-sop) framework.

## What the Handler Sees

Context providers are passive observers that track agent activity and supply structured data to steering handlers. They implement the `SteeringContextProvider` interface:

- **`name`** — identifier for the provider instance
- **`observeAgent(agent)`** — called once at initialization; subscribe to hooks here
- **`context`** (getter) — returns the current context snapshot for steering evaluation

```typescript
--8<-- "user-guide/concepts/agents/interventions/steering_imports.ts:custom_context_provider_imports"

--8<-- "user-guide/concepts/agents/interventions/steering.ts:custom_context_provider"
```

Providers self-register their hooks via `observeAgent` — the steering handler does not need to know which hooks a provider uses. This keeps concerns cleanly separated: providers observe, handlers decide.

## ToolLedgerProvider

The built-in `ToolLedgerProvider` tracks tool call history within a session. It records:

- Tool name and input arguments
- Start and end timestamps
- Execution status (`pending`, `success`, `error`)
- Result content and error messages

This gives the steering LLM visibility into patterns like repeated failures, excessive retries, or tool usage sequences.

```typescript
--8<-- "user-guide/concepts/agents/interventions/steering_imports.ts:tool_ledger_config_imports"

--8<-- "user-guide/concepts/agents/interventions/steering.ts:tool_ledger_config"
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `maxEntries` | `number` | `100` | Maximum tool calls to retain (oldest dropped) |
| `name` | `string` | `'strands:steering:toolLedger'` | Provider instance identifier |

`LLMSteeringHandler` creates a `ToolLedgerProvider` by default if you don't specify `contextProviders`. Pass an empty array to disable it, or combine it with your own providers for richer context.

## Related topics

- [Interventions](./index.mdx) — The typed action model, lifecycle methods, evaluation order, and error handling
- [Hooks](../hooks.mdx) — Low-level event callbacks that context providers subscribe to
- [Steering (Python)](../../plugins/steering.mdx) — Python-specific steering using the plugins interface
