Importer, exporter et versionner des agents, skills, tools et providers au format AFPS.

📦 Présentation

AFPS (Agent Format Packaging Standard) est le format de packaging d'Appstrate. Il définit 4 types de packages :

Type	Description	Préfixe
`agent`	Agent IA avec prompt, config, skills, tools	`ag_`
`skill`	Document Markdown (SKILL.md) qui étend les connaissances d'un agent	`sk_`
`tool`	Extension MCP-style avec des fonctions appelables au runtime	`tl_`
`provider`	Définition de service externe (OAuth, API key, credentials)	`prov_`

🗂️ Structure d'un package

Un package AFPS est un fichier ZIP contenant au minimum un manifest.json :

mon-agent.afps
├── manifest.json    # Métadonnées, config schema, dépendances
├── prompt.md        # Prompt de l'agent (type agent)
├── SKILL.md         # Contenu du skill (type skill)
├── extension.ts     # Code du tool (type tool)
└── ...

📥 Importer un package

Depuis un fichier ZIP

curl -X POST http://localhost:3000/api/packages/import \
  -H "Authorization: Bearer ask_your_key" \
  -H "X-App-Id: app_xxx" \
  -F "[email protected]"

Depuis GitHub

curl -X POST http://localhost:3000/api/packages/import/github \
  -H "Authorization: Bearer ask_your_key" \
  -H "X-App-Id: app_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://github.com/user/repo",
    "ref": "main"
  }'

🔢 Versioning

Les packages suivent le semver (semantic versioning) avec des contraintes :

Forward-only — les versions ne peuvent pas régresser (pas de downgrade)
Dist-tags — pointeurs nommés vers des versions (latest, custom)
Intégrité — hash SHA256 SRI calculé pour chaque version
Le tag latest est auto-géré sur les publishes non-prerelease
Le tag latest ne peut pas être set/remove manuellement

Publier une nouvelle version

curl -X POST http://localhost:3000/api/packages/agents/ag_xxx/versions \
  -H "Authorization: Bearer ask_your_key" \
  -H "X-App-Id: app_xxx" \
  -F "[email protected]"

Lister les versions

curl http://localhost:3000/api/packages/agents/ag_xxx/versions \
  -H "Authorization: Bearer ask_your_key" \
  -H "X-App-Id: app_xxx"

🚫 Yank (retrait)

Le yank marque une version comme retirée sans la supprimer. Les dist-tags affectés sont réassignés à la meilleure version stable.

🔗 Dépendances

Les agents peuvent déclarer des dépendances vers des skills et tools. Les dépendances sont stockées par version et extraites via @appstrate/core/dependencies.

🔍 Résolution de version

La résolution se fait en 3 étapes :

Correspondance exacte — 1.2.3
Dist-tag — latest, beta
Range semver — ^1.0.0, ~2.1

⚙️ Packages système

Les packages système sont livrés avec Appstrate dans le dossier system-packages/. Ils sont chargés automatiquement au démarrage et synchronisés en base avec orgId: null (globaux).

📤 Télécharger un package

curl http://localhost:3000/api/packages/agents/ag_xxx/versions/1.0.0/download \
  -H "Authorization: Bearer ask_your_key" \
  -H "X-App-Id: app_xxx" \
  -o agent.afps

🍴 Forker un package

Créez une copie indépendante d'un package existant :

curl -X POST http://localhost:3000/api/packages/ag_xxx/fork \
  -H "Authorization: Bearer ask_your_key" \
  -H "X-App-Id: app_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-custom-agent"}'

Packages AFPS