👔 Long Running AI Agent Team for New Hire Onboarding
This HR New Hire Onboarding Coordinator Agent demonstrates key principles for architecting agents to handle time-agnostic, multi-day workflows. The project contains a ReAct agent powered by Gemini Flash-Lite and built on top of the Google Agent Development Kit (ADK). The agent guides new hires through a structured onboarding state machine and includes a polished live demo UI for showing pause/resume behavior outside the raw ADK web console.
📖 Overview
Most chatbot tutorials rely on dumping massive conversation history JSON blobs into a vector database to “remember” past turns. However, over multi-day workflows, this unstructured approach introduces severe prompt context pollution, high token costs, and reasoning hallucinations.
To build reliable background agents, we design a durable, lightweight agent memory schema. By grounding the Onboarding Coordinator Agent in a strict enum-based state machine, we guarantee the agent maintains its logical reasoning chain across weeks of delay, without relying on raw chat logs. The coordinator coordinates human-in-the-loop task progression and automated system provisioning, ensuring that every onboarding step is completed in order and preventing checkpoints from being bypassed.
🖥️ Live Onboarding Demo
The repository now includes a production-style React demo served by FastAPI at:
http://127.0.0.1:8000/live-onboarding/
The demo is intentionally built as a two-sided onboarding cockpit:
HR command center: shows backend case state, ADK activity, state-machine progress, local artifacts, and event history.
Employee portal: lets the employee inspect the generated packet, sign it, confirm laptop delivery, and view the resulting artifacts.
The important demo behavior is honest:
The UI does not optimistically advance the workflow.
Clicking Sign packet waits for the backend ADK resume turn to complete before the signed packet/state appears.
Clicking Confirm laptop delivered waits for the hardware ADK resume turn to complete.
After hardware completion, the employee portal shows the Hardware delivery receipt first, then automatically transitions to the Day One schedule.
Local HTML artifacts are real files generated by the FastAPI backend and served through /api/live-onboarding/cases/{case_id}/artifacts/{artifact_id}.
This keeps the app demo-friendly while still proving the long-running ADK pattern: the agent pauses at external events, resumes from webhook-like actions, and only moves forward when the backend state has actually changed.
Demo Flow
Start a fresh case.
Review the unsigned onboarding packet.
Click Sign packet.
Wait for the ADK signature resume to finish.
Review the signed packet.
Click Confirm laptop delivered.
Wait for the ADK hardware resume to finish.
See the hardware receipt, then the Day One schedule.
Run the Live Demo Locally
Authenticate with Google Cloud Application Default Credentials first:
gcloud auth application-default logingcloud config set project <your-project-id>
Install and run the FastAPI app:
uv syncuv run uvicorn app.fast_api_app:app --host 127.0.0.1 --port 8000
Then open:
http://127.0.0.1:8000/live-onboarding/
If you change the React frontend, rebuild the static assets:
cd frontend/live-onboardingnpm installnpm run build
The build writes directly into app/static/live-onboarding, which is what FastAPI serves.
🔄 Core Design Patterns: Architecting for Time
To transition from building stateless chatbots to reliable background agents, this repository demonstrates three architectural paradigm shifts:
Stateless Chatbot Pattern
Durable Background Agent Pattern (This Repo)
Why It Matters
Stateless memory (dumps raw JSON logs or chat histories into vector DBs).
Durable memory schema (grounded enums serialized to SQLite/Cloud SQL).
Eliminates prompt context pollution, token bloat, and reasoning hallucinations over multi-week wait times.
Active polling / blocked threads (keeps loops running or actively polls APIs).
Event-driven dormancy gates (dormant scale-to-zero wait state resumed via webhooks).
Conserves compute resources; agent sleep state persists durably at rest until external events trigger wake-up.
Monolithic single-agent (all tools stuffed into one system instruction).
Multi-agent delegation (HR coordinator delegates IT setups to specialized subagents).
Decouples complex workflows, keeps prompts targeted, and preserves the logical reasoning chain.
🔄 Onboarding State Machine & Idle Time Pause Gates
This coordinator does not run in a single thread or block execution. It employs durable dormancy gates during long periods of “Idle Time”—specifically when waiting for signatures or shipping delivery carrier callbacks.
stateDiagram-v2
[*] --> START : Initialize details
START --> WELCOME_SENT : send_welcome_packet()
state "WELCOME_SENT" as WELCOME_SENT
note right of WELCOME_SENT
⏳ IDLE TIME PAUSE (Days)
Waiting for local signature webhook callback.
Container scales down; state persisted.
end note
WELCOME_SENT --> DOCUMENTS_SIGNED : Webhook Resume Callback
DOCUMENTS_SIGNED --> IT_PROVISIONED : provision_software_accounts()
state "IT_PROVISIONED" as IT_PROVISIONED
note right of IT_PROVISIONED
⏳ IDLE TIME PAUSE (Days)
Waiting for carrier package delivery webhook.
Container scales down; state persisted.
end note
IT_PROVISIONED --> HARDWARE_DELIVERED : Webhook Resume Callback
HARDWARE_DELIVERED --> COMPLETED : send_day_one_schedule()
COMPLETED --> [*] : Onboarding Completed
🏗️ Project Structure
A clear understanding of the workspace layout and files:
new-hire-onboarding/
├── app/ # Core Agent Application
│ ├── agent.py # Main agent logic, model config, & system prompt
│ ├── tools.py # Automated tools (emails, IT provisioning, hardware tracking)
│ ├── state_schema.py # OnboardingStep enum definition
│ ├── resume_handler.py # Callback webhooks to transition states (signatures, delivery)
│ ├── live_onboarding.py # Live demo case state, local artifact generation, and API helpers
│ ├── fast_api_app.py # FastAPI server exposing agent and custom endpoints
│ ├── agent_runtime_app.py # Dedicated Reasoning Engine App wrapper for Agent Runtime
│ ├── static/live-onboarding/ # Built React app served by FastAPI
│ └── app_utils/ # Shared utilities (telemetry, feedback typing)
├── frontend/live-onboarding/ # React + Vite source for the live onboarding UI
├── tests/ # Test Suites
│ ├── unit/ # Basic unit and logic tests
│ ├── integration/ # Local stream and E2E FastAPI server tests
│ └── eval/ # Performance evaluations using Golden Sets
├── pyproject.toml # Poetry/uv project description & dependencies
└── GEMINI.md # AI-assisted development instruction playbook
agents-cli(https://google.github.io/agents-cli/): The official command-line interface for the Gemini Enterprise Agent Platform. It manages project scaffolding, local interactive playgrounds (agents-cli playground), golden evaluations, and reasoning engine deployments. Install it globally using:
uv tool install google-agents-cli
Google Cloud SDK: Authenticated to Google Cloud — Install Gcloud
🛠️ Local Development Commands
Command
Purpose
agents-cli install
Installs the project dependencies via uv
agents-cli playground
Runs the agent in an interactive local chat sandbox
uv run uvicorn app.fast_api_app:app --host 127.0.0.1 --port 8000
Runs the FastAPI app and live onboarding UI
cd frontend/live-onboarding && npm run build
Builds the React UI into app/static/live-onboarding
agents-cli lint
Validates code structure and checks styling formatting
uv run pytest tests/unit
Runs deterministic live onboarding state and artifact tests
uv run pytest tests/integration
Runs streaming integration tests & E2E fastapi server validations
.venv/bin/adk eval ./app <evalset.json>
Runs direct local python evaluation runner bypassing system package registries
📊 Evaluation & Validation Loop
The agent’s state machine transitions are validated using formal golden evaluation sets:
Deploy to Agent Runtime:
This project’s deployment target is scaffolded and pre-configured for Agent Runtime (Agent Engines):
agents-cli deploy
Agent Runtime automatically hosts the server, manages persistent sessions out-of-the-box, and natively integrates trace spans with Cloud Trace for real-time ambient monitoring.
Enhance Project Infrastructure:
To add CI/CD runners (GitHub Actions/Cloud Build) or adapt configurations:
agents-cli scaffold enhance
📡 Observability
This agent includes built-in telemetry pre-configured in telemetry.py. It leverages OpenTelemetry to export trace spans, API logs, and model execution metadata directly to Cloud Trace, Cloud Logging, and BigQuery.
