Agentic Architecture

Agentic Architecture — Multi-Agent Care Orchestration

The system behind agent-driven onboarding, scheduling, and care ops — the product's core differentiator. It is a multi-agent, orchestrated design: a durable Restate orchestrator (backend/worker) sequences specialist Gemini agents, grounded on an append-only care-context event log in Neon + pgvector, with human-in-the-loop gates and everything held inside the Vertex BAA boundary (see AI Tier and HIPAA Compliance).

Locked: Gemini (Vertex) brain · custom agent loop on Restate (durable runtime, backend/worker) · Neon + pgvector memory/moat · multi-agent, orchestrated · PHI in Neon under RLS, agent I/O never leaves the boundary. This is a buildable architecture spec, not a pitch — where a choice is still open it is fenced as WIP and enumerated in Open questions.

1. Topology — multi-agent, orchestrated

Orchestrator — a durable Restate workflow in backend/worker that owns the end-to-end journey (prospect → onboarded client), routes to specialists, holds durable state, and enforces the human-in-the-loop gates.
Specialist agents — each a Gemini loop with a scoped toolset:

Agent	Job	Front door
Intake	Converses with prospect/family, captures care needs, qualifies	Front door of the HomeCareHQ funnel
Care-planner	Turns needs into a proposed care plan (services, hours, caregiver attributes)	—
Scheduler	Matches caregivers (availability, geography, skills), designs + commits the schedule	—
Later	Billing, change/re-schedule, QA/eval agents	—

Each specialist is a sub-workflow / durable step the orchestrator invokes; the orchestrator sequences them and owns the kickoff gate. Conversational surfaces (the ui/web-app and, later, voice) drive the intake agent through the orchestrator, never the model directly.

2. The agent loop

Each agent is Gemini via Vertex (SDK google-genai, vertexai mode) running a bounded reason → tool-call → observe loop. Model tier and BAA/region posture are governed by the AI Tier decision (US region, abuse-logging opt-out, no ai.google.dev).
Tools are typed functions (JSON-schema, derived from the OpenAPI / Pydantic contract in backend/api) that:
- read/write Neon under RLS — the agent acts as the session identity, so it sees only entitled rows;
- call WellSky (referrals, EVV, caregivers);
- retrieve from the care-context log + pgvector;
- take actions — propose plan, commit schedule, send comms via Telnyx / AWS SES.
Determinism boundary: each LLM call and each tool call is wrapped as a Restate durable step — journaled and retriable. On crash the workflow resumes exactly where it left off, and already-committed side-effects are not re-run on replay.

Schema hygiene (HIPAA): never put PHI in JSON-schema field names, enums, or regex — tool schemas are cached without PHI protections. See AI Tier → HIPAA posture.

3. Memory & the data moat

Short-term (conversation + working state) lives in Restate workflow state — durable, survives restarts, no separate session store.
Long-term = the moat: an append-only care-context event log in Neon — every interaction, decision, plan, schedule change, and outcome captured as structured events. This is the proprietary dataset.
- Retrieval: pgvector over embeddings (gemini-embedding-001) of the log + notes, RLS-scoped so retrieval only surfaces entitled context. Agents ground via RAG, not prompt-stuffing.
- Embeddings are computed in-boundary — clinical text is PHI, so it is embedded inside the Vertex BAA boundary; never an out-of-boundary embedder.
A BigQuery mirror (via dbt) serves analytics / eval — de-identified where it leaves the boundary (see Data Pipeline).

The event-log schema is defined in schema/ (Drizzle) alongside the rest of the Neon model.

4. Durability + human-in-the-loop (why Restate)

The signature flow — chat → design schedule → implement → human kickoff call → activate — is long-running, suspendable, and human-gated.
Restate durable promises make "await a human" a first-class primitive: the workflow suspends to zero (scale-to-zero on Cloud Run) while waiting for a human action, then resumes deterministically — no polling, no lost state.
Approval gates: schedule commit + go-live block on a durable promise resolved by a care-coordinator UI action in the ui/web-app.
Idempotency: each step is keyed; WellSky / SES / Telnyx calls are idempotent + journaled, so retries never double-book or double-send.

5. Boundary, safety & governance (HIPAA)

In-boundary: Gemini via Vertex (BAA); PHI in Neon (RLS); retrieval in-zone. No agent I/O to Notion or any no-BAA surface (see HIPAA Compliance).
PHI-free telemetry: agent traces/logs carry opaque IDs only; full transcripts (if kept) live in Neon and are redacted in Cloud Logging. This keeps the observability plane on the PHI-free service list.
Tool-level authz = RLS + Cerbos — the agent can't touch what the acting identity can't. Cerbos supplies policy-as-code decisions (Query Plan → SQL filters) over the Neon RLS floor; each agent gets a least-privilege toolset.
Guardrails / eval: in/out PHI-leak filters on anything crossing a boundary; an eval harness (golden transcripts) gates prompt/tool changes; human-in-the-loop for high-stakes actions.
Auditability: the event log + the Restate journal together form a complete, replayable audit trail of every agent decision and action.

6. Open questions

These are unresolved and must not be treated as decided:

Agent abstraction on top of Restate — raw Gemini SDK (google-genai) + our own loop, or a thin framework (Pydantic AI / Google ADK) with Restate as the durable substrate? (Lean: thin — keep the loop ours.)
Orchestrator ↔ specialist boundary — sub-workflows vs Restate virtual objects per entity (prospect/client) that hold state and serialize concurrent actions? (Virtual objects look right for per-client serialization.)
HomeCareHQ — does it front the intake agent, or seed the funnel data model?
Eval + guardrail tooling — build vs OSS (promptfoo / DeepEval), run in-boundary.
Real-time voice onboarding (Gemini Live) — same orchestrator, streaming transport → see the Voice/VoIP deep dive and AI Tier.