# Phase 5 Prerequisites — Agent Runtime, SharePoint/Graph, AI Model, Make

Everything needed to move from the committed **Knowledge Cache** (Phase 4) to the live **Agent
Runtime** (Phase 5). Phase 5 extends the SAME implementation on branch `feat/agent-knowledge-cache`
— no separate module/repo/service.

> ⚠️ **Never** put a secret, token, certificate, or key in Git or in chat. Supply them via `.env`
> / a secret manager only. See §5 for where each item lives.

---

## 1. Azure / Microsoft Graph (to enable `AGENT_KNOWLEDGE_SOURCE=graph`)

**App Registration permissions (application / app-only, admin-consented):**
| Permission | Why | Preferred |
|---|---|---|
| `Files.Read.All` **or** `Sites.Selected` (+ per-site read grant) | read the agent `.md` files | `Sites.Selected` (least privilege) |
| `Sites.Read.All` | only if `Sites.Selected` is not acceptable | fallback (broader) |

- **Admin consent:** required (application permissions). A Global/Cloud‑App admin must consent.
- **Credential:** client secret **or** certificate (certificate preferred for production rotation).
- The existing Bookings app (`MS_GRAPH_*`) can be reused **only if** these scopes are added +
  consented; otherwise register a dedicated app.

**Environment variables:**
```
AGENT_KNOWLEDGE_SOURCE=graph
AGENT_KNOWLEDGE_GRAPH_DRIVE_ID=<sharepoint/onedrive drive id>
AGENT_KNOWLEDGE_GRAPH_ROOT=Numu_Workspace/Numu_Automation/Startup Agents
MS_GRAPH_TENANT_ID / MS_GRAPH_CLIENT_ID / MS_GRAPH_CLIENT_SECRET   # reuse or dedicate
```

**SharePoint / Drive / Site IDs:** the **drive ID** (or the **site ID** + drive discovery). Confirm
whether the source is a **SharePoint document library** (recommended) or **personal OneDrive**.

**Folder structure (per agent):** `<GRAPH_ROOT>/<agent folder>/04 Knowledge/` containing the four
approved files: `SKILL.md`, `DECISION_RULES.md`, `NOTE_GUIDE.md`, `HANDOFF_SCHEMA.md`.

| agent_key (real) | folder | status |
|---|---|---|
| `intake_triage` | `AUTO-025 - Startup Intake Triage Agent - v01` | known |
| `prescreen` | *TBD* | needed |
| `founder_response_analysis` | *TBD* | needed |
| `screening_call_analysis` | *TBD* | needed |
| `initial_due_diligence` | *TBD* | needed |
| `committee_analysis` | *TBD* | needed |
| `investment_memo` | *TBD* | needed |

`SKILL.md` **must** contain its `agent_key` (loader validation). Per‑agent folder overrides are env‑driven
(`AGENT_KNOWLEDGE_FOLDER_*`).

---

## 2. AI provider

- **Recommended provider:** **Anthropic Claude** — consistent with Numu's existing Claude API usage
  (name localization, enrichment) and this Claude‑integrated stack. (OpenAI/Azure OpenAI possible if
  mandated; the Runtime will abstract the provider behind one interface.)
- **Recommended model:** `claude-sonnet-5` (balanced reasoning/cost) as default; `claude-opus-4-8`
  for the deepest‑reasoning stages (e.g. investment_memo). Model id may be stored per AgentRun.
- **Secret:** provider API key (e.g. `ANTHROPIC_API_KEY`).
- **Region / compliance:** confirm data residency requirements, and that **provider training on
  submitted data is disabled**; set request timeout, input/output token limits, retry + budget caps.
- **PII:** define fields that must **never** be sent to the provider (Runtime redaction layer).

---

## 3. Make.com

- **Scenario to update:** the startup agent scenario(s) (e.g. **AUTO‑025 Scenario 03**) — extended,
  not replaced.
- **Endpoints Make will call (all `McpAuth:full`):**
  1. `GET /api/v1/ai/agents/{agent_key}/knowledge/meta?environment=` — cheap change check (checksum).
  2. `GET /api/v1/ai/agents/{agent_key}/knowledge?environment=` — full approved knowledge (when changed).
  3. `POST /api/v1/ai/agent-runs` — create the run, **passing `knowledge_version` + `knowledge_checksum`** from step 1/2.
  4. *(Phase 5)* `POST /api/v1/ai/agent-runtime/run` — Numu Runtime returns analysis/proposed action.
  5. `POST /api/v1/ai/agent-runs/{run}/decision` — submit the decision → existing policy/approval/execution pipeline.
- **Data Make must pass back to Numu:** `knowledge_version`, `knowledge_checksum` (on run create),
  the proposed `action_slug` + reason/confidence (on `/decision`). Make stays **orchestration only** —
  no policy/approval/execution logic.
- **Webhooks/secrets:** none required for the cache (manual refresh). A SharePoint change webhook is
  optional future work if you want event‑driven refresh.

---

## 4. Infrastructure

- **Environments:** dev / staging / production **already supported** by the cache (independent active
  pointers). Decide: same SharePoint source for all, or separate folders per environment; who approves
  production activation.
- **Redis / cache:** already used (Graph token cache). No new store required for the cache. A **queue**
  is optional (only if refresh becomes async; v1 is synchronous). A **scheduler** is optional (only for
  scheduled checksum verification — Phase 5+).
- **Storage:** knowledge lives in the relational DB (`files_json`); **no object storage needed**.
- **Monitoring / alerting / logging (Phase 5 hardening):** metrics for loader success/failure, stale
  knowledge, validation failures, rollback events, and (Runtime) AI latency/cost + structured‑output
  failures; a health endpoint; alert routing. Today these are **audited** to `activity_logs` but not
  yet metered/alerted.

---

## 5. Ownership / storage / timing (per item)

| Item | Who provides | Where stored | Required before Phase 5? |
|---|---|---|---|
| Azure app + `Files/Sites` consent | Numu Azure admin | Azure AD | Only to enable **graph** mode (local mode needs none) |
| `MS_GRAPH_*` (tenant/client/secret or cert) | Azure admin | `.env` / secret manager (**not Git**) | To enable graph mode |
| `AGENT_KNOWLEDGE_GRAPH_DRIVE_ID` / `_ROOT` | SharePoint owner | `.env` | To enable graph mode |
| Per‑agent folder names (6 TBD) | Knowledge owner | `config/agent_knowledge.php` or `AGENT_KNOWLEDGE_FOLDER_*` env | Before loading those agents |
| Approved `.md` packs | Claude Cowork drafts → human approves | SharePoint (source of truth) | Before refreshing that agent |
| AI provider API key | Numu | secret manager / `.env` (**not Git**) | Phase 5 (Runtime) — can be provided later |
| AI model id + limits + compliance | Numu | `config` + `.env` | Phase 5 |
| Make scenario updates | Numu automation owner | Make.com | Phase 5 |
| Monitoring/alerting stack | Numu ops | infra | Phase 5 (can follow initial pilot) |

**Can begin Phase 5 now without:** graph credentials (local mode works), AI key (until Runtime is
wired), Make changes (until Runtime endpoint exists). **Blocking for graph production:** Azure consent
+ drive id + the real `.md` packs.