Skip to main content

​
Phase Index

This document provides an authoritative index of all phases, their deliverables, locked decisions, and key artifacts.

​
Phase 6.7: Unified Agent Creation & Bulk Bootstrap

Status: ✅ Complete (commit 8b1e537)

​
What Shipped

  • Backend: Orchestrated agent create endpoint (POST /api/v1/admin/agent-profiles/create)
  • Backend: Idempotency-Key header support for UUIDv4 bootstrap path
  • Frontend: CreateAgentModal component for single agent creation
  • Frontend: BulkBootstrapModal component for CSV/table bulk import
  • BigQuery: Idempotency table (config_agent_profile_idempotency)

​
Key Files

  • api/routes/admin.py - Unified endpoint implementation
  • api/schemas/agent_profile_orchestrated.py - Request/response schemas
  • api/bigquery/phase4_profile_queries.py - Idempotency + helper functions
  • integration/bigquery/sql/tables/config_agent_profile_idempotency.sql - DDL
  • api/tests/test_admin_agent_profiles_create.py - Backend tests
  • dashboard/src/features/agentMapping/components/CreateAgentModal.tsx - Single agent UI
  • dashboard/src/features/agentMapping/components/BulkBootstrapModal.tsx - Bulk import UI
  • dashboard/src/features/agentMapping/api/agentMappingClient.ts - API client methods
  • dashboard/src/features/agentMapping/api/types.ts - TypeScript types
  • dashboard/src/features/agentMapping/views/ProfilesView.tsx - Integration view

​
Locked Decisions

  • Backend owns all UUID generation: No client-side UUID generation for agent_entity_id
    • UUIDv5 (deterministic) when agent_id provided: uuid5(namespace, tenant_id|org_id|agent_id)
    • UUIDv4 (bootstrap) when agent_id omitted
  • Orchestrated create endpoint: Single endpoint (POST /api/v1/admin/agent-profiles/create) orchestrates identity + contact creation
  • Idempotency-key usage: Only for UUIDv4 bootstrap path + heal scenarios (not required for UUIDv5 deterministic path)
  • Retry semantics: Use agent_entity_id parameter in request to reuse existing identity (no duplicate creation)
  • Org/tenant scoping: Enforced everywhere; cross-org requests return generic NOT_FOUND (no leak)

​
References

  • Checkpoint Document: PHASE_6_7_CHECKPOINT.md - Full API contract, smoke tests, verification steps
  • BigQuery DDL: integration/bigquery/sql/tables/config_agent_profile_idempotency.sql
  • Backend Tests: api/tests/test_admin_agent_profiles_create.py
  • Deployment Guide: docs/DEPLOYMENT.md - Manual deploy instructions for payroll-backend-prod
  • Audit Notes: docs/reference/AUDIT_NOTES_AGENT_CREATION.md - Invariants, failure modes, verification checklist

​
Service Routing

  • Config Plane (payroll-pipeline-cbs): Rate Plans, versions, rule authoring
  • System of Record (payroll-backend-prod): Agent identities, assignments, execution/audit
  • Phase 6.7 endpoint routes to System of Record (payroll-backend-prod)

​
Previous Phases

​
Phase 6.5: Identity Resolve Bridge

Status: ✅ Complete
  • Purpose: UI-accessible Identity Resolve bridge for admins
  • What it unlocks: Resolve legacy or new agent_id deterministically, generate/reuse agent_entity_id, seed identity
  • Implementation: Service layer helper (api/services/identity_seed.py), endpoint /api/v1/admin/identity/resolve

​
Next Phases

​
Phase 7A: No-Code Data Onboarding

Status: 📋 Planned (scaffold: PHASE_7A_KICKOFF.md)
  • Scope: Multi-source commission file onboarding, upload → validate → header mapping → stage snapshot → “ready for run”
  • Approach: Presigned upload workflow
  • Reference: PHASE_7A_KICKOFF.md - Scope, tables, endpoints, security invariants, smoke tests