Agent SDK vs Messages API: Architecture Decision Prompt

project_brief: Customer-support agent that reads Zendesk tickets, pulls order data from our Postgres, drafts replies, and asks a human for approval on refunds > $100. hard_constraints: HIPAA-adjacent PII, p95 < 8s, must run in our VPC. team_size: 3 engineers. experience_level: Mid. Built 2 Claude apps on Messages API. deadline: 6 weeks.

Recommendation: Messages API + a thin orchestration layer (NOT Agent SDK) for v1. Matrix: tool-use complexity 3/5 (only 2 tools), multi-step 2/5 (mostly linear), context control 5/5 (PII demands explicit redaction), observability 5/5 (HIPAA-adjacent = full prompt/response audit), streaming 4/5 (UX wants token streaming for drafts), team ramp 4/5 (already fluent on Messages API). The SDK's implicit context handling is a liability here — every token into the model must be provably redacted. Risks of choosing Agent SDK instead: (1) opaque context window assembly complicates the audit trail, (2) built-in tool loop makes p95 harder to enforce, (3) your team loses 1-2 weeks learning the abstraction with a 6-week deadline. Spike plan: Week 1 — Messages API skeleton + PII redactor + Postgres tool + Zendesk tool behind a feature flag, all traces shipped to Datadog. Week 2 — human-in-loop refund approval flow + eval harness with 50 real tickets, target 90% draft acceptance. Revisit the decision when: you add a 4th tool OR multi-turn planning is needed OR token cost per ticket exceeds $0.08.