# OSVauco — GCP Agent Master Repo

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).

---

## 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)
├── 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
├── 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
```

---

## 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 |
|---|---|
| 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.