Architecture Decision: Agent Framework Options (Updated with AG-UI)
Date: October 3, 2025 Status: 🚨 DECISION REQUIRED Impact: HIGH - Affects entire agent implementation strategyExecutive Summary
Current State: All agent tools are non-functional due to OpenAI schema validation errors in the Vercel AI SDK’s Zod-to-JSON-Schema converter. NEW DISCOVERY: AG-UI protocol supports staying in TypeScript while getting advanced agent features. Decision Required: Choose between:- Quick Fix - Rewrite tools with explicit JSON Schema (3-5 days)
- AG-UI + TypeScript - Add protocol layer, stay in TypeScript (1 week) ⭐ NEW
- AG-UI + LangGraph + Python - Full Python backend (2-3 weeks)
Current Issues with Vercel AI SDK
Root Cause: Broken Zod-to-JSON-Schema Conversion
The Vercel AI SDK’s internal schema converter produces invalid schemas that OpenAI rejects:Problematic Patterns (ALL FAIL):
- ❌
.optional()on nested objects - ❌
.partial()modifier - ❌
.passthrough()modifier - ❌
z.union([complexObject, z.null()])for optional complex types - ❌ Objects with all optional fields
Tools Affected (10 total):
Complex Tools:update_workspace_context- Workspace focus managementrecord_agent_draft- Draft change proposalsemit_agent_insight- Insight notificationsapply_agent_draft- Apply approved drafts
spreadsheet_set_cell,spreadsheet_get_cell,spreadsheet_set_formulaspreadsheet_select_range,spreadsheet_insert_row,spreadsheet_analyze
Option 1: Fix Vercel AI SDK (Quick Workaround)
Approach
Rewrite all tool schemas using explicit JSON Schema withjsonSchema() from the ‘ai’ package:
Pros ✅
- Fastest implementation - 3-5 days
- Minimal architectural change - Keep existing Next.js/Vercel infrastructure
- Known framework - Team already familiar with Vercel AI SDK
- Type safety - Can maintain TypeScript types alongside JSON Schema
Cons ❌
- Manual schema maintenance - Must maintain Zod AND JSON Schema separately
- Verbose syntax - JSON Schema is more verbose than Zod
- Future vulnerability - Vercel AI SDK may have other conversion issues
- No advanced features - No state graphs, validation nodes, retry logic
- Technical debt - Workaround for a fundamental SDK issue
Effort Estimate
- Schema rewrite: 2 days (10 tools × ~2 hours each with testing)
- Testing & validation: 1 day
- Documentation: 1 day
- Total: 3-5 days
Option 2: AG-UI + TypeScript (⭐ RECOMMENDED)
What is AG-UI?
AG-UI (Agent-User Interaction Protocol) is a framework-agnostic protocol for building collaborative agent experiences with bidirectional state synchronization. Key Discovery: You can use AG-UI in TypeScript without switching to Python!Architecture
Implementation Example
1. Install AG-UI TypeScript SDK
2. Define Tools with AG-UI (Backend)
3. Frontend Integration with AG-UI
Pros ✅
- Stay in TypeScript - No Python needed ✅
- Avoid Zod issues - Use AG-UI Tool type with JSON Schema directly ✅
- Bidirectional state sync - Agent and UI share state via AG-UI protocol ✅
- Keep Next.js infrastructure - No new backend service ✅
- Framework agnostic - Can migrate to other backends later ✅
- Event-driven architecture - Clean separation of concerns ✅
- Vercel AI SDK compatibility - Use Data Stream Protocol ✅
Cons ❌
- New protocol to learn - AG-UI is relatively new ⚠️
- Manual tool conversion - Need helper to convert AG-UI → Vercel format ⚠️
- Still manual schemas - JSON Schema is verbose (but only defined once) ⚠️
- Limited advanced features - No state graphs/validation nodes (Python has this) ⚠️
Effort Estimate
- Install AG-UI SDK: 1 hour
- Setup Data Stream with AG-UI events: 1 day
- Rewrite 10 tools with AG-UI Tool type: 2 days
- Frontend integration with AG-UI client: 1 day
- Testing & debugging: 1 day
- Total: ~1 week
Option 3: AG-UI + LangGraph + Python
Architecture
Implementation Example
Pros ✅
- No schema conversion issues - Pydantic is battle-tested ✅
- Advanced state management - State graphs, checkpointing, time-travel ✅
- Built-in validation - Validation nodes with retry logic ✅
- Production-ready - LangChain/LangGraph used by thousands ✅
- Better debugging - LangSmith observability ✅
- AG-UI protocol - Bidirectional state sync ✅
- Python ecosystem - Access to ML/data libraries ✅
Cons ❌
- Longest timeline - 2-3 weeks ❌
- New stack - Team needs to learn Python/FastAPI/LangGraph ❌
- Deployment complexity - Need to deploy Python backend ❌
- Dual codebase - Next.js + FastAPI ❌
Effort Estimate
- FastAPI setup + LangGraph config: 3 days
- Tool migration (10 tools): 5 days
- AG-UI protocol integration: 2 days
- Frontend integration: 3 days
- Testing & debugging: 2 days
- Total: 2-3 weeks
Decision Matrix
| Criteria | Option 1: Vercel Fix | Option 2: AG-UI + TS | Option 3: AG-UI + Python |
|---|---|---|---|
| Implementation Time | 3-5 days ✅ | ~1 week ✅ | 2-3 weeks ❌ |
| Stay in TypeScript | Yes ✅ | Yes ✅ | No ❌ |
| Schema Reliability | Workaround ⚠️ | Solid ✅ | Battle-tested ✅ |
| Bidirectional State | Manual ❌ | AG-UI ✅ | AG-UI ✅ |
| State Graphs | No ❌ | No ❌ | Yes ✅ |
| Validation Nodes | No ❌ | No ❌ | Yes ✅ |
| Team Learning Curve | None ✅ | Small ✅ | Significant ❌ |
| Deployment | Existing ✅ | Existing ✅ | New service ❌ |
| Future Scalability | Limited ⚠️ | Good ✅ | Excellent ✅ |
| Technical Debt | High ❌ | Low ✅ | None ✅ |
Recommendation: Option 2 (AG-UI + TypeScript) ⭐
Why This is the Sweet Spot
- Solves the schema problem - Use AG-UI Tool type with JSON Schema, avoid Zod entirely
- Stays in TypeScript - No Python backend needed
- Gets modern features - Bidirectional state sync via AG-UI protocol
- Quick to implement - ~1 week vs 2-3 weeks for Python
- Future-proof - Can migrate to LangGraph later if needed (AG-UI supports both)
- Low risk - Keep existing Next.js infrastructure
Migration Path
Week 1: AG-UI + TypeScript Implementation
Day 1: Setup- Install
@ag-ui/coreand@ag-ui/client - Setup Data Stream Protocol in
/api/agent - Emit basic AG-UI events (STATE_UPDATE)
- Rewrite 10 tools using AG-UI Tool type (JSON Schema)
- Create helper to convert AG-UI tools → Vercel format
- Test each tool individually
- Replace
useChatwith AG-UI client hooks - Subscribe to STATE_UPDATE events
- Update UI components to use shared state
- End-to-end testing
- Fix any edge cases
- Documentation
Next Steps (If Choosing Option 2)
- I’ll install AG-UI TypeScript SDK packages
- Create a proof of concept with 1 tool (
spreadsheet_set_cell) - Show bidirectional state sync working
- Once proven, migrate remaining 9 tools
- Update frontend to use AG-UI client
Alternative Paths
If Python is Acceptable: Option 3
- Best long-term architecture
- Advanced state management
- Production-ready from day 1
- Worth the 2-3 week investment
If Need Quick Win: Option 1
- Get 3 spreadsheet tools working in 2 days with
jsonSchema() - Accept technical debt
- Plan proper migration for next sprint
User Context Alignment
Based on your interest in AG-UI protocol and the question “doesn’t have to be langgraph”: ✅ Option 2 (AG-UI + TypeScript) perfectly aligns with your needs:- Get AG-UI protocol benefits ✅
- Stay in TypeScript (no Python) ✅
- Bidirectional state sync ✅
- Reasonable timeline (~1 week) ✅
- Future flexibility (can migrate to LangGraph later) ✅
Resources
AG-UI Protocol (TypeScript)
Vercel AI SDK Integration
AG-UI + LangGraph (Python)
Decision Owner: Product/Engineering Lead Recommended Decision: Option 2 (AG-UI + TypeScript) Timeline: Decide within 24 hours to maintain momentum