Guide de configuration

Travaillez de haut en bas. Chaque étape possède une vérification avant le passage à la suivante.

1. Clés

clé	où	notes
`ANTHROPIC_API_KEY`	https://console.anthropic.com/settings/keys	ou ignorez-la et connectez-vous une fois avec `ant auth login`. L'organisation doit avoir accès à Managed Agents
`NATIONAL_PARK_SERVICE_API_KEY`	https://www.nps.gov/subjects/developer/get-started.htm	gratuit, envoyé par email instantanément
`WINDY_API_KEY`	https://api.windy.com/point-forecast/docs	tier gratuit, produit point-forecast

cp .env.example .env.local   # puis remplissez les trois clés

Vérifiez les clés des fournisseurs depuis votre machine avant d'impliquer le sandbox :

curl -sS "https://developer.nps.gov/api/v1/alerts?parkCode=acad&limit=1" -H "X-Api-Key: $NATIONAL_PARK_SERVICE_API_KEY" | head -c 300
curl -sS -X POST "https://api.windy.com/api/point-forecast/v2" \
  -H "Content-Type: application/json" \
  -d '{"lat":44.35,"lon":-68.21,"model":"gfs","parameters":["temp"],"levels":["surface"],"key":"'"$WINDY_API_KEY"'"}' | head -c 300

Les deux retournent du JSON. Un 403 ici indique un problème de clé, pas un problème de cookbook.

2. Provisionner

npm install
npm run setup

Crée l'environnement (mise en réseau limitée à developer.nps.gov et api.windy.com), l'agent revieweur (Opus, prompt review-only), l'agent planificateur (bash activé, web_search/web_fetch désactivés, un roster coordinateur multiagent nommant le revieweur), le vault, et deux credentials environment_variable avec l'injection_location codée en dur que chaque fournisseur documente (NPS : header, Windy : body). Écrit six ids ROADTRIP_PLANNER_* dans .env.local. Relancer est sans effet tant que l'agent existe (il demande --force si le planificateur stocké est antérieur au roster du revieweur), et --force provisionne une copie fraîche.

3. Exécuter

npm run dev

Ouvrez http://localhost:3000. La page crée une session par navigateur au chargement (cookie roadtrip_planner_session_id), donc le sandbox est chaud avant la première question. Puis effectuez les quatre étapes dans README.md, dans l'ordre. L'étape 2 est l'histoire du vault et elle n'apparaît qu'après une vraie conversation. L'étape 3 est le sélecteur de modèle agent_with_overrides. L'étape 4 est l'examen multi-agent : elle nécessite une demande d'itinéraire complète, pas une question factuelle.

Débogage

symptôme	cause	correction
`npm run setup` 404s sur `/v1/environments`	organisation non inscrite à Managed Agents	demandez l'accès, ou changez d'organisation
`tsc` rejette `event_deltas`, `injection_location`, ou l'import `lib/sessions/accumulate`	le SDK installé est antérieur à la mise à jour Managed Agents du 2026-07-01	mettez à jour `@anthropic-ai/sdk`
les réponses arrivent en entier, pas de rendu token par token	la porte de streaming de l'organisation est fermée (`event_deltas` est silencieusement ignoré quand fermée), ou le parser de flux d'un SDK plus ancien supprime les événements `event_start` / `event_delta` qu'il ne reconnaît pas	confirmez que l'organisation est inscrite à la mise à jour ; mettez à jour `@anthropic-ai/sdk`
sélectionner un modèle 400s avec « Agent must be a non-empty Agent ID or agent_reference » (ou l'ancien « Extra inputs are not permitted »)	la porte de l'organisation pour `agent_with_overrides` n'est pas encore ouverte (une porte fermée rejette le sélecteur comme forme d'agent inconnue)	utilisez le modèle par défaut jusqu'à ce que l'organisation soit inscrite à la mise à jour
sélectionner un modèle 400s avec `agent_field_not_overridable`	le sélecteur contenait une clé non remplaçable (la porte est ouverte ; seuls `model`, `system`, `tools`, `mcp_servers`, `skills` peuvent être remplacés)	ne se produit que si vous avez édité `createTripSession` : supprimez la clé supplémentaire
l'écran de démarrage dit « Missing ROADTRIP_PLANNER_AGENT_ID »	`.env.local` n'a pas été écrit ou dev server démarré avant setup	lancez `npm run setup`, redémarrez `npm run dev`
les événements arrivent uniquement en rafales de fin de tour	un proxy stocke la réponse SSE	utilisez `next dev` directement sur localhost d'abord
la réponse ne cite aucun appel d'outil	l'agent a répondu à partir de ses connaissances préalables	le prompt demande une preuve API par affirmation : relancez `npm run setup -- --force` si vous l'avez affaibli
l'itinéraire arrive sans remise à l'examen (pas d'événements de thread dans le rail)	le planificateur stocké est antérieur au roster du revieweur (provisionné avant le changement multiagent), ou la question était assez petite pour que la branche « skip the review » du prompt s'applique	relancez `npm run setup -- --force` ; demandez un itinéraire complet de plusieurs jours
`npm run setup` 400s créant le planificateur, nommant `multiagent`	l'organisation n'est pas inscrite à la mise à jour Managed Agents qui apporte les rosters coordinateurs	utilisez une copie monoagent (supprimez la ligne `multiagent` dans `setup/create.ts`) jusqu'à ce que l'organisation soit inscrite
chaque appel NPS 403s avec injection de header activée	la clé National Park Service elle-même est mauvaise	relancez l'étape 1 curl depuis votre machine
`session.error` `credential_host_unreachable_error`	la credential permet un hôte que la mise en réseau de l'environnement ne permet pas	les deux listes `allowed_hosts` doivent nommer l'hôte du fournisseur
le chat se réinitialise à un voyage vide après un teardown	le cookie pointait vers une session archivée, donc une nouvelle a été créée	attendu : les sessions archivées ne peuvent pas recevoir un autre message

Réinitialiser

npm run teardown            # archivez les sessions, les deux agents, le vault, les credentials, l'environnement
npm run setup -- --force    # provisionnez une copie fraîche