Een bundel uitbrengen met het artific-commando¶

Het concept achter publicaties staat in Delen en hergebruik.

artific is een commando waarmee je een bundel uitbrengt die als bestanden bestaat. De prompts, agents, toolsets en andere onderdelen van een bundel staan in een map die je in git bijhoudt, en het commando controleert die map bij Core, probeert hem uit in een testorganisatie, publiceert hem als nieuwe versie en stuurt hem in voor de marktplaats. Het gebruikt dezelfde routes als Publiceren en installeren via de API, dus wat het publiceert is een gewone publicatie: abonnees installeren en synchroniseren hem precies zoals een publicatie uit de console.

Gebruik het als een bundel via pull requests verandert, of als een pipeline hem moet publiceren. Voor een bundel die je met de hand samenstelt en publiceert, is de console de kortere weg.

publish, try en submit kun je veilig herhalen: ze schrijven alleen wat afwijkt van wat Core heeft, en een tweede run op een ongewijzigd project schrijft niets en meldt dat.

Wat je nodig hebt¶

• Een sleutel van de organisatie die publiceert, met management. Het commando handelt namens die organisatie en voor geen enkele andere. Organisaties beheren via de API laat zien hoe je die capability aanzet; Sleutels en policy in de console laat zien hoe je een sleutel aanmaakt en de secret bewaart.
• Het adres van je Core, zoals https://core.example.com.

Meer niet. Je eigen Core-sleutel, als ARTIFIC_API_KEY, met het adres van je Core, als ARTIFIC_ENDPOINT, is het enige inloggegeven dat het commando en zijn GitHub Action ooit nodig hebben. Je hebt geen GitHub-account, token of toegang tot een repository van Artific nodig: de downloads en de action zijn openbaar. Het token dat de releaseworkflow van Artific zelf gebruikt, is alleen van Artific; het publiceert alleen nieuwe versies van het commando en maak je nooit zelf aan.

Het commando installeren¶

Elke release van het commando is een GitHub-release van de openbare repository artific-ai/artific-cli met de tag v<versie>, zoals v0.1.0. Die bevat één archief per systeem en een bestand SHA256SUMS met de controlesom van elk archief. Een archief bevat alleen het programma artific. Je hebt er geen account of token voor nodig.

De Linux-versies zijn statisch gebouwd en draaien dus op elke distributie en in elke container. Er is geen versie voor Windows.

Zo installeer je er een:

1. Download het archief voor je systeem en de controlesommen. Op een Mac met Apple silicon:

   VERSION=0.1.0
   ARCHIVE=artific-$VERSION-aarch64-apple-darwin.tar.gz
   BASE=https://github.com/artific-ai/artific-cli/releases/download/v$VERSION
   curl -fLO "$BASE/$ARCHIVE"
   curl -fLO "$BASE/SHA256SUMS"
   

2. Controleer het archief met SHA256SUMS. Het commando meldt <archief>: OK; meldt het iets anders, dan is de download niet het uitgebrachte bestand: verwijder hem en pak hem niet uit.

   grep " $ARCHIVE\$" SHA256SUMS | shasum -a 256 -c
   

   Op Linux doet sha256sum -c hetzelfde als shasum -a 256 -c.

3. Pak het programma uit en zet het in een map op je PATH waarin je mag schrijven. Voor /usr/local/bin heb je vaak sudo nodig:

   tar -xzf "$ARCHIVE" artific
   sudo mv artific /usr/local/bin/
   artific --version
   

Noem altijd een exacte versie: de naam van het archief bevat haar, en er is geen "nieuwste". Een uitgebrachte versie verandert nooit meer; een fout wordt hersteld in een volgende versie.

Het commando op Core richten¶

Elke stap behalve artific build leest twee omgevingsvariabelen:

export ARTIFIC_ENDPOINT=https://core.example.com
export ARTIFIC_API_KEY=ack_...

ARTIFIC_ENDPOINT is het adres van je Core zonder /api/v1: het commando zet het pad van elke route er zelf achter. Dat is anders dan de CORE_URL op de andere pagina's van deze gids.

Het adres moet met https:// beginnen, zodat de sleutel nooit onversleuteld over het netwerk gaat; http:// mag alleen voor localhost, 127.0.0.1 en [::1]. De sleutel gaat alleen mee in de header Authorization, en niets wat het commando toont bevat hem. Ontbreekt een variabele, dan stopt het commando met artific: ARTIFIC_ENDPOINT is not set (of ARTIFIC_API_KEY).

