Structuring and Type-Checking Agent Outputs with Zod

Introduction & Context

Welcome back! In the last lesson, you learned how to inspect the result object after running an OpenAI agent in JavaScript. You explored how to access the agent's final output, review the original input, see which agent produced the answer, and analyze the step-by-step reasoning and raw responses. This knowledge is essential for understanding and debugging your agent's behavior. As you continue building more advanced agent applications, you will often need the agent's output to follow a specific structure. For example, you might want the agent to always return an object with certain fields or to produce output that can be easily parsed and used in other parts of your program. Relying on free-form text can make downstream processing difficult and error-prone. In this lesson, you will learn how to use the outputType parameter to shape and type-check your agent's outputs. This will help you ensure that the agent's responses are always consistent and easy to work with, making your applications more reliable and easier to maintain.

Understanding The outputType Parameter

The outputType parameter allows you to specify the exact format you want the agent's output to follow. While the OpenAI Agents SDK accepts both JSON Schema-compatible objects and Zod schemas, Zod is the recommended approach for JavaScript/TypeScript projects. Zod provides several advantages: Full type inference and runtime validation Detailed error messages A more ergonomic API for JavaScript/TypeScript developers Automatic type generation for TypeScript users When you set the outputType parameter with a Zod schema, the agent will try to produce responses that match the structure you define. The SDK will then validate the agent's output against this schema, ensuring that the data is well-formed. This is especially useful when you want to automate tasks or integrate the agent's output into other systems. For example, if you want your agent to always return a travel recommendation with a destination, a reason, and a topTip, you can define this structure as a Zod schema and use it as the outputType . The SDK will then guarantee that the agent's output matches this structure, making it much easier to process and debug. By using outputType, you reduce the risk of unexpected output formats, which can cause errors in your application. It also makes it easier to catch mistakes early, since the SDK will throw an error if the output does not match the expected type.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Shell

npm install zod
# or
yarn add zod

npm install zod
# or
yarn add zod

JavaScript

import { z } from 'zod';

// Define a Zod schema for the desired output format
const TravelRecommendation = z.object({
  destination: z.string().describe('The recommended travel destination.'),
  reason: z.string().describe('Why this destination is great for the user.'),
  topTip: z.string().describe('A top travel tip for this destination.')
});

import { z } from 'zod';

// Define a Zod schema for the desired output format
const TravelRecommendation = z.object({
  destination: z.string().describe('The recommended travel destination.'),
  reason: z.string().describe('Why this destination is great for the user.'),
  topTip: z.string().describe('A top travel tip for this destination.')
});

JavaScript

import { Agent } from '@openai/agents';

// Define the agent with a specific output type
const agent = new Agent({
  name: 'Travel Genie',
  instructions:
    'You are Travel Genie, a friendly and knowledgeable travel assistant. ' +
    'Recommend exciting destinations and offer helpful travel tips.',
  model: 'gpt-5.6-terra',
  modelSettings: { reasoning: { effort: 'none' } },
  outputType: TravelRecommendation
});

import { Agent } from '@openai/agents';

// Define the agent with a specific output type
const agent = new Agent({
  name: 'Travel Genie',
  instructions:
    'You are Travel Genie, a friendly and knowledgeable travel assistant. ' +
    'Recommend exciting destinations and offer helpful travel tips.',
  model: 'gpt-5.6-terra',
  modelSettings: { reasoning: { effort: 'none' } },
  outputType: TravelRecommendation
});

JavaScript

import { run } from '@openai/agents';

// Run the agent
const result = await run(
  agent,
  'Suggest a once-in-a-lifetime hiking destination.'
);

// Print the agent's final output
console.log(result.finalOutput);

import { run } from '@openai/agents';

// Run the agent
const result = await run(
  agent,
  'Suggest a once-in-a-lifetime hiking destination.'
);

// Print the agent's final output
console.log(result.finalOutput);

JSON

{
  "destination": "Torres del Paine National Park, Patagonia, Chile",
  "reason": "Torres del Paine is renowned for its breathtaking mountain landscapes, turquoise glacial lakes, and dramatic granite towers. It's considered one of the world's most spectacular hiking destinations, offering unforgettable trekking circuits like the W and O routes.",
  "topTip": "Pack for unpredictable weather — Patagonia is famous for experiencing all four seasons in a single day. Layering clothes and a good rain jacket are essential!"
}

