docs: oppdater README, IAM-docs, legg til rag/memory/eval mapper og cost-guard

This commit is contained in:
Chris Christiansen 2026-05-23 20:54:05 +00:00
parent 9b806caed4
commit 69eab2c113
8 changed files with 387 additions and 205 deletions

163
README.md
View File

@ -1,139 +1,50 @@
# OSVauco — GCP Agent Master Repo
Prosjekt: `propane-will-491900-m5` | Region: `us-central1`
**Prosjekt:** `propane-will-491900-m5` | **Region:** `us-central1`
Repository for ADK 2.0-baserte agenter på Gemini Enterprise Agent Platform (tidl. Vertex AI Agent Engine).
## Status
| Komponent | Status |
|---|---|
| Cloud Run Agent | ✅ Live |
| Service URL | https://osvauco-agent-357036551735.us-central1.run.app |
| CI/CD Trigger | ✅ Auto-deploy ved push til `main` |
| ADK Versjon | 1.x (google-adk>=1.0.0,<2.0.0) |
| Siste revisjon | osvauco-agent-00006-mvb |
---
## Hurtigtest
```bash
TOKEN=$(gcloud auth print-identity-token)
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"user_id":"chris","session_id":"test-1","message":"Hei, hvem er du?"}' \
https://osvauco-agent-357036551735.us-central1.run.app/run | jq
```
## Repo-struktur
```
├── agents/
│ ├── core-logic/ # Hoved-agent: agent.py, __init__.py, deploy_agent.py
│ │ ├── requirements.txt # Pinnede avhengigheter
│ │ ├── Dockerfile # Cloud Run containerisering
│ │ └── .env.example # Lokal dev — kopier til .env
│ ├── multi_agent/ # Orchestrator + sub-agents
│ ├── tools/ # MCP-integrasjoner (BigQuery, Maps)
│ ├── rag/ # RAG corpus setup
│ ├── memory/ # Memory Bank + Sessions setup
│ ├── eval/ # CI/CD eval-gate (groundedness ≥ 0.8)
│ └── tests/ # Lokal test-runner (ADK dev server)
│ └── core-logic/ # Live agent: app.py (FastAPI + ADK Runner)
├── infrastructure/
│ ├── 00-authcheck.sh # Verifiser gcloud-identitet og prosjekt
│ ├── 01-setupenv.sh # APIs, bucket, lifecycle, SA, IAM, billing budget
│ ├── 02-deploy.sh # Deploy til Agent Runtime (ADK Python SDK)
│ ├── 03-teardown.sh # Slett Agent Runtimes + cleanup (kostnadsbeskyttelse)
│ ├── 04-observability-setup.sh # Monitoring, Logging, Trace APIs
│ ├── 05-cloudrun-deploy.sh # Deploy til Cloud Run via `adk deploy cloud_run`
│ ├── 06-cicd-setup.sh # Cloud Build trigger + Artifact Registry
│ ├── 07-rag-setup.sh # RAG corpus create + import wrapper
│ └── 08-memorybank-setup.sh # Memory Bank instance + IAM
│ ├── 01-setupenv.sh # ✅ Ferdig
│ ├── 05-cloudrun-deploy.sh # ✅ Ferdig
│ ├── 06-cicd-setup.sh # ✅ Ferdig
│ ├── 07-rag-setup.sh # ⏳ Neste
│ └── 08-memorybank-setup.sh # ⏳ Planlagt
├── docs/
│ ├── GCPBestPractices.md # Platform, ADK 2.0, deploy targets, modeller
│ ├── CostManagementRules.md # Priser, lifecycle-regler, teardown-policy
│ └── IAMRolesandPermissions.md # Roller, SA, ADC, Agent Identity
├── architecture/
│ ├── agentworkflowdiagrams.md # Mermaid-diagrammer: deploy, multi-agent, CI/CD
│ └── dataflowsecurity.md # Auth, secrets, guardrails, Agent Gateway
├── cloudbuild.yaml # CI/CD pipeline
└── README.md
├── scripts/
├── cloudbuild.yaml # CI/CD pipeline
└── .env.example
```
---
## Dag-1 oppsett
### Forutsetninger
- `gcloud` CLI installert og logget inn
- Python 3.12+
- Docker (for Cloud Run deploys)
### Steg 1 — Auth
```bash
gcloud auth login
gcloud auth application-default login
gcloud config set project propane-will-491900-m5
```
### Steg 2 — Environment setup
```bash
bash infrastructure/01-setupenv.sh
# Følg instruksjonene om billing budget (krever billing account ID)
# Finn med: gcloud billing accounts list
```
### Steg 3 — Lokal kjøring
```bash
cd agents/core-logic
cp .env.example .env # fyll inn variabler
pip install -r requirements.txt
adk web . # åpner dev UI på http://localhost:8080
```
### Steg 4 — Deploy til Cloud Run
```bash
bash infrastructure/05-cloudrun-deploy.sh
```
### Steg 5 — Deploy til Agent Runtime (managed)
```bash
bash infrastructure/02-deploy.sh
# HUSK: Kjør teardown på slutten av dagen!
bash infrastructure/03-teardown.sh
```
---
## Hurtigreferanse-kommandoer
| Handling | Kommando |
## Service Account roller (`osvauco-agent-sa`)
| Rolle | Formål |
|---|---|
| Auth check | `bash infrastructure/00-authcheck.sh` |
| Setup env | `bash infrastructure/01-setupenv.sh` |
| Deploy Agent Runtime | `bash infrastructure/02-deploy.sh` |
| **Teardown (viktig!)** | `bash infrastructure/03-teardown.sh` |
| Deploy Cloud Run | `bash infrastructure/05-cloudrun-deploy.sh` |
| Setup RAG corpus | `python agents/rag/setup_corpus.py` |
| Setup Memory Bank | `python agents/memory/memory_setup.py` |
| Kjør eval | `python agents/eval/run_eval.py` |
| Lokal test | `bash agents/tests/test_local.sh` |
| Finn billing account | `gcloud billing accounts list` |
| Liste aktive Cloud Run services | `gcloud run services list --region=us-central1` |
| Slett Cloud Run service | `gcloud run services delete oavauco-agent-v1 --region=us-central1` |
---
## Kostnadsbeskyttelse — viktigste regler
1. **Kjør alltid `03-teardown.sh` på slutten av arbeidsdagen** — Agent Runtimes faktureres.
2. Sett billing budget alert før første deploy (`01-setupenv.sh` har stub for dette).
3. Cloud Run skalerer til 0 — ingen idle-kost med `--min-instances=0`.
4. RAG Engine med Spanner → 24/7 fakturering. Bruk `us-east1` for dev/test.
5. Sessions, Memory Bank og Code Execution er metered fra 28. jan 2026.
---
## CI/CD
`cloudbuild.yaml` kjøres automatisk ved push til `main`:
1. Install dependencies + unit tests
2. Eval gate (groundedness ≥ 0.8 — feiler bygget ellers)
3. Build Docker image
4. Push til Artifact Registry
5. Deploy til Cloud Run
Oppsett: `bash infrastructure/06-cicd-setup.sh`
(Krever at GitHub-repo er koblet til Cloud Build via GCP Console først.)
---
## Sikkerhetsregler
- Ingen JSON-nøkkelfiler i repo — bruk ADC / Workload Identity.
- Alle hemmeligheter i Secret Manager (`gcloud secrets create ...`).
- `.env` er i `.gitignore` — aldri commit.
- Cloud Run kjører med `--no-allow-unauthenticated`.
- ADK-callbacks blokkerer prompt injection og destruktive tool-args.
# CI/CD test Sat May 23 08:22:39 PM UTC 2026
| roles/aiplatform.user | Vertex AI / Gemini |
| roles/secretmanager.secretAccessor | Secrets |
| roles/logging.logWriter | Logging |
| roles/cloudtrace.agent | Tracing |
| roles/monitoring.metricWriter | Monitoring |
| roles/run.invoker | Cloud Run kall |
| roles/iam.serviceAccountUser | Deploy |
| roles/artifactregistry.writer | Docker push |
| roles/run.developer | Cloud Run deploy |

