---
title: Agent Architecture
description: Technical architecture of the RAI Planner agent including state management, instruction file references, interaction model, and session recovery
sidebar_position: 3
sidebar_label: Agent Architecture
keywords:
- RAI Planner
- agent architecture
- state management
- NIST AI RMF
tags:
- rai-planning
- architecture
- reference
author: Microsoft
ms.date: 2026-03-11
ms.topic: reference
estimated_reading_time: 7
---
## Architecture Diagram
```mermaid
flowchart TD
subgraph Agent ["RAI Planner Agent"]
RP["rai-planner.agent.md"]
RS["Researcher Subagent"]
RP -->|"delegates framework lookups"| RS
end
subgraph State ["Assessment State"]
SJ["state.json"]
AF["Phase Artifacts"]
SJ -->|"references"| AF
end
subgraph Instructions ["Instruction Files"]
I1["rai-identity"]
I2["rai-standards"]
I3["rai-security-model"]
I4["rai-impact-assessment"]
I5["rai-backlog-handoff"]
end
RP -->|"reads/writes"| SJ
RP -->|"generates"| AF
RP -->|"follows"| I1
RP -->|"follows"| I2
RP -->|"follows"| I3
RP -->|"follows"| I4
RP -->|"follows"| I5
```
The RAI Planner agent definition lives at `.github/agents/rai-planning/rai-planner.agent.md`. Six instruction files under `.github/instructions/rai-planning/` provide domain-specific guidance, auto-applied via `applyTo` patterns when working within `.copilot-tracking/rai-plans/`.
| Instruction file | Domain |
|-----------------------------------------|----------------------------------------------------------------------------------------|
| `rai-identity.instructions.md` | Agent identity, orchestration, state management, session recovery |
| `rai-standards.instructions.md` | Microsoft RAI Standard v2, NIST AI RMF subcategories, regulatory cross-references |
| `rai-security-model.instructions.md` | AI-specific threat taxonomy, `RAI-T-{CATEGORY}-{NNN}` format, likelihood-impact matrix |
| `rai-impact-assessment.instructions.md` | Control surface evaluation, evidence register, principle tradeoff analysis |
| `rai-backlog-handoff.instructions.md` | Dual-format backlog handoff, content sanitization, autonomy tiers |
| `rai-capture-coaching.instructions.md` | Exploration-first questioning techniques for capture mode |
## State Management
All assessment state persists under `.copilot-tracking/rai-plans/{project-slug}/`. The `state.json` file tracks phase progress, entry mode, and assessment metadata.
### State Fields
| Field | Type | Purpose |
|-----------------------------|----------------|-------------------------------------------------------------|
| `projectSlug` | string | Kebab-case project identifier |
| `raiPlanFile` | string | Path to the RAI plan markdown file |
| `currentPhase` | number | Current phase (1-5) |
| `entryMode` | string | `capture`, `from-prd`, or `from-security-plan` |
| `securityPlanRef` | string or null | Path to security plan state when using `from-security-plan` |
| `assessmentDepth` | string | `standard` or `deep` assessment tier |
| `standardsMapped` | boolean | Whether Phase 2 mapping is complete |
| `raiRiskSurfaceStarted` | boolean | Whether Phase 4 analysis has begun |
| `raiThreatCount` | number | Running count of identified RAI threats |
| `impactAssessmentGenerated` | boolean | Whether Phase 5 assessment is complete |
| `evidenceRegisterComplete` | boolean | Whether evidence register is finalized |
| `handoffGenerated` | boolean | Whether Phase 5 backlog handoff is complete |
| `gateResults` | object | Gate outcomes for threat coverage |
| `scoredDimensions` | object | Phase 5 scorecard: five dimensions, total, and outcome |
| `referencesProcessed` | array | Files that have been read and incorporated |
| `nextActions` | array | Pending action items for the current phase |
| `userPreferences` | object | User-specified preferences for interaction and output |
### Six-Step State Protocol
Every conversation turn follows this protocol:
| Step | Action | Description |
|------|-----------|---------------------------------------------------------------|
| 1 | READ | Load `state.json` at conversation start |
| 2 | VALIDATE | Confirm state integrity and check for missing fields |
| 3 | DETERMINE | Identify current phase and next actions from state |
| 4 | EXECUTE | Perform phase work (questions, analysis, artifact generation) |
| 5 | UPDATE | Update `state.json` with results |
| 6 | WRITE | Persist updated `state.json` to disk |
## Interaction Model
The agent asks up to 7 focused questions per turn, using emoji checklists to track progress within each phase.
| Marker | Meaning |
|--------|----------------------------------------------------|
| ❓ | Pending: question not yet answered |
| ✅ | Complete: answer received and recorded |
| ❌ | Blocked or skipped: user indicated "skip" or "n/a" |
Each turn begins by showing the current phase checklist status. When all questions for a phase reach ✅ or ❌, the agent summarizes findings and asks for explicit confirmation before advancing.
> [!NOTE]
> The agent never advances to the next phase without user confirmation. This ensures the user maintains control over assessment pacing and can revisit questions before moving forward.
## Session Resume Protocol
When returning to an existing RAI assessment, the agent follows a four-step resume protocol:
1. Read `state.json` from the project slug directory
2. Display current phase progress and checklist status
3. Summarize what was completed and what remains
4. Continue from the last incomplete action
### Post-Summarization Recovery
When conversation context is compacted, a five-step recovery process reconstructs state:
1. Read `state.json` for project slug and current phase
2. Read the RAI plan markdown file referenced in `raiPlanFile`
3. Reconstruct context from existing artifacts (system definition pack, standards mapping, security model addendum, control surface catalog)
4. Identify the next incomplete task within the current phase
5. Resume with a brief summary of recovered state and the next action
## Operational Constraints
* All files are created under `.copilot-tracking/rai-plans/{project-slug}/`
* The agent never modifies application source code
* Embedded standards (Microsoft RAI Standard v2, NIST AI RMF 1.0) are referenced from the rai-standards instruction file
* Additional framework lookups (WAF, CAF, ISO 42001, EU AI Act details) are delegated to the Researcher Subagent
* In `from-security-plan` mode, security plan artifacts are read-only
## Related Files
| File | Purpose |
|----------------------------------------------------------------------|-----------------------------------|
| `.github/agents/rai-planning/rai-planner.agent.md` | Agent definition |
| `.github/instructions/rai-planning/*.instructions.md` | Phase-specific instruction files |
| `.github/prompts/rai-planning/rai-capture.prompt.md` | Capture mode entry prompt |
| `.github/prompts/rai-planning/rai-plan-from-prd.prompt.md` | PRD-seeded entry prompt |
| `.github/prompts/rai-planning/rai-plan-from-security-plan.prompt.md` | Security plan-seeded entry prompt |
| `.copilot-tracking/rai-plans/{project-slug}/state.json` | Assessment state |
<!-- markdownlint-disable MD036 -->
*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,
then carefully refined by our team of discerning human reviewers.*
<!-- markdownlint-enable MD036 -->microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
docs/agents/rai-planning/agent-overview.md
160lines · modepreview