feat: add structured output support with Zod schema validation #402

mehtarac · 2026-01-13T18:13:06Z

Motivation

Language model outputs are inherently unstructured text, which creates challenges when building applications that need reliable, program-friendly data. Developers must write custom parsing logic, handle validation errors, and manage retry logic when the LLM produces malformed output. This implementation brings structured output functionality from the Python SDK to TypeScript, enabling type-safe, validated responses from LLMs using Zod schemas.

Resolves #111

Public API Changes

AgentConfig - New Option

import { Agent } from '@strands-agents/sdk'
import { z } from 'zod'

const PersonSchema = z.object({
  name: z.string().describe('Full name'),
  age: z.number().describe('Age in years'),
  occupation: z.string().describe('Job title')
})

// Agent with default schema for all invocations
const agent = new Agent({
  structuredOutputModel: PersonSchema
})

const result = await agent.invoke('John Smith is a 30 year-old engineer')
console.log(result.structuredOutput) // { name: "John Smith", age: 30, occupation: "engineer" }

AgentResult - New Field

The AgentResult class now includes an optional structuredOutput field with automatic type inference from the provided Zod schema:

// Type is automatically inferred from schema
const result = await agent.invoke(prompt, {
  structuredOutputModel: PersonSchema
})
// result.structuredOutput has type: z.infer<typeof PersonSchema> | undefined

New Exports

// Exception type for structured output errors
export { StructuredOutputException } from '@strands-agents/sdk'

// Internal types (exported as types only for advanced usage)
export type { StructuredOutputContext, StructuredOutputTool } from '@strands-agents/sdk'

Implementation Overview

Structured output works through a multi-step process integrated into the agent loop:

Schema Registration: When an agent invocation includes a structuredOutputModel, the agent creates a per-invocation context that registers a hidden validation tool with the model
Tool Generation: The Zod schema is converted to a JSON Schema tool specification that guides the LLM to produce correctly structured output
Validation: When the LLM uses the structured output tool, the response is validated against the Zod schema
Two-Phase Storage: Results are stored in temporary storage during tool execution, then extracted after all tools complete (matching Python SDK pattern)
Forced Execution: If the LLM returns without calling the structured output tool, it is forced to call it via toolChoice, ensuring structured output is always returned
Cleanup: The validation tool is automatically removed from the registry after invocation completes (success or failure)

Key Design Decisions

Dynamic Tool Registration: Structured output tools are registered as "dynamic tools" in a separate namespace within ToolRegistry. They're included in model tool specifications but hidden from the public agent.tools accessor.

Two-Phase Storage Pattern: Matches the Python SDK implementation - results are stored during tool execution (Phase 1) and extracted after all tools complete (Phase 2). This enables proper result handling when multiple tools are used in a single turn.

Forced Tool Execution: When the LLM returns end_turn without calling the structured output tool, the agent forces the model to call it using toolChoice: { tool: { name: 'StructuredOutput' } }. This guarantees structured output is always returned when a schema is provided.

Per-Invocation Lifecycle: Each agent invocation creates its own StructuredOutputContext instance, enabling concurrent invocations with different schemas.

Use Cases

API Response Parsing: Extract structured data from API documentation, error messages, or unstructured API responses
Data Extraction: Pull specific fields from documents, emails, or natural language descriptions
Form Validation: Convert natural language form inputs into validated, typed data structures
Multi-Step Workflows: Ensure each step produces validated output before proceeding to the next step

Implement structured output functionality that enables type-safe, validated responses from LLMs using Zod schemas. Includes automatic validation retry logic and seamless agent integration. Key changes: - Add StructuredOutputContext for per-invocation lifecycle management - Implement StructuredOutputTool with Zod validation and error formatting - Enhance ToolRegistry with dynamic tool registration - Add structuredOutput field to AgentResult with type inference - Add structuredOutputSchema to AgentConfig - Update documentation with usage examples - Create structured-output example Resolves #111

src/agent/agent.ts

src/structured_output/structured_output_utils.ts

src/registry/tool-registry.ts

src/agent/agent.ts