Het project indelen¶

Een bundel is een map. Lange tekst staat in een eigen bestand, zodat een pull request een gewijzigde prompt als tekstverschil laat zien:

support-desk/
  artific.yaml                  de bundel: naam, omschrijving, zichtbaarheid, voorwaarden, parameters
  members/
    prompt/triage.yaml          één onderdeel per bestand: de soort is de map, de naam het bestand
    prompt/triage.template.md   tekst die triage.yaml met !file invoegt
    agent/desk.yaml
    toolset/desk-tools.yaml
    script/house_deck.yaml      een script
    script/house_deck/          de bestanden van dat script
  packages/
    deckkit-1.0.0-py3-none-any.whl   een pakketbestand dat een script meeneemt
  covers/
    listing.png                 de afbeelding op de kaart in de catalogus
    agent/desk.png              de afbeelding van één onderdeel
  CHANGELOG.md                  het bovenste deel wordt het versieverslag

De snelste weg naar een correct project: stel de bundel één keer samen in de console, publiceer een versie en haal die op. Het commando schrijft die versie als map in precies deze vorm, en daar ga je mee verder.

Het bundelbestand¶

artific.yaml beschrijft de publicatie en de delen van de bundel die bij geen enkel onderdeel horen:

name: support-desk
description: Supporttickets sorteren en beantwoorden.
visibility: subtree
terms:
  fork: false
parameters:
  company:
    type: string
    description: De bedrijfsnaam die de agent in zijn antwoorden gebruikt.

visibility, targets en auto_install gelden vanaf het moment dat het commando de publicatie aanmaakt. Daarna blijven de naam en de zichtbaarheid van een publicatie zoals ze zijn.

Onderdelen¶

Elk bestand onder members/<soort>/ is één onderdeel: de soort is de map (prompt, agent, toolset, script, …), de naam is de bestandsnaam zonder .yaml, en de inhoud is de definitie van het onderdeel. Een onderdeel verwijst naar een ander onderdeel van de bundel als {$member: <naam>}, en naar een parameter als {$param: <naam>}. Een onderdeel dat alleen bij een bepaalde keuze van de installeerder meegaat, zet die voorwaarde onder $when.

# members/prompt/triage.yaml
description: Sorteert een binnenkomend ticket.
template: !file triage.template.md

!file leest een tekstbestand, relatief ten opzichte van het YAML-bestand dat het noemt. Het kan geen bestand buiten de projectmap noemen, en geen andere YAML-tag wordt geaccepteerd, dus een project leest nooit iets van de machine waarop het wordt gebouwd.

De bestanden van een script staan in de map met de naam van het script naast het bestand van het onderdeel (members/script/house_deck/). Het commando zet elk bestand daarin in de lijst, met grootte en controlesom, dus het bestand van het onderdeel noemt zelf nooit files. Die map mag alleen gewone bestanden bevatten, geen symbolische koppelingen. Een pakket dat alleen jouw organisatie heeft goedgekeurd, reist met de bundel mee (Pakketten in een bundel): het onderdeel noemt het met ecosystem, name, version en filename, en het bestand staat onder die naam in packages/. Het commando vult de grootte en de controlesom aan.

Geheimen horen nooit in een project. De inloggegevens van een koppeling vult de installeerder zelf in, dus geen enkel veld van een onderdeel kan ze bevatten.

Afbeeldingen en versieverslag¶

covers/listing.png is de afbeelding op de kaart in de catalogus. De afbeelding van een onderdeel staat in covers/<soort>/<naam>.png, voor een agent, een toolset, een API-koppeling, een MCP-server of een tool-alias. Een afbeelding is een .png, .jpg of .webp van hoogstens 8 MiB.

Het versieverslag van een versie is de tekst onder de eerste kop ## van CHANGELOG.md, tot de volgende, hoogstens 4.096 tekens. De kop zelf, zoals ## 1.4.0, is jouw naam voor de release; Core nummert zijn versies zelf, 1, 2, 3 enzovoort.

Eén manifestbestand¶

Een bundel mag ook één manifest.json blijven: het veld manifest van wat GET /publications/{pid}/versions/{v} teruggeeft. Daarnaast bevat artific.yaml dan alleen wat het manifest niet bevat: visibility, targets, auto_install en terms. Het commando weigert een artific.yaml die de naam, de omschrijving of iets anders noemt wat al in het manifest staat.

