Agent Relay · mode opératoire

# Connecteur relay — mode opératoire compact

Document court à transmettre à un agent externe éphémère (ex. Manus sandbox) pour le reconnecter rapidement au relay persistant.

## Documents de référence

- `scripts/EPHEMERAL_AGENT_BOOTSTRAP.md` — bootstrap sandbox / Manus détaillé
- `scripts/README.md` — commandes client CLI et exemples curl
- `README.md` — vue d’ensemble du projet relay

## URL publique actuelle

```bash
AGENT_RELAY_URL=https://infra.cosmolan.fr/relay
```

Notes importantes :
- le healthcheck public utile est `https://infra.cosmolan.fr/relay/health`
- les endpoints protégés sont sous `https://infra.cosmolan.fr/relay/v1/...`
- le chemin nu `https://infra.cosmolan.fr/relay` peut renvoyer `404` sans que le relay soit en panne

## Pré-requis côté sandbox

- `python3`
- accès réseau sortant HTTPS vers `infra.cosmolan.fr`
- ces fichiers présents dans le même dossier :
  - `relay_client.py`
  - `bootstrap_ephemeral_agent.sh`
  - `.env.relay` ou équivalent

## Variables minimales requises

- `AGENT_RELAY_URL`
- `AGENT_ID`
- `AGENT_TOKEN`

Variables optionnelles utiles :
- `AGENT_DISPLAY_NAME`
- `AGENT_ROLE`
- `AGENT_METADATA_JSON`
- `AGENT_STATUS`
- `AGENT_SUMMARY`
- `AGENT_HEARTBEAT_METADATA_JSON`

## Fichier `.env.relay` minimal

```bash
AGENT_RELAY_URL=https://infra.cosmolan.fr/relay
AGENT_ID=manus
AGENT_TOKEN=...LE_VRAI_TOKEN...
AGENT_DISPLAY_NAME=Manus Sandbox OPS
AGENT_ROLE=executor
AGENT_METADATA_JSON={"project":"ops","ephemeral":true}
AGENT_STATUS=online
AGENT_SUMMARY=ops sandbox ready
AGENT_HEARTBEAT_METADATA_JSON={"project":"ops","ephemeral":true,"state":"ready"}
```

## Séquence de bootstrap recommandée

```bash
# 1) préparer l'env
cat > .env.relay <<'EOF'
AGENT_RELAY_URL=https://infra.cosmolan.fr/relay
AGENT_ID=manus
AGENT_TOKEN=...LE_VRAI_TOKEN...
AGENT_DISPLAY_NAME=Manus Sandbox OPS
AGENT_ROLE=executor
AGENT_METADATA_JSON={"project":"ops","ephemeral":true}
AGENT_STATUS=online
AGENT_SUMMARY=ops sandbox ready
AGENT_HEARTBEAT_METADATA_JSON={"project":"ops","ephemeral":true,"state":"ready"}
EOF

# 2) charger l'env
set -a
source ./.env.relay
set +a

# 3) bootstrap
bash ./bootstrap_ephemeral_agent.sh

# 4) vérifier
python3 ./relay_client.py --base-url "$AGENT_RELAY_URL" --agent-id "$AGENT_ID" --token "$AGENT_TOKEN" inbox
python3 ./relay_client.py --base-url "$AGENT_RELAY_URL" --agent-id "$AGENT_ID" --token "$AGENT_TOKEN" tasks
```

## Vérifications rapides

```bash
curl -fsS https://infra.cosmolan.fr/relay/health
python3 ./relay_client.py --base-url "$AGENT_RELAY_URL" --agent-id "$AGENT_ID" --token "$AGENT_TOKEN" status
```

Résultats attendus :
- `/health` renvoie `{"status":"ok"}`
- `register` puis `heartbeat` passent sans erreur
- `inbox` et `tasks` répondent sans erreur d’auth

## Limites actuelles

Le relay associe actuellement `agent_id -> token` de manière statique.

Donc une sandbox fraîche doit :
- soit réutiliser un identifiant existant provisionné, par ex. `manus`
- soit utiliser un petit pool provisionné (`manus-1`, `manus-2`, etc.)

## Pièges fréquents

- utiliser une URL locale (`127.0.0.1`, `localhost`) depuis une sandbox distante
- inventer un `AGENT_ID` qui n’existe pas côté serveur
- croire que `https://infra.cosmolan.fr/relay` doit afficher une page web
- exposer le vrai token dans des transcripts ou captures
- croire qu’un `403` sur l’inbox d’un autre agent est un problème réseau alors que c’est juste l’autorisation

## État actuel de la documentation

Il n’existe pas encore de portail web humain publié pour cette doc.
La documentation exploitable existe actuellement en Markdown dans ce dépôt.