Comprendre l'architecture d'Appstrate, ses composants principaux et le cycle de vie d'un agent.

🔭 Vue d'ensemble

Appstrate est une plateforme Agent as a Service. Contrairement aux outils de workflow automation qui enchaînent des étapes prédéfinies, Appstrate donne un prompt, des credentials et un contexte à un agent IA — puis l'IA décide comment accomplir la tâche. Cette page présente les concepts fondamentaux qui sous-tendent la plateforme.

┌─ Organisation ──────────────────────────────────────────────┐
│  Membres, modèles LLM, proxies, providers, packages        │
│                                                             │
│  ┌─ Application A ──────────────────────────────────────┐   │
│  │  Agents installés, end-users, API keys, webhooks     │   │
│  │                                                       │   │
│  │  ┌─ Run ──────────────────────────────────────────┐   │   │
│  │  │  Réseau Docker isolé                           │   │   │
│  │  │                                                │   │   │
│  │  │  ┌──────────┐    HTTP    ┌──────────────────┐  │   │   │
│  │  │  │  Agent   │ ────────→ │    Sidecar        │  │   │   │
│  │  │  │ (Pi/Bun) │           │ (proxy credentials│  │   │   │
│  │  │  └──────────┘           │  + injection)     │  │   │   │
│  │  │                         └────────┬─────────┘  │   │   │
│  │  │                                  │             │   │   │
│  │  │                            API externe         │   │   │
│  │  └────────────────────────────────────────────────┘   │   │
│  │                                                       │   │
│  │  ┌─ Run ──────────────────────────────────────────┐   │   │
│  │  │  (autre exécution parallèle du même agent)     │   │   │
│  │  └────────────────────────────────────────────────┘   │   │
│  └───────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─ Application B ──────────────────────────────────────┐   │
│  │  (workspace isolé, ses propres agents et end-users)  │   │
│  └───────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

🤖 Agents

Un agent est l'unité d'exécution centrale d'Appstrate. Il est défini par un prompt qui décrit sa mission — pas par un graphe d'étapes. L'IA interprète le prompt et décide quelles actions entreprendre, quels outils appeler, et dans quel ordre.

Un agent peut déclarer :

Un schéma de configuration (JSON Schema, validé par AJV) pour exposer des paramètres ajustables sans modifier le prompt
Des schémas d'entrée/sortie pour structurer les données reçues et produites
Des skills (SKILL.md) — des fichiers de contexte qui enrichissent les capacités de l'agent
Des tools — des extensions de type MCP (Model Context Protocol) qui donnent à l'agent des fonctions appelables

Persistance de l'état : à la fin de chaque run, l'agent peut retourner un result.state. Ce state est automatiquement réinjecté comme "Previous State" au run suivant, ce qui permet à un agent de garder le fil entre plusieurs exécutions (par exemple, se souvenir du dernier email traité).

Memories : en complément du state, les memories sont un stockage clé-valeur par application. Elles permettent à un agent de sauvegarder et retrouver des informations persistantes entre les runs.

🔌 Providers et connexions

Providers

Un provider représente un service externe : Gmail, Slack, Notion, GitHub, ClickUp, etc. Appstrate livre 18 providers système prêts à l'emploi. Chaque provider définit :

Son mode d'authentification : OAuth2/PKCE (avec refresh automatique des tokens), OAuth1 (HMAC-SHA1), API key, basic auth, ou custom (schéma de credentials multi-champs)
Ses URIs autorisées (authorizedUris) — la liste des URLs externes qu'un agent peut appeler avec ces credentials
Son credentialHeaderName et credentialHeaderPrefix — la manière dont le sidecar injecte les credentials dans les requêtes sortantes

Connexions

Une connexion est l'instance authentifiée d'un provider pour un utilisateur ou une organisation. Deux niveaux de profils existent :

Profil personnel : credentials liés à un utilisateur, visibles uniquement par lui
Profil d'organisation : credentials partagés entre les membres de l'organisation

Les credentials sont stockés chiffrés (AES) via la clé CONNECTION_ENCRYPTION_KEY. À aucun moment l'agent n'y accède directement — c'est le sidecar qui les injecte à la volée.

▶️ Runs

Un run est une exécution d'agent. Son cycle de vie suit ces états :

pending → running → success | failed | timeout | cancelled

Chaque run crée un réseau Docker isolé contenant deux conteneurs :

Sidecar — un proxy HTTP (Hono) qui intercepte les appels sortants de l'agent, injecte les credentials du provider, et relaie la requête vers l'API externe. Les secrets ne sont jamais exposés au conteneur agent.
Agent (Pi runtime) — un conteneur Bun qui reçoit le prompt (AGENT_PROMPT) et l'URL du sidecar (SIDECAR_URL). Il n'a aucun accès au réseau hôte.

Pour réduire la latence de démarrage, Appstrate maintient un pool de sidecars pré-créés (configurable via SIDECAR_POOL_SIZE). Les logs sont diffusés en temps réel via SSE (Server-Sent Events) et persistés en base.

Plusieurs runs d'un même agent peuvent s'exécuter en parallèle. Un schéma JSON optionnel permet de valider la structure du résultat. Le coût de chaque run (en dollars, calculé depuis les tokens LLM consommés) est également suivi.

📦 Packages AFPS

AFPS (Agent Format Packaging Standard) est le format standard pour distribuer des composants Appstrate. Un package est une archive ZIP contenant un manifest.json et les fichiers associés.

Il existe 4 types de packages :

Type	Contenu
agent	Prompt, config schema, skills, tools
skill	Fichier `SKILL.md` ajoutant du contexte à un agent
tool	Extension MCP ajoutant des fonctions appelables
provider	Définition d'un service externe et de son auth

Les packages suivent le versionnement semver (forward-only — pas de downgrades). Chaque version est identifiée par un hash SHA256 (SRI) pour garantir l'intégrité. Des dist-tags (par exemple latest) permettent de référencer une version sans connaître son numéro.

Les packages système sont chargés depuis des fichiers ZIP au démarrage de la plateforme. Vous pouvez aussi importer des packages depuis un upload ZIP, un dépôt GitHub, ou le registre Appstrate.

🏢 Multi-tenancy : organisations et applications

Organisations

L'organisation est l'unité de facturation et d'administration. Elle centralise :

Les membres et leurs rôles
Les modèles LLM et proxies configurés
Les clés de provider (OAuth client IDs/secrets)
Le catalogue de packages installés
La facturation (module cloud optionnel)

Applications

Une application est un workspace isolé au sein d'une organisation. C'est le périmètre opérationnel : chaque application possède ses propres agents installés, configurations, end-users, clés API, webhooks, schedules, memories et connexions. Une application par défaut est créée automatiquement pour chaque organisation.

End-users

Les end-users (préfixe eu_) sont les utilisateurs finaux de votre produit — pas les utilisateurs de la plateforme Appstrate. Vous les gérez entièrement via l'API et pouvez exécuter des agents en leur nom grâce à l'impersonation (header Appstrate-User, disponible uniquement en authentification par clé API).

Cela permet de construire des produits SaaS où chaque client final dispose de ses propres connexions, memories et historiques de runs, sans jamais interagir directement avec Appstrate.

Concepts