{
  "destination": "Torres del Paine National Park, Patagonia, Chile",
  "reason": "Torres del Paine is renowned for its breathtaking mountain landscapes, turquoise glacial lakes, and dramatic granite towers. It's considered one of the world's most spectacular hiking destinations, offering unforgettable trekking circuits like the W and O routes.",
  "topTip": "Pack for unpredictable weather — Patagonia is famous for experiencing all four seasons in a single day. Layering clothes and a good rain jacket are essential!"
}

JavaScript

if (result.finalOutput) {
  // Access specific fields
  console.log('Destination:', result.finalOutput.destination);
  console.log('Reason:', result.finalOutput.reason);
  console.log('Top Tip:', result.finalOutput.topTip);
}

if (result.finalOutput) {
  // Access specific fields
  console.log('Destination:', result.finalOutput.destination);
  console.log('Reason:', result.finalOutput.reason);
  console.log('Top Tip:', result.finalOutput.topTip);
}

text

Destination: Torres del Paine National Park, Patagonia, Chile
Reason: Torres del Paine is renowned for its breathtaking mountain landscapes, turquoise glacial lakes, and dramatic granite towers. It's considered one of the world's most spectacular hiking destinations, offering unforgettable trekking circuits like the W and O routes.
Top Tip: Pack for unpredictable weather — Patagonia is famous for experiencing all four seasons in a single day. Layering clothes and a good rain jacket are essential!

Destination: Torres del Paine National Park, Patagonia, Chile
Reason: Torres del Paine is renowned for its breathtaking mountain landscapes, turquoise glacial lakes, and dramatic granite towers. It's considered one of the world's most spectacular hiking destinations, offering unforgettable trekking circuits like the W and O routes.
Top Tip: Pack for unpredictable weather — Patagonia is famous for experiencing all four seasons in a single day. Layering clothes and a good rain jacket are essential!

Shell

npm install zod
# or
yarn add zod

JavaScript

import { z } from 'zod';

// Define a Zod schema for the desired output format
const TravelRecommendation = z.object({
  destination: z.string().describe('The recommended travel destination.'),
  reason: z.string().describe('Why this destination is great for the user.'),
  topTip: z.string().describe('A top travel tip for this destination.')
});

JavaScript

import { Agent } from '@openai/agents';

// Define the agent with a specific output type
const agent = new Agent({
  name: 'Travel Genie',
  instructions:
    'You are Travel Genie, a friendly and knowledgeable travel assistant. ' +
    'Recommend exciting destinations and offer helpful travel tips.',
  model: 'gpt-5.6-terra',
  modelSettings: { reasoning: { effort: 'none' } },
  outputType: TravelRecommendation
});

JavaScript

import { run } from '@openai/agents';

// Run the agent
const result = await run(
  agent,
  'Suggest a once-in-a-lifetime hiking destination.'
);

// Print the agent's final output
console.log(result.finalOutput);

JSON

{
  "destination": "Torres del Paine National Park, Patagonia, Chile",
  "reason": "Torres del Paine is renowned for its breathtaking mountain landscapes, turquoise glacial lakes, and dramatic granite towers. It's considered one of the world's most spectacular hiking destinations, offering unforgettable trekking circuits like the W and O routes.",
  "topTip": "Pack for unpredictable weather — Patagonia is famous for experiencing all four seasons in a single day. Layering clothes and a good rain jacket are essential!"
}

JavaScript

if (result.finalOutput) {
  // Access specific fields
  console.log('Destination:', result.finalOutput.destination);
  console.log('Reason:', result.finalOutput.reason);
  console.log('Top Tip:', result.finalOutput.topTip);
}

text

Destination: Torres del Paine National Park, Patagonia, Chile
Reason: Torres del Paine is renowned for its breathtaking mountain landscapes, turquoise glacial lakes, and dramatic granite towers. It's considered one of the world's most spectacular hiking destinations, offering unforgettable trekking circuits like the W and O routes.
Top Tip: Pack for unpredictable weather — Patagonia is famous for experiencing all four seasons in a single day. Layering clothes and a good rain jacket are essential!

Introduction & Context

Understanding The outputType Parameter

Join the 1M+ learners on CodeSignal

Creating A Custom Data Model With Zod

Configuring The Agent With The outputType Parameter

Running The Agent And Inspecting The Structured Output

Accessing Specific Properties of the Structured Output

Summary & Next Steps