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

Running The Agent And Inspecting The Structured Output

With your agent configured, you can now run it and see how the output is shaped according to your custom data model. In JavaScript, you can use the run utility function to execute the agent and receive a structured result.

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);

When you run this code, the agent will return a structured output that matches your TravelRecommendation schema. For example, you might see:

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!"
}

Notice how the output is no longer a block of free-form text, but a well-structured object with clearly labeled fields. This makes it much easier to access specific pieces of information, such as the destination or the travel tip, in your code.

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