# Essai et rattachement d’un agent

Essayez une recherche Google avant de vous inscrire, puis rattachez l’essai au compte du propriétaire pour continuer avec le même profil CLI.

Référence canonique : https://flashdata.dev/fr/docs/guides/agent-onboarding
Vérifié le 2026-11-04 par FlashData

<a id="access"></a>

## 1. Vérifier l’accès existant

Exécutez cette vérification gratuite dans l’environnement de l’agent. Si data.accessVerified vaut true et que Google Search est autorisé, réutilisez cet accès et passez à l’étape 3. Sans profil enregistré, passez à l’étape 2. Pour reprendre un accès en attente ou bloqué, consultez la section de récupération ci-dessous.

### Vérifier ce profil

```bash
flashdata auth status --json --non-interactive
```

- [Installer la CLI](https://flashdata.dev/fr/docs/guides/flashdata-cli/reference.md#install)
- [Vous avez déjà une clé ?](https://flashdata.dev/fr/docs/guides/agent-onboarding/reference.md#existing)
- [Rétablir l’accès](https://flashdata.dev/fr/docs/guides/agent-onboarding/reference.md#help)

<a id="prepare"></a>

### Conserver le même profil

Un accès fonctionnel renvoie data.accessVerified: true, access: ready dans data.identity.identity et google_search dans data.identity.permittedSources.

Ces commandes utilisent le profil par défaut et fonctionnent dans Bash ou PowerShell. Pour un profil nommé ou un répertoire d’état personnalisé, ajoutez les mêmes options --profile NAME et --state-dir ABSOLUTE_PATH à chaque commande, y compris dans un nouveau terminal.

FLASHDATA_API_KEY est prioritaire sur la clé enregistrée. Laissez cette variable non définie lorsque vous testez l’essai et la transmission des identifiants de ce profil. Utilisez le même utilisateur du système et conservez le répertoire d’état privé : il contient les identifiants, la preuve d’inscription et l’historique des exécutions.

Vérifiez credentialProtection dans auth status. Windows utilise DPAPI, macOS utilise Keychain et Linux sans interface graphique peut utiliser un fichier d’identifiants accessible au seul propriétaire. L’option --credential-store os exige l’utilisation d’un stockage système disponible.


<a id="existing"></a>

### Utiliser une clé propriétaire existante

Une personne dans un terminal peut importer une clé avec la saisie masquée ci-dessous et passer l’inscription à l’essai ainsi que le rattachement. Les agents doivent la transmettre via stdin depuis leur gestionnaire de secrets, avec --api-key-stdin --non-interactive. Ne placez jamais de clé dans les arguments ni dans la conversation.

Si le profil contient déjà un autre accès, examinez-le avant d’utiliser auth login --replace. Importer une autre clé ne remplace pas la transmission des identifiants après rattachement. OAuth MCP est également une connexion distincte, propre à l’hôte.

#### Saisie masquée de la clé · terminal d’un utilisateur

```bash
flashdata auth login
flashdata auth status --json --non-interactive
```

- [Gestion des clés API](https://flashdata.dev/fr/docs/guides/api-keys-and-permissions/reference.md)
- [MCP et autres méthodes d’authentification](https://flashdata.dev/fr/docs/guides/agent-access/reference.md)

<a id="trial"></a>

## 2. Démarrer un seul essai éligible

Exécutez d’abord discover. Vérifiez data.onboardingAvailable et le quota dans data.onboarding.trial. Si l’accès d’essai est disponible, exécutez init une seule fois pour Google Search. Le serveur vérifie l’éligibilité ; la CLI enregistre la clé temporaire sans ouvrir la page d’inscription ni soumettre de requête.

### Vérifier la disponibilité · gratuit

```bash
flashdata discover --json --non-interactive
```

### Démarrer l’accès temporaire

```bash
flashdata init --name "Research assistant" --scopes google_search --json --non-interactive
```

- [Protocole actuel](https://flashdata.dev/auth.md)

<a id="trial-receipt"></a>

### Vérifier la réponse d’inscription

La réponse doit contenir ok: true, data.status: trial et google_search dans data.connection.scopes. Consultez data.connection.trialExpiresAt et data.startingAllowanceCredits. La clé est enregistrée localement et n’est pas affichée. Si data.currentBalanceAvailable vaut false, vérifiez à nouveau le solde gratuitement avant toute requête.

Si la configuration a déjà créé un accès, réutilisez-le. Pour identifier l’origine de la première inscription d’un agent, ajoutez --client codex --audience coding ou --client openclaw --audience personal. En cas de nouvelle tentative, conservez exactement les mêmes paramètres ; ces étiquettes n’accordent aucune autorisation.


<a id="trial-limits"></a>

### Crédits et limites de l’essai

Les équivalents en nombre de requêtes partagent le même solde initial de crédits. Ce ne sont ni des requêtes restantes ni des quotas indépendants. Les sources réservées à un accès propriétaire, comme YouTube Download, ne peuvent pas utiliser les crédits d’essai.

| Limite | Point à vérifier |
| --- | --- |
| Crédits / expiration | Valeurs par défaut actuelles : 1 crédit pendant 72 heures. Consultez la réponse de discover pour connaître le quota et la durée ; la réponse d’inscription indique l’expiration et les sources autorisées. |
| Inscription | 3 inscriptions par IP sur 24 heures, partagées entre les utilisateurs de cette IP. Le plafond global des essais peut également suspendre les nouvelles inscriptions. |
| Exécutions simultanées | Exécutez les tâches d’essai séquentiellement : un élément par lot et une seule tâche en attente. Vérifiez les limites renvoyées avant d’en soumettre davantage. |

- [Crédits et nombre de requêtes](https://flashdata.dev/fr/docs/guides/credits-and-billing/reference.md#estimate)
- [Accès au téléchargement uniquement](https://flashdata.dev/fr/docs/guides/agent-onboarding/reference.md#download-only)

<a id="first-task"></a>

## 3. Essayer une recherche

Vérifiez d’abord l’estimation. Exigez data.estimateAvailable, un tarif google_search disponible dans data.estimate.prices et un solde availableCredits couvrant estimatedCredits. Arrêtez si une vérification échoue. L’estimation est gratuite ; la commande suivante soumet une recherche.

### Vérifier le solde et le coût · sans requête

```bash
flashdata account balance --json --non-interactive
flashdata search "battery recycling" --num 5 --dry-run --json --non-interactive
```

### Une recherche · au plus cinq résultats

```bash
flashdata search "battery recycling" --num 5 --run-id trial-search --json --non-interactive
```


<a id="result"></a>

### Vérifier le résultat

La réponse doit contenir ok: true et data.status: done. Consultez les titres, liens et extraits dans data.results[].organic, et les crédits facturés dans data.usage.credits. Des résultats organic vides sont valides. Avant le rattachement, répéter exactement cette tâche avec trial-search renvoie son résultat enregistré. Conservez le profil, son état et les résultats d’essai utiles.

#### Vérifier le solde restant · gratuit

```bash
flashdata account balance --json --non-interactive
```

- [Lire une réponse de recherche](https://flashdata.dev/fr/docs/guides/http-quickstart/reference.md#result)

<a id="claim"></a>

## 4. Conserver l’accès avec un compte propriétaire

Rattachez l’essai avant son expiration pour un usage continu ou récurrent. Lorsque le propriétaire est prêt, exécutez cette commande dans le profil d’origine. Partagez uniquement data.claimUrl et data.confirmationCode avec lui ; data.expiresAt indique la date limite.

Le lien reste valide 15 minutes, ou jusqu’à l’expiration de l’essai si elle survient avant. Créer le lien n’approuve aucun accès et n’achète aucun crédit.

### Créer un lien de rattachement lorsque le propriétaire est prêt

```bash
flashdata auth claim --json --non-interactive
```


<a id="owner-approval"></a>

### Approuver dans le navigateur

1. Le propriétaire ouvre le lien et se connecte, ou crée un compte et vérifie son adresse e-mail. Pour un nouveau compte, le rattachement reprend automatiquement après la vérification.
2. Vérifiez le compte affiché sur la page de rattachement. Pour un autre propriétaire ou un nouveau compte, utilisez une session de navigateur distincte. Le compte connecté paiera les requêtes suivantes.
3. Saisissez le code à huit chiffres sur cette page, examinez les autorisations de produits et l’accès au solde partagé, puis approuvez. Le propriétaire effectue l’inscription, accepte les conditions, vérifie son adresse e-mail et autorise l’accès.


<a id="finish"></a>

### Terminer dans le terminal d’origine

Après approbation, exécutez finish dans le profil d’origine sous 24 heures. La CLI enregistre la clé propriétaire, la vérifie dans un nouveau processus et confirme son installation. Aucune clé n’est copiée depuis le navigateur.

#### Enregistrer et vérifier l’accès propriétaire

```bash
flashdata auth finish --wait --timeout 10m --json --non-interactive
```

#### Vérifier ensuite dans un nouveau terminal · même utilisateur et même profil

```bash
flashdata auth status --json --non-interactive
flashdata account balance --json --non-interactive
```


<a id="owner-result"></a>

### Confirmer le propriétaire et le solde

Dans auth status, vérifiez le compte accountId prévu, les scopes accordés et les champs ci-dessous. Consultez séparément le solde actuel : les requêtes suivantes consommeront les crédits partagés du propriétaire. Les crédits temporaires inutilisés ne sont pas transférés. Un nouveau compte suit les règles normales d’éligibilité à l’inscription ; le rattachement n’ajoute pas de crédits d’inscription supplémentaires.

Le rattachement change le compte facturé. Pour une nouvelle tâche avec le compte propriétaire, choisissez un nouvel identifiant d’exécution. Réutiliser un identifiant d’exécution de l’essai renvoie run_account_mismatch sans soumettre de nouvelle requête ; cela ne transfère pas l’exécution au propriétaire.

#### Champs attendus · extrait de réponse

```json
{
  "ok": true,
  "data": {
    "accessVerified": true,
    "identity": {
      "identity": {
        "accountType": "owned",
        "access": "ready",
        "installed": true,
        "recurringAllowed": true
      }
    }
  }
}
```

- [Configurer des tâches récurrentes](https://flashdata.dev/fr/docs/guides/recurring-tasks/reference.md)
- [Crédits après rattachement](https://flashdata.dev/fr/docs/guides/credits-and-billing/reference.md#trial)
- [Révoquer cette connexion](https://flashdata.dev/fr/docs/guides/agent-access/reference.md#revoke)

<a id="permissions"></a>

## Choisir les autorisations de produits

Le catalogue HTTP d’autorisations distingue trialEligible de ownerAllowed. Demandez uniquement les sources nécessaires avant la première inscription. requestedScopes contient la demande ; scopes contient les accès actuels de la clé. Les nouveaux produits nécessitent une autorisation explicite.

L’approbation donne accès au solde partagé du propriétaire, y compris aux crédits achetés. Les restrictions par source ne créent pas de plafond de dépenses par agent. OAuth MCP est une connexion distincte et ne rattache pas ce profil CLI.

- [Catalogue des autorisations et protocole HTTP](https://flashdata.dev/auth.md)

<a id="download-only"></a>

## Vous avez seulement besoin de YouTube Download ?

Importez une clé propriétaire autorisant youtube_download, puis configurez le stockage de destination. Le téléchargement n’utilise pas les crédits d’essai temporaires.

La CLI 1.2.1 exige encore une source éligible à l’essai pour init. Pour un accès limité au téléchargement avant inscription, utilisez le parcours de rattachement HTTP décrit dans auth.md. N’ajoutez pas une source d’essai sans rapport pour contourner cette restriction du client.

- [Importer une clé propriétaire](https://flashdata.dev/fr/docs/guides/agent-onboarding/reference.md#existing)
- [Configurer le stockage et télécharger](https://flashdata.dev/fr/docs/guides/youtube-download-guide/reference.md)
- [Parcours HTTP pour le téléchargement uniquement](https://flashdata.dev/auth.md)

<a id="help"></a>

## Reprendre un parcours interrompu

| Étape interrompue | Action suivante |
| --- | --- |
| Inscription | En cas d’erreur 429, respectez Retry-After. Si la réponse a été perdue, relancez init avec le même profil, la même preuve et exactement les mêmes paramètres. Conservez l’état existant ; ne changez pas d’IP et ne démarrez pas un autre essai. |
| Recherche | Inspectez trial-search ci-dessous. Un délai dépassé ne prouve pas qu’aucune tâche n’a été acceptée ; ne changez pas l’identifiant d’exécution pour forcer une nouvelle tentative. |
| Lien de rattachement | Si le lien a expiré mais que l’essai reste valide, créez un nouveau lien dans le même profil lorsque le propriétaire est prêt. Vérifiez le compte connecté avant l’approbation. |
| Transmission des identifiants | Après approbation, relancez auth finish dans le profil d’origine sous 24 heures. Une approbation en attente, une attente interrompue ou une confirmation perdue ne nécessite pas de nouvelle inscription. |
| Expiration / état perdu | Si l’essai ou le délai de transmission des identifiants a expiré, ou si le répertoire d’état privé est perdu, reconnectez-vous avec l’accord du propriétaire ou importez une clé propriétaire. |

### Inspecter la recherche enregistrée · sans nouvelle requête

```bash
flashdata runs show trial-search --json --non-interactive
```

- [Guide de récupération](https://flashdata.dev/fr/docs/guides/agent-recovery/reference.md)