0
agents/eval/.gitkeep Normal file
View File

0
agents/memory/.gitkeep Normal file
View File

0
agents/rag/.gitkeep Normal file
View File

View File

@ -1,82 +1,20 @@
# IAM Roles and Permissions — propane-will-491900-m5
# IAM Roles osvauco-agent-sa
## Service account: vertex-agent-sa
Minimum roles required:
| Role | Purpose |
|---|---|
| `roles/aiplatform.user` | Deploy/query agents on Gemini Agent Platform |
| `roles/storage.objectAdmin` | Read/write staging bucket |
| `roles/logging.logWriter` | Write agent logs to Cloud Logging |
| `roles/iam.serviceAccountTokenCreator` | Allow ADK to use the SA |
| `roles/secretmanager.secretAccessor` | Read secrets at runtime |
| `roles/run.invoker` | Call Cloud Run services |
| `roles/cloudtrace.agent` | Write traces to Cloud Trace |
| `roles/artifactregistry.writer` | Push container images (CI/CD) |
**Service Account:** `osvauco-agent-sa@propane-will-491900-m5.iam.gserviceaccount.com`
## Create SA (idempotent)
```bash
SA_NAME="vertex-agent-sa"
SA_EMAIL="${SA_NAME}@propane-will-491900-m5.iam.gserviceaccount.com"
## Tildelte roller
| Rolle | Tildelt | Formål |
|---|---|---|
| roles/aiplatform.user | 23.05.2026 | Vertex AI / Gemini API-kall |
| roles/secretmanager.secretAccessor | 23.05.2026 | Lese hemmeligheter fra Secret Manager |
| roles/logging.logWriter | 23.05.2026 | Skrive til Cloud Logging |
| roles/cloudtrace.agent | 23.05.2026 | Distribuert sporing |
| roles/monitoring.metricWriter | 23.05.2026 | Skrive metrics |
| roles/run.invoker | 23.05.2026 | Motta HTTP-kall på Cloud Run |
| roles/iam.serviceAccountUser | 23.05.2026 | Brukes av deployer (chris.christiansen@vauco.no) |
| roles/artifactregistry.writer | 23.05.2026 | Pushe Docker-images til Artifact Registry |
| roles/run.developer | 23.05.2026 | Deploye revisjoner til Cloud Run |
if ! gcloud iam service-accounts describe "$SA_EMAIL" \
--project=propane-will-491900-m5 &>/dev/null 2>&1; then
gcloud iam service-accounts create "$SA_NAME" \
--display-name="Vertex Agent SA" \
--project=propane-will-491900-m5
fi
for ROLE in \
roles/aiplatform.user \
roles/storage.objectAdmin \
roles/logging.logWriter \
roles/iam.serviceAccountTokenCreator \
roles/secretmanager.secretAccessor \
roles/run.invoker \
roles/cloudtrace.agent \
roles/artifactregistry.writer; do
gcloud projects add-iam-policy-binding propane-will-491900-m5 \
--member="serviceAccount:${SA_EMAIL}" \
--role="$ROLE" --quiet
done
```
**Do NOT download a JSON key file** — use Workload Identity or ADC (`gcloud auth application-default login`) instead.
## MCP Tool User role (new — 2026)
Required when using Google's managed MCP servers (BigQuery, Maps, etc.):
```bash
gcloud projects add-iam-policy-binding propane-will-491900-m5 \
--member="user:YOUR_EMAIL" \
--role="roles/mcp.toolUser"
```
## Authentication decision tree
```
Running locally in VS Code?
YES → gcloud auth application-default login
File: $HOME/.config/gcloud/application_default_credentials.json
Running on Cloud Run?
YES → Attach service account to service (no key file)
gcloud run services update SERVICE --service-account=SA_EMAIL
Running on GKE?
YES → Use Workload Identity Federation (keyless)
gcloud container clusters update CLUSTER --workload-pool=PROJECT.svc.id.goog
NEVER use:
× gcloud auth activate-service-account (static credentials)
× Exporting JSON key files to repo or environment variables
```
## ADC credential search order
1. `GOOGLE_APPLICATION_CREDENTIALS` env var (service account JSON path)
2. `~/.config/gcloud/application_default_credentials.json`
3. Attached service account from metadata server (Cloud Run, GCE, GKE)
**Best practice**: Never set `GOOGLE_APPLICATION_CREDENTIALS` in production. Let the metadata server handle it.
## Agent Identity (governance layer — 2026)
- Every deployed agent should have its own dedicated service account (Agent Identity).
- Naming convention: `agent-{name}-sa@propane-will-491900-m5.iam.gserviceaccount.com`
- Register in Agent Registry so all autonomous actions are traceable.
## Prinsipp: Minste privilegium
SA-en har kun roller som kreves for drift og CI/CD.
Ingen owner/editor-roller er tildelt.

