anthropics Setup walkthrough
Work top to bottom. Every step has a verification before the next one starts.
1. Keys
| key | where | notes |
|---|---|---|
ANTHROPIC_API_KEY |
https://console.anthropic.com/settings/keys | or skip it and sign in once with ant auth login. The org needs Managed Agents access |
NATIONAL_PARK_SERVICE_API_KEY |
https://www.nps.gov/subjects/developer/get-started.htm | free, emailed instantly |
WINDY_API_KEY |
https://api.windy.com/point-forecast/docs | free tier, point-forecast product |
cp .env.example .env.local # then fill in the three keys
Verify the vendor keys from your own machine before involving the 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
Both return JSON. A 403 here is a key problem, not a cookbook problem.
2. Provision
npm install
npm run setup
Creates the environment (networking limited to developer.nps.gov and api.windy.com), the reviewer agent (Opus, review-only prompt), the planner agent (bash on, web_search/web_fetch off, a multiagent coordinator roster naming the reviewer), the vault, and two environment_variable credentials with the injection_location each vendor documents hardcoded (NPS: header, Windy: body). Writes six ROADTRIP_PLANNER_* ids into .env.local. Re-running is a no-op while the agent exists (it does demand --force if the stored planner predates the reviewer roster), and --force provisions a fresh copy.
3. Run
npm run dev
Open http://localhost:3000. The page creates one session per browser on load (cookie roadtrip_planner_session_id), so the sandbox is warm before the first question. Then do the four beats in README.md, in order. Beat 2 is the vault story and it only lands after a real conversation exists. Beat 3 is the agent_with_overrides model picker. Beat 4 is the multi-agent review: it needs a full itinerary ask, not a one-fact question.
Debugging
| symptom | cause | fix |
|---|---|---|
npm run setup 404s on /v1/environments |
org not enrolled in Managed Agents | request access, or switch orgs |
tsc rejects event_deltas, injection_location, or the lib/sessions/accumulate import |
installed SDK predates the 2026-07-01 Managed Agents update | upgrade @anthropic-ai/sdk |
| replies arrive whole, no token-by-token rendering | the org's streaming gate is closed (event_deltas is silently ignored when ungated), or an older SDK's stream parser drops the event_start / event_delta events it does not recognize |
confirm the org is enrolled in the update; upgrade @anthropic-ai/sdk |
| picking a model 400s with "Agent must be a non-empty Agent ID or agent_reference" (or the older "Extra inputs are not permitted") | the org's gate for agent_with_overrides is not open yet (a closed gate rejects the selector as an unknown agent shape) |
use the default model until the org is enrolled in the update |
picking a model 400s with agent_field_not_overridable |
the selector carried a key that is not overridable (the gate is open; only model, system, tools, mcp_servers, skills may be overridden) |
only happens if you edited createTripSession: remove the extra key |
boot screen says Missing ROADTRIP_PLANNER_AGENT_ID |
.env.local not written or dev server started before setup |
run npm run setup, restart npm run dev |
| events arrive only in end-of-turn bursts | a proxy is buffering the SSE response | use next dev directly on localhost first |
| answer cites no tool calls | the agent answered from priors | the prompt demands API evidence per claim: re-run npm run setup -- --force if you weakened it |
| itinerary arrives with no review handoff (no thread events in the rail) | the stored planner predates the reviewer roster (provisioned before the multiagent change), or the question was small enough that the prompt's "skip the review" branch applied | re-run npm run setup -- --force; ask for a full multi-day itinerary |
npm run setup 400s creating the planner, naming multiagent |
the org is not enrolled in the Managed Agents update that ships coordinator rosters | use a single-agent copy (delete the multiagent line in setup/create.ts) until the org is enrolled |
| every NPS call 403s with header injection on | the National Park Service key itself is bad | re-run the step 1 curl from your machine |
session.error credential_host_unreachable_error |
the credential allows a host the environment's networking does not | both allowed_hosts lists must name the vendor host |
| the chat resets to an empty trip after a teardown | the cookie pointed at an archived session, so a fresh one was created | expected: archived sessions cannot take another message |
Reset
npm run teardown # archive sessions, both agents, vault, credentials, environment
npm run setup -- --force # provision a fresh copy