> ## 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.
# Escalation Pipeline
> Agent-centric progressive escalation from direct response to autonomous mode
The escalation pipeline adjusts execution complexity from simple answers to full autonomous loops — all via `Agent(autonomy=True)`.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Escalation Pipeline"
Request[📋 User Request] --> Process[⚙️ Escalation Pipeline]
Process --> Result[✅ Result]
end
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class Request input
class Process process
class Result output
```
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Agent
participant Feature as Escalation Pipeline
User->>Agent: Request
Agent->>Feature: Process request
Feature-->>Agent: Result
Agent-->>User: Response
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(
instructions="You are a helpful coding assistant.",
llm="gpt-4o-mini",
autonomy=True,
)
stage = agent.get_recommended_stage("Refactor the auth module")
print(stage) # "autonomous"
response = agent.start("What is Python?")
print(response)
```
The user sends a prompt; the agent escalates from direct answers to heuristic, planned, or autonomous execution based on task signals.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Escalation Pipeline"
In[📝 Prompt] --> Signals[🔍 Signal Detection]
Signals --> Stage[⚙️ Pick Stage]
Stage --> Agent[🤖 Agent]
Agent --> Out[✅ Response]
end
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class In input
class Signals,Stage process
class Agent agent
class Out output
```
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Agent
participant Escalator
User->>Agent: Send prompt
Agent->>Escalator: get_recommended_stage(task)
Escalator-->>Agent: direct / heuristic / planned / autonomous
Agent-->>User: Response at the right complexity
```
### Escalation Stages
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
Prompt[📋 Prompt] --> Signals[🔍 Signal detection]
Signals --> S0[Direct]
Signals --> S1[Heuristic]
Signals --> S2[Planned]
Signals --> S3[Autonomous]
S3 --> Guard[🛡 Loop guard + doom loop]
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
classDef stage fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef guard fill:#8B0000,stroke:#7C90A0,color:#fff
class Prompt input
class Signals process
class S0,S1,S2,S3 stage
class Guard guard
```
## Quick Start
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(
instructions="You are a helpful coding assistant.",
llm="gpt-4o-mini",
autonomy=True,
)
# Fast heuristics — no LLM call
stage = agent.get_recommended_stage("What is Python?")
signals = agent.analyze_prompt("Refactor the auth module")
print(stage) # direct
print(signals) # {'refactor_intent', 'complex_keywords'}
response = agent.start("What is Python?")
print(response)
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, AutonomyConfig
agent = Agent(
instructions="You are a coding assistant.",
autonomy=AutonomyConfig(
max_iterations=30,
doom_loop_threshold=5,
auto_escalate=True,
),
)
print(agent.autonomy_enabled)
print(agent.autonomy_config)
```
***
## Stages and Signals
| Stage | Name | Typical trigger |
| ----- | ---------- | ------------------------------------- |
| 0 | DIRECT | Simple questions (`simple_question`) |
| 1 | HEURISTIC | File paths, code blocks |
| 2 | PLANNED | Edit, test, or build intent |
| 3 | AUTONOMOUS | Multi-step refactor, complex keywords |
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(instructions="Assistant", autonomy=True)
agent.get_recommended_stage("What is Python?") # direct
agent.get_recommended_stage("Read src/main.py") # heuristic
agent.get_recommended_stage("Fix the bug in auth.py") # planned
agent.get_recommended_stage("Refactor auth and add tests") # autonomous
```
| Signal | Trigger examples |
| ------------------ | --------------------------------- |
| `simple_question` | "what is", "define", "explain" |
| `file_references` | Paths like `src/main.py` |
| `edit_intent` | "edit", "modify", "fix" |
| `refactor_intent` | "refactor", "restructure" |
| `complex_keywords` | "analyse", "optimise", "refactor" |
***
## CLI
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Simple question — DIRECT stage
praisonai "What is Python?"
# Complex task — escalates to AUTONOMOUS
praisonai "Refactor the auth module and add tests"
praisonai chat --autonomy
```
***
## Pipeline Components
Under `praisonaiagents/escalation/`:
* **Doom loop detector** — identical calls and no-progress patterns
* **Loop guard** — idempotency-aware tool-call guardrails on every `Agent`. See [Loop Guard](/docs/features/loop-guard).
* **Pipeline orchestration** — escalation triggers and recovery
* **Observability hooks** — metrics for escalation events
***
## Best Practices
Pass `autonomy=True` or an `AutonomyConfig` — the agent selects the stage automatically during execution.
Call `analyze_prompt()` to preview complexity without an LLM call when building UIs or routing logic.
Lower the threshold (e.g. `3`) for agents that may repeat tool calls; raise it for exploratory coding tasks.
No standalone pipeline objects — escalation, loop guard, and doom-loop detection live on `Agent`.
***
## Related
Pattern-based detection of stuck agent loops
Delegate subtasks when autonomy escalates