Guide: How to use Structured Outputs in Langbase

A step-by-step guide to use Structured Outputs in Langbase.

What are Structured Outputs?

Structured Outputs is a feature that guarantees responses from language models adhere strictly to your supplied JSON schema. It eliminates the need for ad-hoc validation and reduces the risk of missing or malformed fields by enforcing a schema.

This is particularly useful for applications—like data extraction, generative UI and chain of thoughts where you expect the model's output to be parsed according to a specific structure.

Some benefits include:

Reliable Type-Safety: The model's output is automatically validated against your schema. It ensures that the output is always in the expected format, reducing the need for manual validation.
Explicit Refusals: If the model refuses to perform a request, the error or refusal is returned in a standardized format.
Simpler Prompting: You don't need to include extensive instructions to enforce a particular output format.

Using Structured Outputs in Langbase Pipes

In this guide, we will use Langbase SDK to create a Langbase pipe that uses Structured Outputs.

Step #1Define the JSON Schema

First, you need to define the JSON schema that describes the expected output format. In TypeScript, you can use the zod library to define the schema.

Here is an example of a simple schema that enforces the LLM to do Chain of Thought reasoning for a given math query and return the final answer:

import { z } from 'zod';
import { zodToJsonSchema } from 'zod-to-json-schema';

const MathReasoningSchema = z.object({
	steps: z.array(
		z.object({
			explanation: z.string(),
			output: z.string(),
		}),
	),
	final_answer: z.string(),
});

// Convert the Zod schema to JSON Schema format
const jsonSchema = zodToJsonSchema(MathReasoningSchema, { target: 'openAi' });

Step #2Create the Pipe

Now, we can create a Langbase pipe using the createPipe method from the Langbase SDK. We will pass the JSON schema to this pipe, and the pipe will enforce the model's output to match this schema.

import 'dotenv/config';
import { Langbase } from 'langbase';
import { z } from 'zod';
import { zodToJsonSchema } from 'zod-to-json-schema';

const langbase = new Langbase({
	apiKey: process.env.LANGBASE_API_KEY!,
});

const MathReasoningSchema = z.object({
	steps: z.array(
		z.object({
			explanation: z.string(),
			output: z.string(),
		}),
	),
	final_answer: z.string(),
});

// Convert the Zod schema to JSON Schema format
const jsonSchema = zodToJsonSchema(MathReasoningSchema, { target: 'openAi' });

async function createMathTutorPipe() {
	const pipe = await langbase.pipes.create({
		name: 'math-tutor',
		model: 'openai:gpt-4o',
		messages: [
			{
				role: 'system',
				content:
					'You are a helpful math tutor. Guide the user through the solution step by step.',
			},
		],
		json: true,
		response_format: {
			type: 'json_schema',
			json_schema: {
				name: 'math_reasoning',
				schema: jsonSchema,
			},
		},
	});

	console.log('✅ Math Tutor pipe created:', pipe);
}

createMathTutorPipe();

Step #3Run the Pipe and Validate Output

Once you have created the pipe, you can run it with a math query. The model will respond according to the defined JSON schema. You can validate it with your original Zod schema. This confirms that the output adheres to your structured format.

async function runMathTutorPipe(question: string) {
	const { completion } = await langbase.pipes.run({
		name: 'math-tutor',
		messages: [{ role: 'user', content: question }],
		stream: false,
	});

	// Parse and validate the response using the original Zod schema
	const solution = MathReasoningSchema.parse(JSON.parse(completion));
	console.log('✅ Structured Output Response:', solution);
}

runMathTutorPipe('How can I solve 8x + 22 = -23?');

What happens here:

The pipe is executed with a math problem from the user.
The output is parsed from JSON and validated using MathReasoningSchema.
Any deviation from the expected format will be caught during the Zod validation process, giving you reliable, type-safe structured outputs.

Here is the JSON response we get from our Structured Outputs pipe:

{
    "steps": [
        {
            "explanation": "We start with the original equation.",
            "output": "8x + 22 = -23"
        },
        {
            "explanation": "Subtract 22 from both sides to isolate the term with x.",
            "output": "8x + 22 - 22 = -23 - 22"
        },
        {
            "explanation": "Simplify both sides of the equation after subtraction.",
            "output": "8x = -45"
        },
        {
            "explanation": "Divide both sides by 8 to solve for x.",
            "output": "8x/8 = -45/8"
        },
        {
            "explanation": "Simplify the right side to find the value of x.",
            "output": "x = -45 / 8"
        }
    ],
    "final_answer": "x = -45 / 8"
}

You can find the full code for this example here.

By following this guide, you've leveraged Langbase to build an AI agent that responds with reliable, structured output according to your use case. Join our Discord community to share your builds and get support while innovating with Langbase.

Guides