agent-lab #

Side-by-side agent SDK examples — scenario-first (nest scenario → framework), idiomatic demos, machine-checkable smoke.

Layout #

Path	What
scenarios/<id>/	SDK-agnostic goal + Assert (smoke) + Implementations
scenarios/<id>/<framework>/	Demo for that scenario (index.ts / index.py)
sdks/<framework>/	Package install + stack README (catalog)
scenarios/GAPS.md	Coverage matrix — verified vs linked — pending keys+PASS (linked ≠ done)
scenarios/UNIT-1.md	Start-here CTA → Support graduation (Letta verified spine)
scenarios/UNIT-1-WORKSHOP.md	Facilitator 90–120 min run sheet (same CTA end)
tripwire/	Smoke runner (AGENT_LAB_RESULT / AGENT_LAB_SKIP)
shared/	Env + smoke helpers

Start here #

Finish at Support graduation. Follow the TypeScript Unit-1 spine — then stop:

1. Phase-1 Letta verified: hello → tool-use → streaming → memory → approvals
2. Reply Obligation (verified Letta)
3. Support (verified Letta) ← CTA end / done

Path: scenarios/UNIT-1.md. Workshop run sheet: scenarios/UNIT-1-WORKSHOP.md. Selective smoke: tripwire --playlist unit-1-letta. Citation is optional after Support; computer-use is advanced — not the CTA end.

Done definition (shared): Support green on Letta (support/letta tripwire PASS) is Unit 1 done. Citation is optional after Support; computer-use is advanced. Linked OA / CAS / Managed cells are compare after Unit 1 (linked ≠ verified) — not alternate finishes. Soft-pedal Managed.

Status: only verified cells are smoke-backed. linked — pending keys+PASS means a demo path exists but is not done (keys and/or PASS still needed). See scenarios/GAPS.md. Soft-pedal employer Managed as the teaching lead.

Scenarios #

Scenario	Goal
hello	One prompt → one short reply
tool-use	Trivial add tool → 42
streaming	Incremental turn events
memory	Retain state across reconnect
handoffs	Router → specialist
approvals	Gate sensitive action
mcp	MCP tool server (stub — Phase 2)
sandbox-files	Sandbox file I/O (stub — Phase 2)
skills	Skill packages (stub — Phase 2)

SDK catalog (tiers + Index-only stacks): sdks/README.md.

Language policy #

Prefer TypeScript when the vendor ships an official TS/JS client. Python-only is a constraint (flag in the SDK README).

Tripwire #

cd tripwire && npm install
npx tsx run.ts --scenario hello
npx tsx run.ts --id hello/letta/index.ts
npx tsx run.ts --playlist unit-1-letta   # Unit 1 Letta spine (Support = done)
npx tsx select.ts              # git-diff → affected --id list (no API)

Hobby: do not run bare npx tsx run.ts (full TARGETS matrix burns keys). Demos print AGENT_LAB_RESULT {…} or AGENT_LAB_SKIP {…} (see tripwire/README.md). Freshness: docs/FRESHNESS-AUDIT-2026-10-01.md.

After installing an SDK’s npm deps, run ./scripts/link-scenario-node-modules.sh so scenarios/*/<fw>/ can resolve modules.