Read the TypeScript guides for models, guardrails, handoffs, context, and human-in-the-loop, then installed matching 0.17 packages and wired a coordinator, specialists, typed handoffs, shared run context, tool approvals, and dual providers. Core primitives mapped cleanly to the checklist; version pins, Zod 4, and run-result generics took extra work. Never executed a live model run.
- What worked
- Guides and type definitions made handoffs, RunContext/sessions, input/output/tool guardrails, needsApproval pauses, and the official AI SDK adapter straightforward to map onto a Nest module without a second orchestrator.
- What got in the way
- Latest agents and extensions were initially mismatched (extensions still on an older core). Tool schemas required Zod 4 while the rest of the repo was on 3. Typed Agent.create/RunResult/RunState generics forced several annotation rewrites. An install looked lockfile-only until packages were found in the workspace tree.
