fix structured output

[anubra266]

No description provided.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 3df3e8a

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
agents-manage-api	Building	Preview, Comment	Jan 6, 2026 8:51pm
agents-manage-ui	Building	Preview, Comment	Jan 6, 2026 8:51pm
agents-run-api	Building	Preview, Comment	Jan 6, 2026 8:51pm

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
agents-docs	Skipped		Jan 6, 2026 8:51pm

[claude]

Claude finished @anubra266's task —— View job

---

Code Review: fix structured output

Comprehensive review completed as a TypeScript Staff Engineer and System Architect.

Review Progress:

• Analyze the changed file and understand the modifications
• Research related code patterns and system context
• Evaluate code quality, architecture, and potential impacts
• Provide detailed feedback and recommendations

Executive Summary

This PR introduces a comprehensive Agent.ts implementation (3,324 lines) that centralizes agent functionality with proper structured output handling. The "fix" appears to be a significant refactor that consolidates agent logic and implements robust model fallback patterns for structured outputs.

Key Strengths

1. Robust Model Configuration Hierarchy ✅

The structured output model resolution follows a clear precedence:

• agents-run-api/src/agents/Agent.ts:372-377: Uses dedicated structuredOutput model when available
• agents-run-api/src/agents/Agent.ts:384-387: Falls back to base model with clear error messaging

2. Well-Architected Two-Phase Generation ✅

• Phase 1: Planning/reasoning with tools (agents-run-api/src/agents/Agent.ts:2265-2315)
• Phase 2: Structured output generation (agents-run-api/src/agents/Agent.ts:2327-2330)
• Smart streaming logic: only streams Phase 1 when structured output needed

3. Comprehensive Error Handling ✅

• agents-run-api/src/agents/Agent.ts:105-110: Centralized model validation with descriptive error messages
• Multiple validation layers for model configuration requirements
• Graceful fallbacks with explicit error messaging

Areas for Consideration

🔶 1. Model Configuration Inconsistency Risk

Issue: The fallback logic assumes base model can always handle structured output tasks.

// agents-run-api/src/agents/Agent.ts:384-387
return {
  model: validateModel(baseConfig.model, 'Base (fallback for structured output)'),
  providerOptions: baseConfig.providerOptions,
};

Concern: Not all base models support structured output (e.g., older GPT-3.5 vs GPT-4). This could lead to runtime failures when structured output is required but base model lacks capability.

Recommendation: Add model capability validation or explicit structured output support flags.

🔶 2. Complex State Management

Issue: The Agent class manages numerous private state variables:

// agents-run-api/src/agents/Agent.ts:196-206
private streamHelper?: StreamHelper;
private streamRequestId?: string;
private conversationId?: string;
private delegationId?: string;
private isDelegatedAgent: boolean = false;
private mcpClientCache: Map<string, McpClient> = new Map();
// ... more state

Concern: High cognitive complexity and potential for state synchronization issues across concurrent operations.

Recommendation: Consider extracting state management into dedicated service classes (e.g., AgentStateManager, McpConnectionManager).

🔶 3. Timeout Configuration Complexity

Issue: Multiple timeout calculations with unclear relationships:

• agents-run-api/src/agents/Agent.ts:2330: Phase 2 timeout calculation
• Different timeouts for streaming vs non-streaming
• Timeout cascading logic across multiple model calls

Concern: Difficult to reason about timeout behavior, especially in nested agent delegations.

Recommendation: Consolidate timeout logic into a TimeoutConfigurationService with clear documentation of timeout hierarchies.

🔶 4. Tool Sanitization Edge Cases

Issue: Runtime tool name sanitization for AI SDK compatibility:

// agents-run-api/src/agents/Agent.ts:286-290
let sanitizedKey = originalKey.replace(/[^a-zA-Z0-9_-]/g, '_');
sanitizedKey = sanitizedKey.replace(/_+/g, '_');

Concern: Sanitization could create naming conflicts (e.g., "tool:name" and "tool-name" both become "tool_name").

Recommendation: Add conflict detection and implement deterministic collision resolution.

⚠️ 5. Missing Input Validation

Issue: Agent configuration accepts broad types without runtime validation:

// agents-run-api/src/agents/Agent.ts:115-145
export type AgentConfig = {
  tools?: McpTool[];
  artifacts?: Record<string, Artifact>;
  // ... other loosely typed fields
}

Concern: Malformed configuration could cause runtime errors deep in execution flow.

Recommendation: Implement configuration schema validation at construction time using Zod or similar.

⚠️ 6. Potential Memory Leaks

Issue: MCP client caching without cleanup:

// agents-run-api/src/agents/Agent.ts:205
private mcpClientCache: Map<string, McpClient> = new Map();
private mcpConnectionLocks: Map<string, Promise<McpClient>> = new Map();

Concern: Long-lived agent instances could accumulate stale connections.

Recommendation: Implement connection cleanup in destructor or add explicit cleanup methods.

System Design Considerations

Model Provider Abstraction

The model selection logic is well-structured but could benefit from a strategy pattern for different provider capabilities. Consider creating a ModelCapabilityService to handle provider-specific structured output support.

Observability

Strong OpenTelemetry integration throughout, but consider adding structured logging for model selection decisions to aid debugging in production.

Extensibility

The two-phase architecture is forward-thinking but may need adjustment as new model capabilities emerge (e.g., native reasoning models that don't need separate phases).

Breaking Changes & Compatibility

Since this is a new file addition, no immediate breaking changes, but the centralized agent logic suggests this may be part of a larger refactoring effort. Ensure existing agent implementations are properly migrated.

Priority Recommendations

1. High: Add model capability validation before fallback to base model
2. High: Implement configuration schema validation
3. Medium: Extract state management into separate services
4. Medium: Add tool name collision detection
5. Low: Implement connection cleanup for MCP clients

Overall, this is a well-architected implementation that addresses the structured output fix comprehensively. The primary concerns center around runtime validation and state management complexity, which are addressable without major architectural changes.

---