Zien wat het project oplevert¶

artific build --project support-desk

toont het ene manifest dat het project oplevert, en maakt nergens contact mee. Elke stap behalve pull neemt --project, dat de projectmap of een manifest.json noemt; standaard is dat de huidige map.

Een versie uitbrengen¶

Controleren¶

artific check --project support-desk

Core controleert de bundel met dezelfde regels als bij publiceren: elk onderdeel, elke verwijzing en parameter, en de voorwaarden. Gaat dat goed, dan meldt het commando of publiceren een versie zou schrijven en welke capabilities de organisatie van een abonnee nodig heeft:

support-desk: accepted; publish would write version 4
capabilities a subscriber needs: tooling, computer

Bij een weigering toont het elk veld dat Core noemde, met de eigen melding van Core, en stopt het met exitcode 1. Een prijs zonder recht bijvoorbeeld (Een prijs instellen):

artific: checking support-desk: 422 Unprocessable Content: ...
  terms.price: ...

Een controle hoort bij een publicatie, dus de allereerste release van een bundel kun je nog niet controleren; het commando meldt dat artific publish de publicatie aanmaakt. Core controleert een script alleen over bestanden die de publicatie heeft, dus check uploadt elk script- of pakketbestand dat de publicatie nog niet heeft. Een versie schrijft het niet.

Uitproberen in een testorganisatie¶

Een organisatie kan haar eigen bundel voor de marktplaats niet installeren. Om de installatie te zien zoals een abonnee hem ziet, probeer je de bundel uit in een organisatie onder de jouwe:

artific try --project support-desk --org ten_9Fb2...

Dit publiceert de bundel als een aparte publicatie, support-desk-preview, die alleen die organisatie ziet, en abonneert de organisatie erop. Open de testorganisatie en kijk onder Geïnstalleerd: de parameters worden gevraagd, de capabilities gecontroleerd en de kopieën geschreven zoals bij elke abonnee. Meldt het commando subscribed, needs_configuration, dan heeft een verplichte parameter nog geen waarde: vul die in bij het abonnement onder Geïnstalleerd (Installeren). Draai try opnieuw na een wijziging en de voorproef krijgt de nieuwe versie.

De voorwaarden van de voorproef vragen nooit om een recht en hebben geen prijs, omdat een testorganisatie geen recht heeft. Een voorproef blijft staan tot je hem intrekt:

artific try --project support-desk --withdraw

Intrekken is definitief en de naam blijft bezet, dus de volgende voorproef heet support-desk-preview-2, enzovoort. Zolang een voorproef op één organisatie gericht is, wordt try in een andere geweigerd tot je hem intrekt.

Publiceren¶

artific publish --project support-desk

Het commando maakt de publicatie aan als je organisatie er nog geen met die naam heeft: een publicatie voor de marktplaats als concept, de andere meteen aangeboden. Daarna uploadt het de scriptbestanden en pakketten die de publicatie nog niet heeft, publiceert het een versie als het manifest of de voorwaarden afwijken van de hoogste versie, uploadt het afbeeldingen waarvan de inhoud is veranderd en zet het de omschrijving als die is veranderd. Voor alles wat het schrijft, toont het één regel:

publication support-desk: created (listed)
version 1: published
cover listing: uploaded

Wat er met een nieuwe versie gebeurt, hangt af van de zichtbaarheid:

• Onderliggende organisaties of gekozen organisaties: elk abonnement dat de laatste versie volgt, synchroniseert er meteen naar. Draai dus eerst check en try.
• Marktplaats: een concept wordt aan niemand aangeboden tot Artific het opneemt. Bij een bundel die al wordt aangeboden, wacht de nieuwe versie op beoordeling, en houden abonnees de versie die ze hebben. Een gewijzigde omschrijving van zo'n bundel wacht ook, en het commando meldt dat.

Insturen voor de marktplaats¶

artific submit --project support-desk

stuurt een concept voor de marktplaats in ter beoordeling, zoals Ter beoordeling insturen in de console doet (Marktplaats). Een aangeboden bundel met een nieuwere versie wacht al op beoordeling, en die laat het commando met rust. Een bundel voor onderliggende of gekozen organisaties wordt nooit ingestuurd; het commando weigert hem. Of de bundel wordt opgenomen, blijft de beslissing van Artific.

publish en submit zijn aparte stappen, zodat een pipeline bij elke merge kan publiceren en alleen kan insturen als je een release tagt.