View File

@ -80,3 +80,325 @@ PHASE 5 -- IAP paa opax.vauco.no: begrens tilgang til @vauco.no Google-kontoer k
## NESTE OPPGAVE
PHASE 5 -- IAP paa opax.vauco.no: begrens tilgang til @vauco.no Google-kontoer kun. HITL gate: DEPLOY GODKJENT.
---
## Session: 20260523-054807
- Tid : 2026-05-23 05:50 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-055359
- Tid : 2026-05-23 05:54 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : Exec Phase A+B
---
## Session: 20260523-055906
- Tid : 2026-05-23 05:59 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : her
---
## Session: 20260523-061624
- Tid : 2026-05-23 06:16 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : fase a+b
---
## Session: 20260523-135706
- Tid : 2026-05-23 13:57 UTC
- Bruker : ukjent
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-135706
- Tid : 2026-05-23 13:57 UTC
- Bruker : ukjent
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-135710
- Tid : 2026-05-23 13:57 UTC
- Bruker : ukjent
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-135747
- Tid : 2026-05-23 13:57 UTC
- Bruker : ukjent
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-135751
- Tid : 2026-05-23 13:57 UTC
- Bruker : ukjent
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-135756
- Tid : 2026-05-23 13:57 UTC
- Bruker : ukjent
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-135800
- Tid : 2026-05-23 13:58 UTC
- Bruker : ukjent
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-135805
- Tid : 2026-05-23 13:58 UTC
- Bruker : ukjent
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-135809
- Tid : 2026-05-23 13:58 UTC
- Bruker : ukjent
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-135814
- Tid : 2026-05-23 13:58 UTC
- Bruker : ukjent
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-135819
- Tid : 2026-05-23 13:58 UTC
- Bruker : ukjent
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-135823
- Tid : 2026-05-23 13:58 UTC
- Bruker : ukjent
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-135710
- Tid : 2026-05-23 14:16 UTC
- Bruker : ukjent
- OPAX : NEDE
- Mål : fase a+b
---
## Session: 20260523-141745
- Tid : 2026-05-23 14:17 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-141751
- Tid : 2026-05-23 14:17 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-141756
- Tid : 2026-05-23 14:18 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-141802
- Tid : 2026-05-23 14:18 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-141807
- Tid : 2026-05-23 14:18 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-141813
- Tid : 2026-05-23 14:18 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-141819
- Tid : 2026-05-23 14:18 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-141824
- Tid : 2026-05-23 14:18 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-141830
- Tid : 2026-05-23 14:18 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-141835
- Tid : 2026-05-23 14:18 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-152725
- Tid : 2026-05-23 15:27 UTC
- Bruker : ukjent
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-152725
- Tid : 2026-05-23 15:27 UTC
- Bruker : ukjent
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-152731
- Tid : 2026-05-23 15:30 UTC
- Bruker : ukjent
- OPAX : NEDE
- Mål : fullførelse av fase abc
---
## Session: 20260523-170425
- Tid : 2026-05-23 17:04 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-170425
- Tid : 2026-05-23 17:04 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-170430
- Tid : 2026-05-23 17:04 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : Phaze abc
---
## Session: 20260523-171956
- Tid : 2026-05-23 17:21 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : ABC
---
## Session: 20260523-174538
- Tid : 2026-05-23 17:45 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-200030
- Tid : 2026-05-23 20:00 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-200036
- Tid : 2026-05-23 20:00 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-200042
- Tid : 2026-05-23 20:00 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-200049
- Tid : 2026-05-23 20:00 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-200055
- Tid : 2026-05-23 20:00 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-200101
- Tid : 2026-05-23 20:01 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-200108
- Tid : 2026-05-23 20:01 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-200102
- Tid : 2026-05-23 20:01 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : abc
---
## Session: 20260523-200114
- Tid : 2026-05-23 20:01 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-200120
- Tid : 2026-05-23 20:01 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)
---
## Session: 20260523-200126
- Tid : 2026-05-23 20:01 UTC
- Bruker : chris.christiansen@vauco.no
- OPAX : NEDE
- Mål : (ingen beskrivelse)

11
scripts/cost-guard.sh Executable file
View File

@ -0,0 +1,11 @@
#!/bin/bash
# cost-guard.sh — Sjekk GCP-kostnader for propane-will-491900-m5
PROJECT="propane-will-491900-m5"
echo "=== Cost Guard ==="
gcloud billing budgets list \
--billing-account=$(gcloud billing accounts list --format='value(name)' | head -1) \
--format='table(displayName,amount.specifiedAmount.units,thresholdRules)'
echo ""
echo "=== Cloud Run metrics ==="
gcloud run services list --project=$PROJECT --region=us-central1 \
--format='table(SERVICE,REGION,LAST_DEPLOYED_AT)'

0
scripts/osvauco-opax-boot.sh Normal file → Executable file
View File