Optional Microsoft Entra Agent Registry Integration for Agent Registration

Nobody has claimed this yet.

Add optional enablement for administrators to register SimpleChat agents (global, group, and personal) with the [Microsoft Entra Agent Registry](https://learn.microsoft.com/en-us/entra/agent-id/identity-platform/publish-agents-to-registry), providing centralized visibility, identity management, and discoverability of agents across the organization via the Microsoft Graph API.

### Motivation

Today, SimpleChat agents (configured in `personal_agents`, `global_agents`, and `group_agents` Cosmos containers) exist solely within the application boundary. They have no visibility or governance footprint in Microsoft Entra ID. As organizations scale AI agent deployments, IT administrators need:

- **Centralized inventory** — A single registry view of all agents across platforms (Microsoft and non-Microsoft).
- **Agent identity & authentication** — Each agent can receive its own Entra identity, enabling scoped permissions, Conditional Access policies, and audit logging.
- **Discoverability** — Agent Card manifests allow other agents, applications, and orchestrators to discover and interact with registered agents.
- **Lifecycle governance** — Admins can disable, audit, and manage agents from the Entra Admin Center.

Since SimpleChat is not one of the auto-integrated Microsoft products (Copilot Studio, Microsoft Agent 365, Azure AI Foundry), **self-serve registration via the Microsoft Graph API** is required.

---

### Proposed Feature

#### 1. Admin-Level Configuration (Admin Settings)

Add a new section in **Admin Settings** to configure Microsoft Entra Agent Registry integration:

| Setting | Description |
|---|---|
| **Enable Agent Registry** | Toggle to enable/disable registration of agents with Microsoft Entra Agent Registry |
| **Agent Identity Blueprint App ID** | The `appId` of the pre-configured Agent Identity Blueprint in the tenant |
| **Agent Identity Blueprint Object ID** | The object ID for credential and scope management |
| **Agent Identity Blueprint Credential** | Client secret or managed identity reference used to acquire tokens for the blueprint |
| **Tenant ID** | The Microsoft Entra tenant ID |
| **Default Originating Store** | Label identifying SimpleChat as the originating platform (e.g., `"SimpleChat"`) |
| **Preferred Transport** | Default transport protocol for the agent endpoint (e.g., `"HTTP+JSON"`) |
| **Agent Endpoint URL Base** | Base URL of the SimpleChat deployment used to construct agent endpoint URLs |

#### 2. Per-Agent Registration Toggle

When Agent Registry is enabled at the admin level, expose an **optional toggle** on each agent configuration (global, group, and personal agent modals):

- **"Register with Microsoft Entra Agent Registry"** — checkbox/toggle (default: off)
- When enabled, on agent save, the system should:
1. **Create an Agent Identity** via the blueprint (if one doesn't already exist for this agent)
2. **Register an Agent Instance** in the registry via `POST /beta/agentRegistry/agentInstances`
3. **Register an Agent Card Manifest** with discovery metadata (display name, description, skills, icon, etc.)
- Store the returned `agentInstanceId`, `agentIdentityId`, and `agentCardId` on the agent document in Cosmos DB for future updates/deletes.

#### 3. Agent Identity Blueprint Prerequisites (Documented Setup)

Before using this feature, the tenant admin must complete the following setup outside of SimpleChat (documented in feature docs):

1. **Create an Agent Identity Blueprint** via Microsoft Graph API:
```http
POST https://graph.microsoft.com/beta/applications/
OData-Version: 4.0
Content-Type: application/json

{
"@odata.type": "Microsoft.Graph.AgentIdentityBlueprint",
"displayName": "SimpleChat Agent Blueprint",
"sponsors@odata.bind": ["https://graph.microsoft.com/v1.0/users/"],
"owners@odata.bind": ["https://graph.microsoft.com/v1.0/users/"]
}
```
2. **Create the Blueprint Service Principal**
3. **Configure credentials** (managed identity recommended for production; client secret for dev/test)
4. **Configure identifier URI and OAuth scope** (`access_agent`)
5. **Grant required permissions**: `AgentInstance.ReadWrite.All`, `AgentIdentityBlueprint.Create`, `AgentIdentity.CreateAsManager`

#### 4. Registration Payload Mapping

Map existing SimpleChat agent data to the Agent Registry schema:

| SimpleChat Agent Field | Agent Instance Field | Agent Card Field |
|---|---|---|
| `display_name` | `displayName` | `displayName` |
| `description` | — | `description` |
| `name` (slug) | `sourceAgentId` | — |
| `id` (Cosmos ID) | (internal tracking) | — |
| Admin user OID | `ownerIds[]` | `ownerIds[]` |
| App endpoint + agent route | `url` | — |
| Agent instructions/skills | — | `skills[]` |
| Agent icon (if any) | — | `iconUrl` |

#### 5. Lifecycle Management

| Action | Behavior |
|---|---|
| **Agent Created** (with registry toggle on) | Create agent identity + register instance + register card |
| **Agent Updated** | Update agent instance and card metadata via PATCH |
| **Agent Deleted** | Delete agent identity, deregister instance from registry |
| **Registry Toggle Disabled** | Deregister from registry, delete agent identity, clear stored IDs |
| **Admin Disables Feature Globally** | Bulk deregister all previously registered agents (with confirmation) |

#### 6. Registration Status Visibility

- Show registration status badge on agent cards in the UI (e.g., "Registered", "Not Registered", "Registration Failed")
- Display the `agentIdentityId` and `agentInstanceId` in the agent detail view (read-only)
- Log registration events to the existing activity/audit system

---

### Technical Implementation Notes

#### New Backend Module

Create `functions_agent_registry.py` to encapsulate all Microsoft Graph API interactions:

- `acquire_blueprint_token(tenant_id, blueprint_app_id, credential)` — Get access token via client credentials flow
- `create_agent_identity(token, blueprint_id, display_name, sponsors)` — Create agent identity via Graph
- `register_agent_instance(token, agent_data, endpoint_url)` — POST to `/beta/agentRegistry/agentInstances`
- `register_agent_card(token, instance_id, card_manifest)` — Register agent card manifest
- `update_agent_instance(token, instance_id, updated_data)` — PATCH agent instance
- `delete_agent_instance(token, instance_id)` — DELETE agent instance
- `delete_agent_identity(token, identity_id)` — DELETE agent identity
- `get_agent_registration_status(token, instance_id)` — Verify registration

#### API Endpoints

| Method | Endpoint | Description |
|---|---|---|
| POST | `/api/admin/agent//register-entra` | Register a specific agent with the registry |
| DELETE | `/api/admin/agent//deregister-entra` | Deregister a specific agent |
| GET | `/api/admin/agent//entra-status` | Get registration status |
| POST | `/api/admin/agents/bulk-register-entra` | Bulk register all eligible agents |
| POST | `/api/admin/agents/bulk-deregister-entra` | Bulk deregister all agents |

Start by mapping the personal_agents, global_agents, and group_agents Cosmos containers to the proposed functions_agent_registry.py module and the listed admin API endpoints. Review the Microsoft Graph Agent Registry prerequisites and payload mapping before planning the admin settings and per-agent controls. Done means registration, updates, deletion, status visibility, auditing, and global disable behavior are covered end to end.

Written by the indexing model from the issue text.