Een gepubliceerde versie als bestanden ophalen¶

artific pull support-desk
artific pull support-desk 3 --into support-desk-v3

schrijft een versie van een publicatie van je organisatie als projectmap: de hoogste versie tenzij je er een noemt, in een map met de naam van de publicatie tenzij je --into opgeeft. De map moet leeg zijn of nog niet bestaan. Tekst van meerdere regels in een definitie komt in <onderdeel>.<veld>.md naast het bestand van het onderdeel, en de scriptbestanden, pakketten, afbeeldingen en het versieverslag komen mee. Bouw je de opgehaalde map, dan krijg je het manifest, de voorwaarden, het versieverslag en de afbeeldingen van die versie terug; zo wordt een bundel die je eerst in de console hebt samengesteld een project.

Meldingen en exitcodes¶

Een foutregel begint met artific: en noemt waar het commando mee bezig was, zoals artific: publishing a version of support-desk: ..., gevolgd door de status en de titel van het antwoord van Core als Core weigerde. Een weigering die velden noemt, krijgt daaronder per veld een ingesprongen regel. artific <stap> --help toont de opties van een stap.

Een prijs instellen¶

Een bundel kan een prijs tonen op de marktplaats. Die prijs is een voorwaarde van de versie:

terms:
  entitlement: true
  price:
    amount: "49.00"
    currency: EUR
    period: month

period is once, month of year, en amount is een bedrag met hoogstens twee decimalen. Core bewaart de prijs en toont hem, maar brengt hem nooit in rekening: een organisatie installeert een bundel die om een recht vraagt pas als ze er een heeft, en de betaling loopt buiten Core om (Wanneer een bundel een recht vereist). Daarom wordt een prijs zonder entitlement: true geweigerd (422 op terms.price). Een gewijzigde prijs is een wijziging van de voorwaarden, dus elk abonnement wacht tot zijn organisatie de voorwaarden van de nieuwe versie accepteert; geen abonnee gaat ongevraagd naar een nieuwe prijs.

Uitbrengen vanuit een GitHub-pipeline¶

Dezelfde openbare repository bevat ook een GitHub Action, artific-ai/artific-cli, die één release van het commando installeert, controleert met SHA256SUMS en er één stap mee draait. Ze werkt in elke repository, in elke organisatie, zonder token: de enige secret die je nodig hebt is de sleutel.

Een workflow die elke pull request controleert, elke merge naar main publiceert en bij een tag instuurt:

name: bundles
on:
  pull_request:
  push:
    branches: [main]
    tags: ["v*"]

permissions:
  contents: read

jobs:
  check:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-24.04
    environment: core
    steps:
      - uses: actions/checkout@v4
      - uses: artific-ai/artific-cli@v0.1.0
        with:
          version: 0.1.0
          command: check
          args: --project bundles/support-desk
          endpoint: ${{ vars.ARTIFIC_ENDPOINT }}
          api-key: ${{ secrets.ARTIFIC_API_KEY }}

  release:
    if: github.event_name == 'push'
    runs-on: ubuntu-24.04
    environment: core
    steps:
      - uses: actions/checkout@v4
      - uses: artific-ai/artific-cli@v0.1.0
        with:
          version: 0.1.0
          command: ${{ github.ref_type == 'tag' && 'submit' || 'publish' }}
          args: --project bundles/support-desk
          endpoint: ${{ vars.ARTIFIC_ENDPOINT }}
          api-key: ${{ secrets.ARTIFIC_API_KEY }}

De GitHub-omgeving core bevat het adres als variabele ARTIFIC_ENDPOINT en de sleutel als secret ARTIFIC_API_KEY. Heb je meerdere Core-installaties, zoals een test- en een productie-installatie, geef dan elk een eigen omgeving en draai de stap per omgeving. Een repository met meerdere bundels herhaalt de stap voor elk project.

• Zet beide vast. @v0.1.0 na uses: kiest de action, version het programma; wijzig ze samen. De tags van artific-ai/artific-cli worden nooit verplaatst. Zet je in je repository elke action vast op een commit, noem dan de volledige commit waar v0.1.0 naar wijst, met de tag als commentaar.
• Controleren heeft de publicatie nodig. De eerste pull request van een nieuwe bundel faalt bij check tot publish de publicatie één keer heeft aangemaakt.
• De sleutel is een geheim als elk ander. Roteer hem zoals beschreven in Een sleutel roteren, en werk de secret bij.