Page Agent — intégrer l'agent IA à votre site
Page Agent ajoute un agent navigateur borné à votre application. Une authentification Velqa et une autorisation explicite de l'utilisateur sont obligatoires avant toute session.
Tarifs et paliers
L'abonnement couvre le nombre de domaines actifs. L'inférence réellement consommée est débitée en plus, depuis le solde de crédit de votre compte.
| Palier | Prix | Domaines actifs |
|---|---|---|
| Starter | 29 USD / mois | 1 |
| Growth | 79 USD / mois (forfait) | jusqu'à 3 |
Growth est un forfait : le prix ne se multiplie pas par le nombre de domaines. Starter est facturé par domaine actif.
Un site que vous désactivez vous-même (interrupteur on/off du tableau de bord) ne compte ni dans le plafond de domaines, ni dans la facturation. Le réactiver le recompte.
Sans abonnement actif, une session est refusée. Souscrivez depuis Tableau de bord → Page Agent, ou depuis Tableau de bord → Facturation, qui expose aussi le palier en cours et un lien de gestion.
Créer un domaine au-delà du plafond de votre palier renvoie 409 page_agent_domain_cap_reached : passez à Growth ou désactivez un domaine existant.
Voir l'agent à l'œuvre
Une boutique fictive, `/fr/demo`, sert de terrain de démonstration : l'agent y cherche dans un catalogue, remplit un panier et s'arrête pour confirmation avant de supprimer une ligne ou de payer. Rien n'y est vendu et rien n'y est débité. La connexion est requise, comme elle le sera sur votre site.
Essai sur votre domaine
Un compte dont l'adresse e-mail est vérifiée et qui n'a jamais souscrit peut demander un essai de 14 jours depuis Tableau de bord → Page Agent. Il donne les mêmes droits qu'un palier Starter : un domaine actif, la vérification, les clés, et des sessions réelles sur votre propre site.
Aucune carte n'est demandée, mais l'essai n'est pas gratuit en inférence : comme pour un abonnement, chaque session est retenue puis débitée sur le solde de crédit de votre compte. Le crédit offert à l'inscription suffit à une évaluation.
Le compte à rebours démarre au moment où vous demandez l'essai, pas à l'inscription : lancez-le quand vous êtes prêt à poser le snippet. Un domaine déjà vérifié est activé immédiatement.
À l'échéance, le domaine repasse en veille et les sessions sont refusées. Rien n'est perdu : la vérification et la configuration restent en place, souscrire un palier réactive le domaine sans nouvelle vérification DNS. L'essai n'est accordé qu'une fois par compte.
Route d'assertion (Node/Hono)
Votre backend doit authentifier l'utilisateur, l'autoriser pour le site concerné, vérifier Origin et les en-têtes Fetch Metadata (Sec-Fetch-Site, Sec-Fetch-Mode), puis protéger la route contre le CSRF. Il signe une assertion courte avec siteId, sub, iat, exp, jti, aud et kid. La clé secrète sk_pa_ ne doit jamais arriver au navigateur : utilisez uniquement la clé publiable et l'URL d'assertion credentialed.
app.get("/page-agent/assertion", requireUser, requireCsrfAndOrigin, async (c) => {
const site = await authorizeSite(c.get("user").id, c.req.header("Origin"));
if (!site) return c.json({ error: "forbidden" }, 403);
return c.json({ assertion: await signAssertion({ siteId: site.id, sub: c.get("user").id, aud: "velqa-page-agent", kid: process.env.PAGE_AGENT_SIGNING_KID }) });
});Cycle de vie d'une session
Une session dure 15 minutes. Renouvelez-la avec POST /v1/page-agent/session/renew (jeton courant + nouvelle assertion) avant expiration ; le renouvellement fait tourner le jeton. Une session expirée renvoie 401 page_agent_session_expired : réémettez-en une plutôt que de réessayer.
Chaque tour consomme un pas du budget de la session (maxSteps) et une part de ses budgets de coût.
Idempotence des tours
POST /v1/page-agent/chat/completions exige un en-tête `Idempotency-Key` (256 caractères maximum). Réutilisez la même clé pour rejouer un tour dont vous n'avez jamais reçu l'issue — typiquement après un 502/503/504 : le tour reprend sa réservation d'origine au lieu d'en ouvrir une seconde.
La clé est appariée à une empreinte du corps de la requête, calculée sur une forme canonique : réordonner les clés d'un schéma d'outil ne casse pas un retry. En revanche, réutiliser la même clé avec un contenu réellement différent renvoie 409 page_agent_idempotency_conflict — prenez une nouvelle clé pour un nouveau tour. Les réponses mises en cache expirent après 15 minutes.
Un seul tour à la fois par session : un appel concurrent renvoie 409 page_agent_request_in_flight.
Codes d'erreur
Toutes les réponses d'erreur ont la forme { "error": "<code>" }. Le code, pas le statut seul, porte la conduite à tenir.
| Statut | Code | Conduite à tenir |
|---|---|---|
| 400 | page_agent_request_invalid | Corrigez la charge utile (voir Limites). |
| 401 | page_agent_session_expired | Réémettez une session ; ne réessayez pas tel quel. |
| 402 | page_agent_owner_credit | Solde de crédit insuffisant côté propriétaire du site : rechargez. |
| 402 | page_agent_site_budget | Plafond mensuel du site atteint. |
| 403 | page_agent_assertion_invalid | Assertion, Origin ou domaine non valides. |
| 403 | page_agent_site_disabled | Le propriétaire a désactivé le site ; il peut le réactiver. |
| 403 | page_agent_site_suspended | Suspension administrative : contactez le support. |
| 409 | page_agent_request_in_flight | Un tour est déjà en cours sur cette session ; attendez. |
| 409 | page_agent_idempotency_conflict | Même Idempotency-Key, contenu différent : changez de clé. |
| 409 | page_agent_idempotency_replay_unavailable | Le tour rejoué est déjà réglé ; prenez une nouvelle clé. |
| 429 | page_agent_rate_limited | Ralentissez, puis réessayez. |
| 503 | page_agent_not_available | Indisponibilité passagère (dépendance interne) : réessayez. |
page_agent_owner_credit et page_agent_not_available sont les deux cas à ne pas confondre : le premier demande une action de facturation, le second un simple retry.
Limites de requête
Une requête de tour est refusée en 400 page_agent_request_invalid au-delà de :
- 1 Mio de corps de requête ;
- 128 messages, 64 outils ;
- 262 144 caractères par message ;
- 65 536 octets pour le schéma
parametersd'un outil.
Les rôles acceptés sont user, assistant et tool. Un outil nommé execute_javascript est refusé.
DOM, sécurité et confirmations
Le DOM est une donnée non fiable : une injection indirecte de prompt peut être placée dans une page. L'agent ne doit jamais considérer son contenu comme une instruction de confiance. Les mots de passe, champs de carte et marqueurs data-velqa-mask sont masqués par défaut. Le masquage des données métier est opt-in et n'est qu'un masque visuel d'interaction, pas une garantie de confidentialité.
Les actions destructives (delete, pay, send, archive, disable, revoke, checkout et soumission de paiement) sont suspendues avant dispatch et nécessitent un marqueur de confirmation. Les navigations sont limitées aux origines exactes autorisées ; javascript: et l'exécution JavaScript sont refusés.
Données, fournisseurs et rétention
Le contenu DOM sélectionné et les prompts transitent vers les sous-traitants d'inférence autorisés et listés au registre en vigueur. Les métadonnées de session sont conservées au maximum 90 jours, les agrégats de facturation/usage 24 mois, et le cache technique chiffré d'idempotence au maximum 15 minutes. Consultez le DPA et la politique de confidentialité.
Installation
Le SDK est chargé depuis une release immuable et vérifiée par SRI. Configurez data-velqa-key, data-velqa-lang et data-velqa-assertion-url ; ne copiez jamais une clé sk_pa_ dans le HTML. data-velqa-api-base vaut https://api.velqa.dev par défaut et n'a besoin d'être précisé que pour pointer une autre API. data-velqa-lang accepte fr-FR et en-US : il fixe la langue du panneau et celle dans laquelle l'agent répond à vos visiteurs. Le snippet proposé dans le tableau de bord contient déjà les quatre attributs. Le runbook opératoire interne détaille les alertes et procédures d'incident.