# agent-lab

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

## Layout

| Path | What |
| --- | --- |
| [`scenarios/<id>/`](scenarios/) | SDK-agnostic goal + Assert (smoke) + Implementations |
| `scenarios/<id>/<framework>/` | Demo for that scenario (`index.ts` / `index.py`) |
| [`sdks/<framework>/`](sdks/) | Package install + stack README (catalog) |
| [`scenarios/GAPS.md`](scenarios/GAPS.md) | Coverage matrix — **verified** vs **linked — pending keys+PASS** (linked ≠ done) |
| [`scenarios/UNIT-1.md`](scenarios/UNIT-1.md) | Start-here CTA → Support graduation (Letta **verified** spine) |
| [`scenarios/UNIT-1-WORKSHOP.md`](scenarios/UNIT-1-WORKSHOP.md) | Facilitator 90–120 min run sheet (same CTA end) |
| [`tripwire/`](tripwire/) | Smoke runner (`AGENT_LAB_RESULT` / `AGENT_LAB_SKIP`) |
| [`shared/`](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`](scenarios/UNIT-1.md). Workshop run sheet: [`scenarios/UNIT-1-WORKSHOP.md`](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`](scenarios/GAPS.md). Soft-pedal employer Managed as the teaching lead.

## Scenarios

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

SDK catalog (tiers + Index-only stacks): [sdks/README.md](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

```bash
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](tripwire/README.md)). Freshness: [docs/FRESHNESS-AUDIT-2026-10-01.md](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.