Uw AI-register uitlezen vanuit een eigen systeem

Endpoints

Alles onder /api/v1/, alles met de methode GET. Er bestaan geen schrijf-endpoints.

Filters per endpoint

Een onbekende waarde of een onbekende parameternaam levert een 400 op met de reden erbij, nooit stilzwijgend een ongefilterde lijst. Alle lijsten pagineren met limit (maximaal 200) en offset.

Antwoorden en fouten

Elk antwoord draagt een ok-vlag. Bij een lijst zit er een pagination-blok bij met het totaal, zodat u weet of er meer is.

{
  "ok": true,
  "data": [ … ],
  "pagination": { "limit": 50, "offset": 0, "total": 214, "has_more": true }
}

Het aanmeldpunt voor agents

POST https://www.aicompliancehub.nl/api/agent-intake
Authorization: Bearer <agent-token>
Content-Type: application/json

Het manifest

Bewaar het per agent in de repo als aicompliancehub-agent.json. Het JSON Schema staat op /schemas/agent-manifest.v1.json, zodat een editor of assistent het bestand kan controleren. De namen description en version uit de A2A Agent Card werken ook.

Wat het antwoord zegt

Een geslaagde melding geeft HTTP 200 met een veld status. Een agent die al in het register staat, wordt vergeleken met de laatst goedgekeurde versie. Witruimte, hoofdletters en de volgorde van een lijst tellen daarbij niet mee. Voor zo'n agent is herhaald melden vanuit een pipeline dus veilig. Een nieuwe agent die is afgewezen, staat niet in het register en komt bij een volgende melding opnieuw in de wachtrij. Een waarde die niet in de lijst van een veld staat, wordt genegeerd; de beheerder vult het veld dan aan.

Melden vanuit de pipeline

Deze stap meldt elk manifest in de repo zodra het verandert. Voorbeelden voor GitLab CI en Azure Pipelines staan in het platform bij de instructies voor bouwers.

# .github/workflows/ai-register.yml
name: AI-register
on:
  push:
    branches: [main] # de standaardbranch van de repo
    paths: ["**/aicompliancehub-agent.json"]
jobs:
  melden:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Agents melden bij het AI-register
        env:
          AGENT_TOKEN: ${{ secrets.AICOMPLIANCEHUB_AGENT_TOKEN }}
        run: |
          set -eu
          set -o pipefail
          git ls-files 'aicompliancehub-agent.json' '**/aicompliancehub-agent.json' | while IFS= read -r f; do
            echo "Melden: $f"
            curl -sS --fail-with-body -X POST "https://www.aicompliancehub.nl/api/agent-intake" \
              -H "Authorization: Bearer $AGENT_TOKEN" \
              -H "Content-Type: application/json" \
              --data @"$f"
            echo
          done

Organisatiebreed inrichten

# .github/workflows/ai-register.yml in één repo van de organisatie
# Eenmalig: een GitHub App met alleen-lezen Contents en Metadata op alle repo's,
# geïnstalleerd op de organisatie. Zet in deze repo de variabele AI_REGISTER_APP_ID
# en de secrets AI_REGISTER_APP_KEY (private key) en AICOMPLIANCEHUB_AGENT_TOKEN.
name: AI-register (hele organisatie)
on:
  schedule:
    - cron: "17 5 * * *" # elke dag
  workflow_dispatch:
permissions:
  contents: read
jobs:
  scannen:
    runs-on: ubuntu-latest
    steps:
      - id: app
        uses: actions/create-github-app-token@v3
        with:
          client-id: ${{ vars.AI_REGISTER_APP_ID }}
          private-key: ${{ secrets.AI_REGISTER_APP_KEY }}
          owner: ${{ github.repository_owner }}
          permission-contents: read
          permission-metadata: read
      - name: Alle manifesten melden bij het AI-register
        env:
          GH_TOKEN: ${{ steps.app.outputs.token }}
          AGENT_TOKEN: ${{ secrets.AICOMPLIANCEHUB_AGENT_TOKEN }}
        run: |
          set -eu
          set -o pipefail
          OWNER="${OWNER:-$GITHUB_REPOSITORY_OWNER}"
          MANIFEST="${MANIFEST:-aicompliancehub-agent.json}"
          werk=$(mktemp -d)
          
          if [ -n "${AI_REGISTER_REPOS:-}" ]; then
            for r in $AI_REGISTER_REPOS; do
              printf '%s\t%s\n' "$r" "$(gh api "repos/$OWNER/$r" --jq .default_branch)"
            done > "$werk/repos"
          else
            # Met een App-token: de repo's waar de App bij mag. Anders de organisatie.
            gh api --paginate installation/repositories --jq '.repositories[] | select(.archived | not) | [.name, .default_branch] | @tsv' > "$werk/repos" 2>/dev/null ||
              gh api --paginate "orgs/$OWNER/repos?per_page=100" --jq '.[] | select(.archived | not) | [.name, .default_branch] | @tsv' > "$werk/repos"
          fi
          
          aantal=0
          while IFS="$(printf '\t')" read -r repo branch; do
            if ! gh api "repos/$OWNER/$repo/git/trees/$branch?recursive=1" > "$werk/boom" 2>/dev/null; then
              echo "Overgeslagen: $repo (leeg of geen toegang)"
              continue
            fi
            # tr -d: jq op Windows schrijft CRLF; op Linux verandert het niets.
            if [ "$(jq -r '.truncated' "$werk/boom" | tr -d '\r')" = "true" ]; then
              echo "Let op: de bestandsboom van $repo is te groot en afgekapt; zet het manifest hoger in de repo."
            fi
            jq -r --arg f "$MANIFEST" '.tree[] | select(.type == "blob") | .path | select(. == $f or endswith("/" + $f))' "$werk/boom" | tr -d '\r' > "$werk/paden"
            while IFS= read -r pad; do
              map=$(dirname "$pad")
              if [ "$map" = "." ]; then ref="$repo"; else ref="$repo/$map"; fi
              gh api -H "Accept: application/vnd.github.raw+json" "repos/$OWNER/$repo/contents/$pad?ref=$branch" |
                jq --arg ref "$ref" '.agent_ref //= $ref' > "$werk/manifest.json"
              echo "Melden: $repo/$pad"
              curl -sS --fail-with-body -X POST "https://www.aicompliancehub.nl/api/agent-intake" \
                -H "Authorization: Bearer $AGENT_TOKEN" \
                -H "Content-Type: application/json" \
                --data @"$werk/manifest.json"
              echo
              aantal=$((aantal + 1))
            done < "$werk/paden"
          done < "$werk/repos"
          echo "Klaar: $aantal manifest(en) gemeld."