…output Address PR review feedback: - Rename structuredOutputSchema to structuredOutputModel (Python SDK naming convention) - Rename schema_converter.ts to structured_output_utils.ts - Rename publicTool variable to registeredTool - Remove verbose JSDoc comment Implement two-phase storage pattern matching Python SDK: - Phase 1 (Store): Results stored in temporary storage during tool execution - Phase 2 (Extract): Results extracted after all tools execute - Add hasResult(), extractResult(), getToolName() methods to context Add forced tool execution for guaranteed structured output: - Add _forcedToolChoice field to Agent - Force structured output tool when LLM returns without calling it - Pass toolChoice to model via StreamOptions - Clear forced tool choice after successful execution This ensures structuredOutput is always returned when a schema is provided, matching the Python SDK's guaranteed result behavior.

src/structured_output/exceptions.ts

- Remove validationErrors, toolName, toolUseId fields - Exception now only has message (like Python SDK) - Raised only when LLM refuses to call tool after being forced - Add forceAttempted tracking in agent loop - Throw exception when forced execution fails - Update tests for simplified exception class

src/agent/agent.ts

zastrowm · 2026-01-14T17:56:03Z

src/agent/agent.ts

        const toolResultMessage = yield* this.executeTools(modelResult.message, this._toolRegistry)

+        // Extract structured output result AFTER all tools execute (two-phase pattern)
+        if (context) {


Instead of possibly having undefined, let's use the null object pattern - a context that does nothing if we didn't have a schema; that will clean up the code and make it more clear I think

Done! Implemented null object pattern with NullStructuredOutputContext and factory function createStructuredOutputContext(). The agent code no longer has if (context) checks.

src/registry/tool-registry.ts

zastrowm · 2026-01-14T18:04:17Z

src/types/agent.ts

+   * The validated structured output from the LLM, if a schema was provided.
+   * Type is inferred from the Zod schema using z.infer.
+   */
+  readonly structuredOutput?: T | undefined


The | undefined seems odd given that it's optional on ?

The | undefined is actually required due to exactOptionalPropertyTypes: true in tsconfig. Without it, TypeScript throws an error when assigning undefined to the field.

When would we ever assign undefined to this field? Shouldn't that be prevented?

zastrowm · 2026-01-14T18:05:03Z

src/structured_output/__tests__/structured_output_tool.test.ts

+      expect(tool.name).toBe('PersonSchema')
+    })
+
+    it('includes structured output description', () => {


We should be able to assert on the entire description string exactly

Done! Updated tests to assert on entire objects with exact values including inputSchema, error messages, etc.

zastrowm · 2026-01-14T18:05:20Z

src/structured_output/__tests__/structured_output_tool.test.ts

+    })
+
+    it('includes input schema from Zod schema', () => {
+      expect(tool.toolSpec.inputSchema).toBeDefined()


Expect that the entire inputSpec is exactly as we expect it

Done! Tests now assert the complete toolSpec object including additionalProperties: false in the inputSchema.

zastrowm · 2026-01-14T18:05:49Z

src/structured_output/__tests__/structured_output_tool.test.ts

+        expect(result.value.content).toHaveLength(1)
+
+        const errorContent = result.value.content[0] as any
+        expect(errorContent.text).toContain('Validation failed')


Again, assert on the entire object; everything is deterministic so let's not just check contains

Done! Updated to use exact string matching for error messages.

zastrowm · 2026-01-14T18:07:05Z

src/structured_output/structured_output_context.ts

+ * 1. Phase 1 (Store): During tool execution, results are stored in temporary storage
+ * 2. Phase 2 (Extract): After all tools execute, the result is extracted from temporary storage
+ */
+export class StructuredOutputContext {


Out of curiosity, could we just merge StructuredOutputTool and this class? E.g. can we just use the tool?

I considered this but kept them separate because: 1) The context manages the two-phase storage and tool lifecycle, 2) The tool handles validation and result storage per-invocation, 3) The null object pattern requires the interface/context separation. Could merge them but the responsibilities feel cleanly separated. Happy to refactor if you prefer.

mehtarac · 2026-01-14T18:13:03Z

/strands implement

Address zastrowm's review feedback: Agent changes: - Pass toolChoice as parameter to invokeModel instead of class field - Move BeforeInvocationEvent before tool registration - Clear forcedToolChoice after use, not as class field cleanup StructuredOutputContext changes: - Make schema required (not optional) - Add extractResultFromMessage() to encapsulate toolUseIds extraction - Remove unnecessary temporaryStorage.clear() in cleanup ToolRegistry changes: - Remove dynamic tools functionality - Use regular add()/removeByName() for structured output tool - Simplify getToolsForModel() to just return values() Tests: - Update context tests to use extractResultFromMessage - Update tool tests to use instanceof checks instead of exact object matching - Remove tests for removed functionality

