# AI Agent Modes & Step Roles (R17 — v3.46)

> **Reference for `ai-prompt` skill** — how to choose `AiAgentMode` and `AiAgentStepRole` when scaffolding multi-step AI agents.

## When This Reference Applies

- You create an `AiAgent` with more than one step
- You need a non-Sequential reasoning mode (loop, plan-then-execute, self-correct)
- The user asks "how do I make the agent retry", "how do I make it plan first", "what is ReAct"

For single-prompt skills, the basic `Prompt + Block + OutputSchema` pattern is enough — no agent, no mode.

---

## `AiAgentMode` (4 values)

| Mode | Value | Use case | Latency | Cost |
|---|---|---|---|---|
| `Sequential` | 0 | Known DAG fan-out / fan-in (analyze → summarize → email) | Low | Low |
| `ReAct` | 1 | Reasoning + tool loop, plan unknown ahead of time | High | High |
| `PlanAndExecute` | 2 | Task that can be planned upfront then executed | Medium | Medium |
| `SelfCorrection` | 3 | Output that can be critiqued and replayed | Medium | Medium-High |

### Recommended configuration

| Field | Default | Range |
|---|---|---|
| `MaxIterations` | 5 | [1..20] — protects against infinite loops |
| `QualityThreshold` | 0.8 | [0..1] — used by `SelfCorrection` to decide replay |

---

## `AiAgentStepRole` (5 values)

| Role | Value | Expected output schema |
|---|---|---|
| `Worker` | 0 | Standard skill output (used in `Sequential` mode) |
| `Planner` | 1 | `{ plan: [{ skillCode, label }] }` — produces the plan in `PlanAndExecute` |
| `Reasoner` | 2 | `{ action, input }` or `{ final_answer }` — used in `ReAct` |
| `Critic` | 3 | `{ score: 0..1, feedback?: string }` — used in `SelfCorrection` |
| `Synthesizer` | 4 | Final aggregated output (`PlanAndExecute` after parallel workers) |

---

## Cache hint (R-cache)

| Field | Type | Purpose |
|---|---|---|
| `AiSkill.CacheTtlSeconds` | `int?` | TTL for caching this skill's output (per input hash). Null = no cache. |
| `AiSkillBlock.IsCacheable` | `bool` | Marks an idempotent block whose output can be reused across executions. |

Only mark a skill / block cacheable when the output is **deterministic for a given input** — otherwise stale answers will be served.

---

## Choosing a mode (decision tree)

```
Question: do I know the steps in advance?
  Yes → Sequential
  No  → Question: can the LLM decide the steps once, then execute?
          Yes → PlanAndExecute
          No  → Question: must I let the LLM iterate with tools?
                  Yes → ReAct
                  No  → SelfCorrection (single attempt + critique loop)
```

---

## DO / DON'T

| ✅ DO | ❌ DON'T |
|---|---|
| Start with `Sequential` — switch to other modes only when needed | Default to `ReAct` (expensive, hard to debug) |
| Cap `MaxIterations` at the smallest number that satisfies your case | Leave the default 5 for `ReAct` on long-running tasks (set 10-15) |
| Set `QualityThreshold` based on prompt evaluation results | Pick `0.8` blindly — measure on your eval dataset |
| Use `Critic` role with a structured output schema | Let the critic return free-form text |
| Cache only deterministic, idempotent skills | Cache anything that uses `now()` or randomness |

---

## Reference source files (read-only)

- `D:\01 - projets\SmartStack.app\features\IA-Workflow\src\SmartStack.Domain\AI\Agents\AiAgent.cs`
- `D:\01 - projets\SmartStack.app\features\IA-Workflow\src\SmartStack.Domain\AI\Agents\AiAgentMode.cs`
- `D:\01 - projets\SmartStack.app\features\IA-Workflow\src\SmartStack.Domain\AI\Agents\AiAgentStep.cs`
- `D:\01 - projets\SmartStack.app\features\IA-Workflow\src\SmartStack.Domain\AI\Agents\AiAgentStepRole.cs`
- `D:\01 - projets\SmartStack.app\features\IA-Workflow\src\SmartStack.Domain\AI\Skills\AiSkill.cs` (CacheTtlSeconds)
- `D:\01 - projets\SmartStack.app\features\IA-Workflow\src\SmartStack.Domain\AI\Skills\AiSkillBlock.cs` (IsCacheable)
