95 lines
5.0 KiB
Markdown
95 lines
5.0 KiB
Markdown
---
|
|
phase: 05-employee-design
|
|
plan: "01"
|
|
subsystem: backend-api
|
|
tags: [agent-templates, system-prompt, migration, rbac, tdd]
|
|
dependency_graph:
|
|
requires: [04-rbac]
|
|
provides: [template-gallery-api, system-prompt-builder]
|
|
affects: [packages/shared, packages/gateway, migrations]
|
|
tech_stack:
|
|
added: []
|
|
patterns:
|
|
- AgentTemplate ORM model (global, non-tenant-scoped)
|
|
- build_system_prompt() functional builder with mandatory AI transparency clause
|
|
- Alembic migration with seed data via conn.execute() + CAST jsonb pattern
|
|
key_files:
|
|
created:
|
|
- packages/shared/shared/models/tenant.py (AgentTemplate class added)
|
|
- packages/shared/shared/prompts/__init__.py
|
|
- packages/shared/shared/prompts/system_prompt_builder.py
|
|
- migrations/versions/007_agent_templates.py
|
|
- packages/shared/shared/api/templates.py
|
|
- tests/unit/test_system_prompt_builder.py
|
|
- tests/integration/test_templates.py
|
|
modified:
|
|
- packages/shared/shared/api/__init__.py (export templates_router)
|
|
- packages/gateway/gateway/main.py (mount templates_router)
|
|
decisions:
|
|
- "AgentTemplate is NOT tenant-scoped — templates are global, readable by all authenticated users, no RLS needed"
|
|
- "Deploy creates an independent Agent snapshot — changes to template do not affect deployed agents"
|
|
- "GET /templates and GET /templates/{id} use get_portal_caller (not require_tenant_member) — no tenant_id path parameter available, any authenticated user can browse"
|
|
- "AI transparency clause always appended — non-negotiable per Phase 1 architectural decision"
|
|
- "Seed data uses conn.execute() with CAST(:col AS jsonb) pattern — consistent with Phase 2 asyncpg jsonb handling"
|
|
metrics:
|
|
duration: "7 minutes"
|
|
completed_date: "2026-03-25"
|
|
tasks_completed: 2
|
|
files_created_or_modified: 9
|
|
---
|
|
|
|
# Phase 5 Plan 01: Agent Templates — Backend Foundation Summary
|
|
|
|
AgentTemplate ORM model, Alembic migration 007 with 7 seed templates, system prompt builder with mandatory AI transparency clause, template gallery API (list/detail/deploy), and comprehensive unit + integration test coverage.
|
|
|
|
## Tasks Completed
|
|
|
|
| # | Task | Commit | Files |
|
|
|---|------|--------|-------|
|
|
| 1 | AgentTemplate model, migration 007, system prompt builder, unit tests | d1acb29 | tenant.py, 007_agent_templates.py, prompts/system_prompt_builder.py, test_system_prompt_builder.py |
|
|
| 2 | Template API endpoints (list, detail, deploy) + RBAC + integration tests | f9ce3d6 | templates.py, __init__.py, main.py, test_templates.py |
|
|
|
|
## What Was Built
|
|
|
|
### AgentTemplate ORM Model (`packages/shared/shared/models/tenant.py`)
|
|
|
|
Added `AgentTemplate` class with fields: id (UUID PK), name, role, description, category, persona, system_prompt, model_preference, tool_assignments (JSON), escalation_rules (JSON), is_active, sort_order, created_at. NOT tenant-scoped — no tenant_id, no RLS.
|
|
|
|
### Migration 007 (`migrations/versions/007_agent_templates.py`)
|
|
|
|
Creates `agent_templates` table and seeds 7 professional templates:
|
|
1. Customer Support Rep (support) — zendesk tools, sentiment/billing escalation
|
|
2. Sales Assistant (sales) — calendar_book, pricing negotiation escalation
|
|
3. Office Manager (operations) — calendar_book, HR complaint escalation
|
|
4. Project Coordinator (operations) — deadline missed escalation
|
|
5. Financial Manager (finance) — large transaction threshold escalation
|
|
6. Controller (finance) — budget exceeded escalation
|
|
7. Accountant (finance) — invoice discrepancy escalation
|
|
|
|
### System Prompt Builder (`packages/shared/shared/prompts/system_prompt_builder.py`)
|
|
|
|
`build_system_prompt(name, role, persona, tool_assignments, escalation_rules) -> str` assembles: identity header + optional tools section + optional escalation section + mandatory AI transparency clause. Empty/None tools and escalation rules omit their sections cleanly.
|
|
|
|
### Template API (`packages/shared/shared/api/templates.py`)
|
|
|
|
- `GET /api/portal/templates` — list active templates ordered by sort_order, any authenticated caller
|
|
- `GET /api/portal/templates/{id}` — template detail, 404 if inactive or missing
|
|
- `POST /api/portal/templates/{id}/deploy` — creates Agent snapshot for tenant, tenant_admin only (customer_operator gets 403)
|
|
|
|
## Test Coverage
|
|
|
|
- **17 unit tests** (`tests/unit/test_system_prompt_builder.py`): full prompt, minimal, empty sections, AI clause always present
|
|
- **11 integration tests** (`tests/integration/test_templates.py`): list 7+ templates, field verification, single template detail, deploy creates snapshot, platform_admin deploy, operator 403, not-found 404, two deploys create independent agents
|
|
|
|
## Deviations from Plan
|
|
|
|
None — plan executed exactly as written.
|
|
|
|
Pre-existing test failures noted (not caused by this plan):
|
|
- `tests/integration/test_invite_flow.py` — Celery/Redis not available at localhost:6379 in dev env
|
|
- `tests/integration/test_portal_rbac.py` — RLS policy violation in `_create_agent` fixture (no SET LOCAL before INSERT)
|
|
|
|
## Self-Check: PASSED
|
|
|
|
All 8 expected files present. Both task commits verified (d1acb29, f9ce3d6). Unit tests (17) and integration tests (11) pass.
|