> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Message Steering
> Send real-time guidance to agents during long-running execution
Message Steering lets you send guidance to a running agent without restarting it.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(
name="researcher",
instructions="You are a research assistant",
message_steering=True,
)
agent.start("Write a brief overview of agentic RAG.")
agent.steer("Focus on business impact, keep under 200 words", priority=10)
```
The user steers a long-running task mid-flight; guidance is queued and applied at the next safe boundary.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Message Steering"
U[👤 User] -->|steer message| Q[📬 Priority Queue]
Q -->|polled at chat/tool boundary| A[🤖 Running Agent]
A -->|adjusted response| R[✅ Response]
end
classDef user fill:#6366F1,stroke:#7C90A0,color:#fff
classDef queue fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef result fill:#10B981,stroke:#7C90A0,color:#fff
class U user
class Q queue
class A agent
class R result
```
## Quick Start
Enable with `message_steering=True` and use `agent.steer()` to send guidance.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(
name="researcher",
instructions="You are a research assistant",
message_steering=True,
llm="gpt-4o-mini",
)
agent.steer("Focus on business impact, keep under 200 words", priority=10)
agent.start("Summarise the latest AI trends")
```
Send steering messages while the agent is actively running.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import threading, time
from praisonaiagents import Agent
agent = Agent(name="writer", instructions="You write articles", message_steering=True)
def run():
return agent.start("Write a comprehensive article about quantum computing")
t = threading.Thread(target=run); t.start()
time.sleep(0.5); agent.steer("Make it beginner-friendly")
time.sleep(1.0); agent.steer("Include practical applications", priority=15)
time.sleep(1.5); agent.steer("Keep under 300 words total", priority=20)
t.join()
```
Use async execution with real-time steering.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import asyncio
from praisonaiagents import Agent
async def main():
agent = Agent(name="analyst", instructions="You analyse data", message_steering=True)
task = asyncio.create_task(agent.astart("Analyse impact of AI on job markets"))
await asyncio.sleep(0.3); agent.steer("Focus on positive opportunities")
await asyncio.sleep(0.7); agent.steer("Include specific examples", priority=12)
print(await task)
asyncio.run(main())
```
***
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Agent
participant Queue
participant LLM
User->>Agent: agent.start("long task")
Agent->>LLM: prompt
User->>Queue: agent.steer("be brief", priority=10)
Agent->>Queue: poll (next chat step)
Queue-->>Agent: [URGENT USER GUIDANCE]: be brief
Agent->>LLM: prompt + steering
LLM-->>Agent: shorter response
Agent-->>User: result
```
Message steering injects guidance at chat and tool execution boundaries without interrupting the agent's workflow.
***
## Priority Levels
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
Q{Need to change agent behaviour?} -->|Style nudge| N[NORMAL — priority=5]
Q -->|Important course correction| H[HIGH — priority=10]
Q -->|Must affect next tool call| U[URGENT — priority=20]
Q -->|Stop current tool NOW| I[INTERRUPT — priority=30]
classDef question fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef normal fill:#6366F1,stroke:#7C90A0,color:#fff
classDef high fill:#189AB4,stroke:#7C90A0,color:#fff
classDef urgent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef interrupt fill:#10B981,stroke:#7C90A0,color:#fff
class Q question
class N normal
class H high
class U urgent
class I interrupt
```
| Priority | Int value | Behaviour |
| --------- | --------- | ------------------------------------------------------ |
| LOW | 1 | Whispered guidance |
| NORMAL | 5 | Default priority |
| HIGH | 10 | Acknowledged urgently in next chat step |
| URGENT | 20 | Can interrupt tool execution |
| INTERRUPT | 30 | Bypasses rate limiting; immediate stop of current tool |
***
## CLI Usage
Enable message steering from command line:
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai --message-steering "Write a detailed report about AI trends"
```
The `--message-steering` flag sets `message_steering=True` on the agent.
***
## YAML Usage
Enable steering per role in YAML configuration:
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
framework: praisonai
roles:
researcher:
role: Research Assistant
goal: Conduct thorough research
message_steering: true # Enable per-role
tasks:
research_task:
description: Research AI trends and write report
expected_output: Comprehensive research report
```
***
## Configuration Options
| Option | Type | Default | Description |
| ------------------ | ----------------------------------- | ------- | ------------------------------- |
| `message_steering` | `bool` \| `MessageSteeringProtocol` | `False` | Enable steering |
| `max_messages` | `int` | `50` | Queue capacity (in constructor) |
| `check_interval` | `float` | `0.1` | Poll interval in seconds |
When `message_steering=False` (default), there's zero overhead - the feature has no performance impact when disabled.
***
## Agent Methods
| Method | Signature | Description |
| ------------------------------------- | ----------------------------------------------------- | ----------------------------------------------- |
| `steer` | `agent.steer(message: str, priority: int = 5) -> str` | Queue a steering message. Returns tracking ID. |
| `get_steering_status` | `agent.get_steering_status() -> Dict[str, Any]` | Returns `{enabled, pending_count, has_pending}` |
| `message_steering_enabled` (property) | `agent.message_steering_enabled -> bool` | Whether steering is active |
***
## Custom Steering Backends
Implement `MessageSteeringProtocol` to plug custom backends:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, MessageSteeringProtocol, SteeringMessage, SteeringPriority
class RedisSteering: # Implements MessageSteeringProtocol structurally
def queue_message(self, message: str, priority: int = 5) -> str: ...
def get_pending_messages(self): ...
def process_steering(self, context=None) -> bool: ...
def clear_messages(self) -> int: ...
def has_pending_messages(self) -> bool: ...
@property
def enabled(self) -> bool: ...
agent = Agent(name="bg", message_steering=RedisSteering())
```
***
## Best Practices
Start agents in background threads to enable concurrent steering. The threaded pattern is the primary use case for message steering.
Use NORMAL (5) for style guidance, HIGH (10) for course corrections, URGENT (20) to interrupt tools, and INTERRUPT (30) only for immediate stops.
Steering messages are injected into prompts. Keep them brief and actionable for best results.
Use `get_steering_status()` to check pending messages and ensure your guidance is being processed.
***
When wrapping a steering-enabled agent in a chat bot, set the bot's `busy_mode="steer"` to surface this capability to end users. See [Bot Run Control](/docs/features/bot-run-control).
***
## Related
Pre/post execution hooks (compile-time interception)
Interactive input vs background steering