mehtarac · 2026-01-14T19:01:27Z

/strands implement
Ensure all the comments have replies, the suggestions are addressed and that the code is functional.

…act test assertions Address remaining review feedback: Null object pattern: - Add IStructuredOutputContext interface - Add NullStructuredOutputContext (no-op implementation) - Add createStructuredOutputContext() factory function - Agent now uses context without undefined checks (cleaner code) Cleanup: - Remove examples/structured-output directory (defer to maintainer on location) - Remove structured_output/index.ts (export directly from files) - Update src/index.ts with direct exports Tests: - Update tool tests to assert on exact objects (inputSchema, error messages) - Add NullStructuredOutputContext tests - Add createStructuredOutputContext tests

zastrowm · 2026-01-14T19:19:34Z

src/agent/agent.ts

+      yield new BeforeInvocationEvent({ agent: this })
+
+      // Register structured output tool (no-op if null context)
+      context.registerTool(this._toolRegistry)


Where is it removed from the registry and do we have a test verifying that?

zastrowm · 2026-01-14T19:21:10Z

src/agent/agent.ts

        // Continue loop
      }
    } finally {
+      // Always cleanup structured output context (no-op for null context)


Remove comments about "no-op for null contexts"; that's an implementation detail that we don't need here

Same for above

zastrowm · 2026-01-14T19:22:24Z

src/agent/agent.ts

        currentArgs = undefined // Only pass args on first invocation
+        forcedToolChoice = undefined // Clear after use
+
        if (modelResult.stopReason !== 'toolUse') {


Is modelResult.stopReason !== 'toolUse' but forceAttempted something we should be handling here?

zastrowm · 2026-01-14T19:23:50Z

src/agent/agent.ts

-        const modelResult = yield* this.invokeModel(currentArgs)
+        const modelResult = yield* this.invokeModel(currentArgs, forcedToolChoice)
        currentArgs = undefined // Only pass args on first invocation
+        forcedToolChoice = undefined // Clear after use


Is there ever a case where forceAttempted is true but forcedToolChoice is undefined?

If not, can forceAttempted just be substituted by forcedToolChoise != undefined

zastrowm · 2026-01-14T19:24:21Z

src/agent/agent.ts

+            const toolName = context.getToolName()
+            forcedToolChoice = { tool: { name: toolName } }
+            forceAttempted = true
+            // Continue loop without adding messages (don't re-add user message)


What does "don't re-add user message" mean here?

zastrowm · 2026-01-14T19:25:03Z

src/agent/agent.ts

    }

-    const toolSpecs = this._toolRegistry.values().map((tool) => tool.toolSpec)
+    const toolSpecs = this._toolRegistry.getToolsForModel().map((tool) => tool.toolSpec)


getToolsForModel isn't something that needs to exist I think?

zastrowm · 2026-01-14T19:27:00Z

src/structured_output/structured_output_utils.ts

+ * @returns JSON Schema representation of the Zod schema
+ * @throws StructuredOutputException if the schema contains unsupported features
+ */
+export function convertSchemaToJsonSchema(schema: z.ZodSchema): JSONSchema {


Re-use the same logic as ZodTool or re-use ZodTool; I'm mostly concerned about having different logic for ZodTool and structured_output

zastrowm · 2026-01-14T19:27:20Z

src/structured_output/structured_output_utils.ts

+  }
+
+  // Convert to JSON Schema using Zod v4's built-in toJSONSchema
+  const result = z4mini.toJSONSchema(schema, { target: 'draft-7' }) as JSONSchema & { $schema?: string }


Yes consolidate; we should not have separate logic for this

zastrowm · 2026-01-14T19:27:40Z

src/types/agent.ts

+   * The validated structured output from the LLM, if a schema was provided.
+   * Type is inferred from the Zod schema using z.infer.
+   */
+  readonly structuredOutput?: T | undefined


When would we ever assign undefined to this field? Shouldn't that be prevented?

strands-agent added 3 commits January 8, 2026 15:42

Additional changes from write operations

95c738d

Additional changes from write operations

b8df58e

mehtarac temporarily deployed to auto-approve January 13, 2026 18:13 — with GitHub Actions Inactive

zastrowm marked this pull request as draft January 13, 2026 18:29