Structured Output

Examples using security: { mode: "local" } are for trusted local use. Hosted deployments require verified identity and resource authorization.

In plain terms

Ask for a form, not an essay. You pass a Zod schema. The model fills it in. You read result.structured as typed data.

const agent = new Agent({
  name: "sorter",
  model: openai(process.env.OPENAI_MODEL ?? "gpt-6.1-sol"),
  structuredOutput: z.object({
    sentiment: z.enum(["positive", "negative", "neutral"]),
    score: z.number(),
  }),
});

const result = await agent.run("I love this.");
console.log(result.structured);

What is Structured Output?

With structured output, you define a Zod schema that describes the expected shape of the response. Agentium:

Converts the schema to a provider-specific format (e.g., json_schema for OpenAI)
Instructs the LLM to respond in that format
Parses and validates the response against the schema
Exposes the result in RunOutput.structured

Using Zod Schemas

Set structuredOutput in AgentConfig:

import { Agent, openai } from "@agentium/core";
import { z } from "zod";

const SentimentSchema = z.object({
  sentiment: z.enum(["positive", "negative", "neutral"]),
  confidence: z.number().min(0).max(1),
  keywords: z.array(z.string()),
});

const agent = new Agent({
  name: "SentimentAnalyzer",
  model: openai(process.env.OPENAI_MODEL ?? "gpt-6.1-sol"),
  instructions: "Analyze the sentiment of the given text.",
  structuredOutput: SentimentSchema,
});

const result = await agent.run("This product is amazing! Best purchase ever.");
console.log(result.structured);
// { sentiment: "positive", confidence: 0.95, keywords: ["amazing", "best"] }

How It Works

Schema

Define a Zod schema (object, array, nested, etc.).

responseFormat

Agentium converts the schema to the provider’s responseFormat (e.g., { type: "json_schema", schema: {...} }).

LLM

The model is instructed to return valid JSON matching the schema.

Parse & Validate

The raw response is parsed and validated with schema.safeParse(). Invalid output may throw or be handled by the provider.

RunOutput.structured

When structuredOutput is set, the parsed and validated result is available on RunOutput.structured:

const result = await agent.run("Tell me about Paris.");

// result.text — raw text from the model (may be JSON string)
console.log(result.text);

// result.structured — parsed, validated object
console.log(result.structured);
// { name: "Paris", country: "France", population: 2161000, ... }

Example: Sentiment Analysis Agent

import { Agent, openai } from "@agentium/core";
import { z } from "zod";

const SentimentSchema = z.object({
  sentiment: z.enum(["positive", "negative", "neutral"]),
  confidence: z.number().min(0).max(1).describe("Confidence score 0-1"),
  keywords: z.array(z.string()).describe("Key phrases that influenced the sentiment"),
});

const agent = new Agent({
  name: "SentimentAnalyzer",
  model: openai(process.env.OPENAI_MODEL ?? "gpt-6.1-sol"),
  instructions: `Analyze the sentiment of the given text.
Return valid JSON matching the schema.`,
  structuredOutput: SentimentSchema,
  logLevel: "info",
});

const result = await agent.run(
  "The service was slow and the staff was rude. Very disappointed."
);

console.log(result.structured);
// {
//   sentiment: "negative",
//   confidence: 0.92,
//   keywords: ["slow", "rude", "disappointed"]
// }

Example: City Info with Rich Schema

const CityInfoSchema = z.object({
  name: z.string(),
  country: z.string(),
  population: z.number().describe("Approximate population"),
  landmarks: z.array(z.string()).describe("Famous landmarks"),
  bestTimeToVisit: z.string(),
});

const agent = new Agent({
  name: "CityInfo",
  model: openai(process.env.OPENAI_MODEL ?? "gpt-6.1-sol"),
  instructions: "Provide city information. Always respond with valid JSON.",
  structuredOutput: CityInfoSchema,
});

const result = await agent.run("Tell me about Paris, France.");
console.log(JSON.stringify(result.structured, null, 2));

Structured Output in Express / Swagger

When you expose an agent with structuredOutput via Express, Agentium automatically generates a typed response schema in the OpenAPI spec. Swagger UI will display the exact shape of the structured field — consumers of your API see the full contract without extra documentation.

import express from "express";
import { Agent, openai } from "@agentium/core";
import { createAgentRouter } from "@agentium/transport";
import { z } from "zod";

const analyst = new Agent({
  name: "analyst",
  model: openai(process.env.OPENAI_FAST_MODEL ?? "gpt-6-luna"),
  instructions: "Analyze data and provide insights.",
  structuredOutput: z.object({
    summary: z.string(),
    keyPoints: z.array(z.string()),
    confidence: z.number().min(0).max(1),
  }),
});

const app = express();
app.use(express.json());

const router = createAgentRouter({ security: { mode: "local" },
  agents: { analyst },
  swagger: { enabled: true },
});

app.use("/api", router);
app.listen(3000);

The generated OpenAPI spec for POST /api/agents/analyst/run will include:

"structured": {
  "type": "object",
  "properties": {
    "summary": { "type": "string" },
    "keyPoints": {
      "type": "array",
      "items": { "type": "string" }
    },
    "confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    }
  },
  "required": ["summary", "keyPoints", "confidence"]
}

Agents without structuredOutput use the generic RunOutput schema where structured is untyped.

Provider Support

Provider	Support
OpenAI	`responseFormat: { type: "json_schema", schema: {...} }`
Google Gemini	`responseFormat: "json"` with `json_schema`
Anthropic	Structured output via tool use or response format where supported
Vertex AI	`responseFormat: "json"` with `json_schema`
Jev	Only closed fields: `z.enum` → choice, `z.boolean` → noul (`>= 0.5` → `true`), `z.number().min().max()` → score (2–32 integer levels). Free-form strings and open objects throw. See Jev.

Agentium abstracts provider differences. Use a Zod schema and the framework handles the rest.

On Jev, agent.run(input, { questions }) wins over structuredOutput. Skip per-run questions if you want result.structured to parse as the Zod object.

Build

Agent applications

Harness runtime

Teams and workflows

Data and capabilities

Interfaces and jobs

Voice and telephony

Verify and manage

Structured Output

In plain terms

What is Structured Output?

Using Zod Schemas

How It Works

RunOutput.structured

Example: Sentiment Analysis Agent

Example: City Info with Rich Schema

Structured Output in Express / Swagger

Provider Support

​In plain terms

​What is Structured Output?

​Using Zod Schemas

​How It Works

​RunOutput.structured

​Example: Sentiment Analysis Agent

​Example: City Info with Rich Schema

​Structured Output in Express / Swagger

​Provider Support

In plain terms

What is Structured Output?

Using Zod Schemas

How It Works

RunOutput.structured

Example: Sentiment Analysis Agent

Example: City Info with Rich Schema

Structured Output in Express / Swagger

Provider Support