Agentpakker

Hva det er

En agentpakke er et git-repo med KI-artefakter og en fil som beskriver dem. Ingenting skal registreres eller godkjennes. Et repo med et gyldig manifest er en agentpakke, og den som vil ha den, peker på repoet med --source.

Agentpakker er måten et team påvirker verktøykassa uten å bygge den selv. Sida går gjennom fire steg i rekkefølge: bruk en pakke som finnes, ta delene du trenger av den, bygg videre på den, og lag din egen først når ingenting av det holder. Skal du bare bruke Nav-innholdet, trenger du ikke denne sida: guidene for nav-pilot dekker installasjon og bruk.

Lager du en pakke selv, står alle felt og regler i referansen for agentpakker.

1. Bruk en som finnes

Det billigste steget er å installere en pakke noen alt vedlikeholder. nav-pilot finner ikke pakker for deg: install krever at du kjenner reponavnet, og det finnes ingen kommando som lister pakker. Lista under er ført for hånd.

Pakkene som finnes

De tre under validerer CI-en i navikt/copilot ved hver kontraktsendring. Slutter en pakke å følge kontrakten, feiler bygget vårt, så lista holdes kort. Den er en referanse for deg som skriver en pakke, ikke en anbefaling om hva du bør installere. Vil du ta i bruk en annen pakke enn nav-pilot, spør du teamet som eier den først.

nav-pilot install nav-pilot --source navikt/copilot --repo

Lås installasjonen

Installerer du i et repo, skriver install .nav-pilot/agentpakke.lock.json med kilden og revisjonen. Bruker-scope har ingen erklæring, for ~/.copilot er ikke et repo: der ligger revisjonen i din egen tilstandsfil, og gjelder bare deg. Commit erklæringa: da installerer hele teamet fra samme revisjon, og nav-pilot sync --apply flytter pinnen som én linje diff i en pull request.

I CI bruker du --frozen: den installerer nøyaktig det erklæringa sier, eller lar være. Den spør aldri og flytter aldri pinnen. Exit-koden skiller «pinnen er ikke det repoet sier» fra «installasjonen røk», se avslutningskodene.

- run: nav-pilot install nais-platform --frozen --force

2. Ta delene du trenger

Vil du ha fire av tolv agenter fra en plattformpakke, skal du slippe å forke den. items i erklæringa parer navn med artefakttype. Uten feltet installeres alt pakka har. Feltet skriver du selv: nav-pilot fyller det aldri ut. Hadde den ført opp alle tolv, ville hver ny agent oppstrøms blitt en merge-konflikt hos hver konsument.

{
  "contractVersion": "1",
  "source": "navikt/copilot",
  "sha": "b73a69e0000000000000000000000000000000aa",
  "items": {
    "nav-pilot": "agent",
    "klarsprak": "skill"
  }
}

Navnene sjekkes mot det pakka har. En skrivefeil stopper hele installasjonen. Du får ikke tre av fire uten beskjed.

items virker bare mot Tier 1. En Tier 1-pakke er filer som kan velges hver for seg. En Tier 2-pakke er payload-trær bundet til en digest, der revisjonen er enheten, ikke fila. items mot en Tier 2-pakke nektes, ikke ignoreres, og feilmeldinga ber deg fjerne blokka eller be pakka publisere en payload-kontekst med akkurat det teamet trenger.

3. Bygg videre på en

Vil du bygge på Nav-pakka i navikt/copilot uten å vedlikeholde en kopi av den, committer du den samme erklæringa i ditt eget pakkerepo. Repoet ditt har da både et manifest og en erklæring, og den som installerer pakka di får begge pakkenes innhold. Erklæringa løses på nytt ved hver install og sync.

{
  "contractVersion": "1",
  "source": "navikt/copilot",
  "sha": "b73a69e0000000000000000000000000000000aa"
}

sha er påkrevd for en kilde på formen owner/repo. Uten den ville gjenbruken hentet det main tilfeldigvis holdt, og to installasjoner en uke fra hverandre fått ulikt innhold. Installasjonen sier hva den gjenbrukte:

Source: navikt/ditt-repo@c3f7ca3
Reuses: navikt/copilot@b73a69e

Har begge pakkene et artefakt med samme navn, installeres ditt. Slik endrer du én ting i en pakke du ellers tar som den er. Hvordan pakkene settes sammen, og hvordan du holder basen oppdatert, står under Gjenbruk av en annen pakke.

4. Lag din egen

Skygging og items dekker de fleste grunnene folk har til å forke en pakke. Lag din egen når innholdet ikke finnes noe sted.

Struktur

Katalognavnene velger du selv. layout i manifestet peker på dem: heter katalogen innhold/agenter hos deg, skriver du det der. Filnavnene inne i katalogene er låst, se artefakttypene. Hver agentfil åpner med YAML-frontmatter som minst har name og description.

ditt-repo/
├── .nav-pilot/
│   └── agentpakke.json
├── agents/
│   └── grillmester.agent.md
└── skills/

Manifestet

Minste form som validerer. layout navngir katalogene pakka faktisk har, minst én av dem. primaryAgents er de agentene brukeren kan starte klienten som. Resten er subagenter andre kaller. Første navn startes som standard, og nav-pilot --persona <navn> velger et annet av dem. Hvert navn må ha en agentfil i layout.agents, ellers avviser validate og install manifestet.

{
  "contractVersion": "1",
  "name": "ditt-team",
  "description": "Hva pakka er til for",
  "layout": {
    "agents": "agents",
    "skills": "skills"
  },
  "clients": {
    "copilot": {
      "primaryAgents": ["grillmester"]
    }
  }
}

Resten av manifestet er valgfritt. Referansen beskriver hvert felt:

• Klientoppføringa: klienter, versjonsområder, standardmodell og minste nav-pilot-versjon.
• Hvilken tier du skal velge. Velg Tier 1 om du ikke har en grunn til noe annet.
• Pakke uten agent, for dere som bare deler skills eller instruksjoner.
• MCP-servere pakka forventer.
• Sandkassekonfigurasjon: unntak fra cplt som brukeren må godkjenne.
• Kjørbar kode og skript i en skill.

Valider

nav-pilot validate --source "$PWD"

Validating: /Users/deg/ditt-repo@c3f7ca3

  ℹ manifest: .nav-pilot/agentpakke.json
  ℹ agentpakke: ditt-team (contract version 1)
  ℹ clients: copilot (tier 1)

✓ /Users/deg/ditt-repo conforms to the agentpakke contract.

Bruk "$PWD", eller "$GITHUB_WORKSPACE" i CI. --source . avvises. Utelater du --source, validerer du Nav-pakka i stedet for din, og alt ser grønt ut. Advarsler (⚠) feiler ikke kommandoen. Mer om kilden og skjemaet står under Validering.

Distribuer

nav-pilot install ditt-team --source navikt/ditt-repo --repo

Det er hele distribusjonen. Den som installerer får .nav-pilot/agentpakke.lock.json i sitt eget repo, med kilden og revisjonen, og committer den. Da installerer hele teamet fra samme revisjon.

Vedlikehold

Konsumentene er pinnet til revisjonen de installerte. En endring du pusher, kommer fram først når de kjører nav-pilot sync --apply. Tre ting å vite før du endrer en pakke andre bruker:

• Endre ikke name i manifestet. Da blir eksisterende installasjoner en annen pakke.
• Vil du jobbe videre på main uten at alt går rett ut, publiserer du stabile releases.
• Sletter du et artefakt, fører du det opp i .nav-pilot/retired-artifacts.json, se Pensjonering.

Ressurser