# Bestille en kjøring Dette dokumentet er for deg som **bestiller** en kjøring — fagpersonen som vet hvilke tilnærminger det er verdt å prøve på et prosjekt, og som vil vite nøyaktig hva systemet skal gjøre før det gjør det. Søsterdokumentet [ekspert-svar.md](ekspert-svar.md) handler om det motsatte enden: å avgi dommen etterpå. > **Ærlighetsmerking.** Bestillingen styrer hva som **vurderes**. Den styrer aldri hva som > **godkjennes**. Den deterministiske validatoren gjelder uendret for en tilnærming du selv har bedt > om — ber du om noe tallene ikke bærer, blir det avvist, og avvisningen kommer tilbake til deg med > begrunnelsen. ## Oppdragsfila En bestilling er én JSON-fil. Du gir den til kjøringen med `--mandate`. ```json { "objective": "Kutt energikostnad i BYGG-KONTOR-NORD uten ombygging, med tiltak som kan gjennomføres i 2026.", "approaches": [ { "id": "led-retrofit", "label": "LED-retrofit av kontorbelysning", "description": "Drift mener armaturene er originale og har gått langt forbi oppgitt levetid." }, { "id": "driftsavtale", "label": "Reforhandling av driftsavtale", "description": "Avtalen er ikke justert siden 2019 og dekker areal vi ikke lenger disponerer." } ], "allow_own_proposals": true, "success_criteria": "Minst ett tiltak som passerer validatoren og som drift kan stå inne for." } ``` | Felt | Hva det gjør | |---|---| | `objective` | Hva kjøringen er til for, i klartekst. **Påkrevd** — en kjøring uten uttalt hensikt er nettopp det denne fila finnes for å hindre. | | `approaches` | Tilnærmingene du vil ha vurdert. Hver får sin egen vurdering og sin egen linje i oppgjøret. | | `allow_own_proposals` | `true` (standard): systemet foreslår også sitt eget, i tillegg til dine. `false`: kun dine. | | `success_criteria` | Hva du vil regne som vellykket. Gjengis ordrett i kunngjøringen; ingenting tolker den maskinelt. | **Om `id`:** den er nøkkelen tilnærmingen rapporteres under. To tilnærminger kan ikke dele `id` (da ville de kollapset til én linje i oppgjøret), og `own-proposal` er reservert for systemets eget forslag. **Om `description`:** den mates ordrett inn til modellen. Det er her fagkunnskapen din faktisk gjør en forskjell — *hvorfor* du tror tilnærmingen er verdt å prøve er nøyaktig det systemet ikke kan lese seg til av kostnadstallene. **Enten tilnærminger eller egne forslag.** En fil med tom `approaches` **og** `allow_own_proposals: false` blir avvist: da har kjøringen ingenting å gjøre. ## Å kjøre den ```bash uv run python -m portfolio_optimiser.run BYGG-KONTOR-NORD \ --docs-dir shared/examples/bygg-energi-mikro \ --bundle-dir shared/examples/bygg-energi-mikro \ --mandate oppdrag.json \ --scripted-replies replies.json ``` `--mandate` virker i begge moduser. I porteføljemodus (`--portfolio`) gjelder bestillingen **hvert** prosjekt i passet, og hvert prosjekt gjør opp for seg. **Vil du se hva kjøringen ville gjort, uten å bruke penger?** Legg til `--live-dry-run`. Da skrives kunngjøringen, og kjøringen stopper før første modellkall. **Fila leses strengt.** Mangler den, eller er den feilformet, blir kjøringen **nektet** (rc 1) — den går aldri videre på en halvlest bestilling. Det er med vilje: et oppgjør som beskriver arbeid ingen har bestilt, er verre enn ingen bestilling. ## Hva du får: kunngjøringen Før noe koster penger, skriver kjøringen hva den skal gjøre: ``` Run mandate for BYGG-KONTOR-NORD Objective: Kutt energikostnad i BYGG-KONTOR-NORD uten ombygging, ... Evaluates: 2 expert-proposed approach(es) + the system's own proposals 1. led-retrofit — LED-retrofit av kontorbelysning 2. driftsavtale — Reforhandling av driftsavtale Stops at: 3 rounds / 100000 tokens Contacts: no external services Success: Minst ett tiltak som passerer validatoren ... ``` Kjører du med `--dimension-config`, kommer det en `Scoped to:`-linje til. Linjer for ting kjøringen ikke har — avgrensning, tallmål — utelates i stedet for å stå tomme: en tom linje ville lest som en beslutning ingen har tatt. `Contacts` er egress-erklæringen: en kjøring når aldri en ekstern tjeneste den ikke har navngitt her. `Stops at` er takene — systemet kjører aldri en ubegrenset løkke. ## Hva du får: oppgjøret Etter kjøringen svarer den for bestillingen, én linje per tilnærming: ``` Mandate outcome led-retrofit VALIDATED 30000 NOK LED-retrofit av kontorbelysning driftsavtale REJECTED claimed 240000 exceeds feasible 90000 own-proposal NOT EVALUATED budget exhausted before this approach was evaluated Validated: 1 of 3 approaches — best 30000 NOK (the outcome this run carries) ``` De tre statusene betyr forskjellige ting, og forskjellen er poenget: - **VALIDATED** — tallene holdt. Beløpet er det validatoren slapp gjennom. - **REJECTED** — tilnærmingen ble vurdert, og falt på tallene. Grunnen står der; det er den du kan gjøre noe med (ofte er den «regnet mot feil grunnlag», ikke «dårlig idé»). - **NOT EVALUATED** — kjøringen rakk den aldri. Den er **ikke** avvist, og den er ikke glemt. En tilnærming du bestilte forsvinner aldri i stillhet. Det er hele grunnen til at oppgjøret finnes. **Tilnærmingene summeres ikke.** Flere av dem angriper som regel samme kostnadslinje, så de er alternativer — ikke besparelser som legges oppå hverandre. Derfor står det *hvor mange som holdt* og *hvilken kjøringen bærer videre*, aldri en sum. (Dette ble oppdaget ved å faktisk kjøre den: tre tilnærminger mot samme linje ga «totalt 90 000», som ingen av dem kunne innfri.) ## Hver tilnærming kan dømmes for seg Kjører du med `--outbox-dir` (og `--run-id`), legger kjøringen igjen **én artefakt per vurdert tilnærming** — `run-001-led-retrofit-proposal.json`, `run-001-driftsavtale-proposal.json`, og så videre — ikke bare for den kjøringen bar videre. Det er ikke en bokføringsdetalj. Uten det kunne bare den valgte tilnærmingen få en fagdom, og de andre du bestilte ville aldri nådd læringssløyfa: de ble vurdert, rapportert i oppgjøret, og deretter glemt. Nå står de hver for seg i køen din: ``` uv run python -m portfolio_optimiser.hitl pending --outbox-dir utboks --verdict-dir innboks run-001 c91cb2fe1aa139a9 validated [led-retrofit] run-001 4f0a1d77b2e5c318 rejected [driftsavtale] ``` Hvordan du svarer på dem står i [ekspert-svar.md](ekspert-svar.md). En tilnærming med status NOT EVALUATED har ingen artefakt — kjøringen produserte aldri et forslag for den, så det er ingenting å dømme. ## Hva bestillingen ikke gjør - **Den overstyrer ikke validatoren.** Se ærlighetsmerkingen øverst. - **Den avgjør ikke om et tiltak skal gjennomføres.** Det gjør et menneske, etterpå — se [ekspert-svar.md](ekspert-svar.md). - **Den setter ikke et tallmål.** Sparemålet har ett hjem, målkonfigurasjonen (`--goals`, som gjelder porteføljemodus). To kopier av samme tall drifter fra hverandre, så oppdraget bærer hensikten i ord og gjengir tallet hvis det finnes. - **Den lagrer seg ikke som kunnskap.** Bestillingen er en instruks for én kjøring. Det som lærer systemet noe, er dommen du avgir etterpå. ## Hvis kjøringen skal spørre en ekstern tjeneste Skal agentene kunne slå opp i en tjeneste dere allerede har — et prisregister, målerdata, et avtaleregister — settes den opp med `--mcp-config`: ```json {"servers": [ {"name": "prisregister", "transport": "http", "url": "https://intern.example/mcp", "allowed_tools": ["lookup_unit_price"], "timeout_seconds": 15, "credential_env": "PRISREGISTER_TOKEN"} ]} ``` Tre ting er verdt å vite som bestiller: - **Du må navngi hvilke verktøy som er tillatt.** Tom liste er ikke lov. Uten det ville tjenesten selv bestemt hva agentene får lov til å kalle. - **Alt som vil bli kontaktet, står i kunngjøringen** — før første kall, på `Contacts:`-linja, med både servernavn og tillatte verktøy. En kjøring når aldri en tjeneste den ikke har navngitt. Det gjelder også når du ikke bruker `--mandate`. - **Passord og nøkler skal aldri i fila.** `credential_env` navngir en miljøvariabel; verdien leses derfra. Er variabelen ikke satt, blir kjøringen nektet — heller det enn å ringe tjenesten anonymt og få svar med feil tilgang. Uten `--mcp-config` gjøres ingen nettverkskall i det hele tatt. ### Etterpå: hva ble faktisk kalt Kunngjøringen er en **tillatelse** — den sier hva kjøringen *kan* kontakte. Den sier ikke om agentene brukte tjenesten eller lot den ligge. Derfor fører kjøringen også et **kall-spor**, som følger med artefaktene under `provenance.external_calls`: ```json "external_calls": [{"server": "prisregister", "tool": "lookup_unit_price"}] ``` En tom liste er en påstand, ikke et hull: ingenting utenfor prosessen ble kontaktet. Verktøy som kjører lokalt (som dokumentsøket) telles ikke med — de er ikke kontakt med noen. **Hva sporet ikke sier.** Det viser at verktøyet ble kalt, og hvilken server det tilhører. Det er ikke bevis for at tjenestens svar er det tallet som havnet i forslaget, og det er ingen kontrollert gjengivelse av hva tjenesten svarte. Skal svaret etterprøves, må det gjøres mot tjenesten selv. En sjelden detalj, tatt med fordi den ellers ville sett ut som en feil: hvis to servere tilbyr verktøy med **samme navn**, står `server` tomt. Rammeverket oppgir bare verktøynavnet, så de to lar seg ikke skille — og da er «vet ikke» riktigere enn å gjette på den ene.