{
  "markdown": "# HR Policy Agent Lab — RAG vs OKF\n\nBuild **one agent** — an HR Policy Assistant that answers employee questions\ngrounded in the *Altostrat Singapore Employee Policy Handbook* — and build its\n\"retrieval brain\" **two ways** so you feel the trade-off:\n\n- **Track A — RAG:** Google **Vertex AI Search** over the handbook (semantic search).\n- **Track B — OKF:** Google's **Open Knowledge Format** — a cross-linked markdown\n  bundle the agent *navigates deliberately* (no vector database).\n\nYou write the code by instructing **your AI coding agent** (`agy`).\nEvery exercise ships a hint and a suggested prompt to paste directly into your coding agent.\n\n---\n\n## The scenario (read this first)\n\n**The company.** Altostrat Singapore employs full-time staff, interns, and an\nextended workforce. All their rules live in one place: the **Altostrat Singapore\nEmployee Policy Handbook & Conduct Guidelines** — a **52-page PDF** (`data/handbook.pdf`)\ncovering leave, expenses, business courtesies, conduct, privacy, and more.\n\n**The problem.** Employees keep asking HR the same questions — *\"How much sick leave\ndo I get?\"*, *\"Can I expense this?\"*, *\"How many vacation days for a 12-hour shift?\"*\nHR is a bottleneck, answers come out inconsistent, and nobody reads a 52-page PDF.\nSome questions are even **traps**: a purchase *under* a dollar limit can still be\n**prohibited** (e.g. gift cards, adult entertainment). A confident-but-wrong answer\nis a compliance risk.\n\n**The ask (Project Elevate).** Ship a conversational **HR Policy Assistant** that\nanswers employee policy questions **accurately, grounded strictly in the handbook,\nwith citations** — and that **refuses** when the answer isn't in the handbook instead\nof guessing.\n\n### What the agent *is*\nA single, focused **ADK `LlmAgent`** (Gemini) for policy Q&A. Not a freeform chatbot:\nit uses **tools** to fetch the relevant policy, then answers from what it fetched.\n\n### What the agent *does*\n1. Takes an employee's natural-language question.\n2. **Retrieves** the relevant policy — via **RAG** or **OKF** (the two \"brains\" you build).\n3. Answers **only** from that policy, **cites** the source, and **declines**\n   out-of-domain or unanswerable questions.\n\n### What the policy handbook *does*\nIt is the agent's **single source of truth** (its \"grounding corpus\"). The agent may\nanswer *only* from it. In this lab the same handbook is given to the agent **two ways**:\na **Vertex AI Search** index (Track A / RAG) and an **OKF markdown bundle** in\n`knowledge/` (Track B).\n\n### Why this is the RAG-vs-OKF lesson\nAccurate, auditable Q&A over a big document is *exactly* the \"how does an agent know\nthe docs?\" problem. RAG and OKF are two answers — and this handbook, with its gotcha\nrules, is the perfect place to feel the difference.\n\n---\n\n## What you'll build\n\nThe agent is an ADK `LlmAgent` (Gemini). You implement the parts that make it an\nagent; the plumbing is given.\n\n| You write | What it does |\n|---|---|\n| `agent/tools/okf_tool.py` | `list_concepts` / `read_concept` — traverse the OKF bundle |\n| `agent/tools/rag_tool.py` | `search_policy_docs` — query Vertex AI Search |\n| `agent/prompt.py` | grounding + citation instructions |\n| `agent/agent.py` (one block) | construct the `LlmAgent` |\n\nGiven for you: the OKF `knowledge/` bundle, the handbook, the Vertex RAG scripts\n(`rag/`), the eval set (`evals/`), config, and the runner/CLI.\n\n---\n\n## The three layers (mental model)\n\n```\n  YOU  ──talk──▶  CODING AGENT  ──commands+skills──▶  agents-cli  ──▶  THE HR POLICY AGENT\n  (a human)       (AI pair programmer,                (a toolkit)       (ADK LlmAgent + Gemini,\n                   launched with `agy`)                                 the thing you build)\n```\n\n`agents-cli` is a toolkit that teaches your coding agent how to scaffold, run, evaluate, and deploy ADK agents on Google Cloud. Installing it is **encouraged, not required**:\n\n```bash\nuvx --python 3.11 google-agents-cli setup      # equips your coding agent with ADK skills\n# or install globally: uv tool install --python 3.11 google-agents-cli && agents-cli setup\n```\n\n---\n\n## Prerequisites & Setup\n\n- Python 3.11+ and [`uv`](https://docs.astral.sh/uv/) (`curl -LsSf https://astral.sh/uv/install.sh | sh`).\n- For **Track A (RAG)** only: a Google Cloud project with billing, Terraform ≥ 1.5, and `gcloud` (see `rag/README.md`).\n- Model access — choose **either** Google AI Studio (Gemini API key) **or** Vertex AI via Google Cloud. The Lab 2 judge uses the same auth.\n\n```bash\n# 1. Install dependencies\nuv sync\n\n# 2. Copy the environment configuration\ncp .env.example .env\n```\n\n### Choose your Model Authentication Path\n\n#### Path A: Gemini API Key (Google AI Studio)\nSimplest for local testing. Get a free API key at [aistudio.google.com/apikey](https://aistudio.google.com/apikey).\n\nIn `.env`, set:\n```bash\nGEMINI_API_KEY=your_gemini_api_key_here\n```\n\n#### Path B: Vertex AI (Google Cloud)\nUse Vertex AI with your Google Cloud project credentials.\n\n1. Log in with Google Cloud Application Default Credentials (ADC) and set your project:\n```bash\ngcloud auth application-default login\ngcloud config set project YOUR_PROJECT_ID\n```\n\n2. In `.env`, comment out `GEMINI_API_KEY` and configure the Vertex AI variables:\n```bash\nGOOGLE_GENAI_USE_VERTEXAI=true\nGOOGLE_CLOUD_PROJECT=your_gcp_project_id_here\nGOOGLE_CLOUD_LOCATION=global\n```\n\n> ⚠️ **Region & Model Disclaimer:** Depending on your Google Cloud project quota and the model tier you are using (e.g. preview models like `gemini-3.5-flash`), you should set `GOOGLE_CLOUD_LOCATION=global` (or your assigned regional location) to avoid `404 / Model Not Found` routing errors.\n\n---\n\n## Quickstart & Coding with Your AI Agent\n\n```bash\n# 1. Confirm the OKF knowledge bundle is well-formed\nuv run python knowledge/check_okf.py knowledge\n\n# 2. Confirm the scaffold imports and the retrieval mode\nuv run python -c \"import agent.config as c; print('mode:', c.RETRIEVAL_MODE)\"\n\n# 3. Launch your coding agent to start coding!\nagy\n```\n\nNow open **`LAB.md`**, copy the suggested prompts for each exercise, and paste them into **your coding agent** to implement your agent.\n\nWhen you've implemented the OKF tools + prompt + agent, test it three ways:\n\n- **A) Local Web UI Playground (Recommended):**\n  ```bash\n  agents-cli playground      # or: uv run adk web .\n  ```\n- **B) Interactive Terminal CLI:**\n  ```bash\n  uv run adk run agent \"How many days of bereavement leave do I get?\"\n  ```\n- **C) Standalone Python script:**\n  ```bash\n  RETRIEVAL_MODE=okf uv run python -m agent.agent \"How many days of bereavement leave do I get?\"\n  ```\n\n---\n\n## RAG vs OKF — the point of the lab\n\n| | RAG (Vertex AI Search) | OKF (Open Knowledge Format) |\n|---|---|---|\n| Retrieval | Semantic search returns top-k chunks | Agent reads `index.md`, navigates to the right concept, reads it |\n| Infra | GCP project, data store, ingest pipeline | None — plain `.md` files (\"if you can `cat` a file, you can read it\") |\n| Best for | Large, messy, unstructured corpora | Curated, structured, stable knowledge |\n| Updates | Re-ingest + re-index | Edit a markdown file, commit |\n| Auditability | Chunk provenance | Exact file + frontmatter `resource` + git history |\n| Gotcha handling | May retrieve a *related* chunk and miss the governing rule | Reads the whole governing concept, cross-links to prohibitions |\n\n> Observed in this lab's own RAG data store: asking *\"room salon under $100 — need\n> approval?\"* returned the **approval-thresholds** chunk but **missed** the\n> \"adult entertainment is prohibited\" chunk — exactly the kind of gap OKF's\n> deliberate navigation avoids. You'll see this yourself in Exercise 05.\n\n## Repo map\n\n```\nagent/         # the agent you build (scaffold with TODOs)\nknowledge/     # the OKF bundle (given, complete) + check_okf.py\nrag/           # Track A: terraform + ingest + verify (given)\ndata/          # handbook.pdf (source corpus)\nevals/         # policy_eval.json + run_eval.py + RUBRICS.md\nLAB.md         # Lab 1 — build the agent (exercises 00 -> 06)\nLAB_EVALS.md   # Lab 2 — evals & hillclimbing (measure & improve the agent)\n```\n\n## Two labs\n\n1. **`LAB.md` — Build the agent.** Implement the retrieval tools, prompt, and agent\n   (RAG and OKF).\n2. **`LAB_EVALS.md` — Evals & hillclimbing.** Measure the agent against a rubric,\n   read the scoreboard, and improve the score the honest way (see `evals/RUBRICS.md`).\n\nStart with **`LAB.md`**.\n",
  "bytes": 8421,
  "sha": "6d269fb81f8b860bcb84dc63eca188b79a3176e4b65ea7e8d39fc97c61d30eb4",
  "repo_slug": "tanyagoogle/elevate-hr-policy-agent",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_tanyagoogle_elevate_hr_policy_agent_know_ab479a70/readme"
}