Recommended content:

````markdown
# AI Agent Runtime Technical Plan

## 1. Purpose

This document tracks the technical foundation needed to turn approved Numu Agent Training Packages into a controlled backend runtime.

This is not production implementation yet.

## 2. Current Decision

The AI Agent Runtime will start inside the existing dashboard backend repo under:

```text
/ai-agents
```

> Note: `/ai-agents` is the confirmed canonical foundation path (the earlier `/backend/ai-agents` reference is superseded).

This may later be extracted into a separate repo/service if needed.

## 3. Required Components

### 3.1 Registry Reader

Purpose:

- read `AGENT_KNOWLEDGE_REGISTRY.json`
- identify registered agents
- load agent metadata
- validate required files exist
- prevent unregistered agents from running

Open item:

- confirm canonical AUTO-026 key: `pre_screen` vs `prescreen`

### 3.2 Knowledge Loader

Purpose:

- read runtime-loadable files for each registered agent
- assemble model context
- validate required sections
- produce a compiled prompt package for runtime

### 3.3 Knowledge Cache

Purpose:

- cache compiled agent knowledge
- store version/hash/timestamp
- avoid repeatedly rebuilding unchanged agent context
- invalidate cache when registered files change

### 3.4 Agent Runtime

Purpose:

- accept agent run request
- load startup input
- load agent knowledge
- call model
- validate structured output
- return recommendation
- never directly execute business actions

### 3.5 AgentRun Logging

Purpose:

Record every agent execution.

Suggested fields:

```text
agent_run_id
agent_key
startup_id
input_reference
model
prompt_package_version
knowledge_hash
output_json
recommendation
approval_status
error_code
error_message
created_at
completed_at
created_by
```

### 3.6 Handoff Persistence

Purpose:

- create Handoff records
- retrieve latest valid Handoff
- link Handoff to startup, source agent, target agent, and AgentRun
- support idempotency
- support supersede/correction once backend contract exists

Open items:

- backend idempotency
- supersede/correction endpoint
- trigger ownership: Runtime vs Make fallback

### 3.7 Notes Persistence

Purpose:

- save internal AI analysis Notes
- link Notes to startup and AgentRun
- distinguish internal Note from founder-facing message
- do not claim final action execution unless execution layer confirms it

Open item:

- confirm final Note persistence endpoint/path

### 3.8 Approval Requests

Purpose:

- create approval requests for human review
- support approval/rejection by authorized users
- log reviewer and timestamp
- trigger execution layer only after approval

AUTO-026 actions requiring approval:

```text
request_more_info
request_meeting
reject
```

### 3.9 Execution Layer

Purpose:

Execute approved actions only after human approval.

Potential actions:

```text
request_more_info
request_meeting
reject
```

Execution Layer may later handle:

- status/group transition
- founder communication
- internal Note persistence
- Handoff persistence
- audit logging

Open items:

- live `request_meeting` action availability
- resulting Group/Status after `request_more_info`
- resulting Group/Status after `request_meeting`
- rejection transition behavior
- policy approval surfacing

## 4. Environment Variables

Do not store values in repo.

Only define names/placeholders.

Possible environment variable names:

```text
ANTHROPIC_API_KEY
NUMU_API_BASE_URL
NUMU_API_TOKEN
MAKE_API_TOKEN
SENDPULSE_CLIENT_ID
SENDPULSE_CLIENT_SECRET
TWOCHAT_API_KEY
MICROSOFT_GRAPH_CLIENT_ID
MICROSOFT_GRAPH_CLIENT_SECRET
AZURE_KEY_VAULT_URL
```

Final names should match the backend environment convention.

## 5. Testing Strategy

Initial tests should be local/staging only.

Do not test on production startups.

Test layers:

1. Registry reader unit test
2. Knowledge loader unit test
3. Structured output validation test
4. AgentRun logging test
5. Handoff create/read test using test data only
6. Approval request test using test data only
7. Execution layer dry-run test

## 6. Production Readiness Requirements

Before production:

- branch protection active
- CI pipeline running
- staging environment available
- secrets stored outside repo
- AgentRun logging implemented
- structured model output validation implemented
- backend Handoff idempotency implemented or explicitly approved alternative
- approval workflow implemented
- execution layer tested
- rollback strategy defined
- monitoring/logging enabled
- no live writes without approval

## 7. Open Decisions for Fahad / Developer

- Canonical agent key: `pre_screen` or `prescreen`
- AUTO-026 Registry inclusion timing
- Runtime trigger ownership
- Handoff persistence ownership
- Handoff supersede/correction contract
- Note persistence path
- live `request_meeting` action availability
- resulting Group/Status rules
- approval UI behavior
- staging test startup/entity
````

---