experimental_output with complex interfaces

[rbadillap]

Hello team.

I have the following question. This is my agent:

// Agent Output
export interface ClassificationOutput {
  prompt: Prompt; //  <- type Prompt from "ai"
  context: Context; // <- type Context from local
}


// Agent Settings
export type ClassifierSettings = AgentSettings<
  ToolSet, 
  ClassificationOutput, 
  Partial<ClassificationOutput>
>;

// Agent
export interface Classifier extends Agent<
  ToolSet, 
  ClassificationOutput, 
  Partial<ClassificationOutput>
>

// BasicAgent
class DefaultClassifier
  extends Agent<ToolSet, ClassificationOutput, Partial<ClassificationOutput>>
  implements Classifier

How can I use experimental_output under these conditions?

// option #1
experimental_output: Output.object<ClassificationOutput, PartialObject<ClassificationOutput>>({
  schema: jsonSchema<ClassificationOutput>({ ... })
// ... Module '"ai"' declares 'PartialObject' locally, but it is not exported.ts(2459)

// option #2
experimental_output: Output.object<ClassificationOutput>({ ... })
// ... Type 'Output<ClassificationOutput, PartialObject<ClassificationOutput>>' is not assignable to type 'Output<ClassificationOutput, Partial<ClassificationOutput>>'.

I understand that PartialObject<Prompt> ≠ Partial<Prompt>, but does that mean that I need to use only serializable types right?

// This works!
export interface ClassificationOutput {
  prompt: string;
  context: string;
}

My questions are:

1. Am I over-engineering the approach adding these types for my agent?
2. Should I change the output interface with serializable primitives?
3. The PartialObject parameter is a second (and non-related) issue?

Thank you, just looking for clarification, I'm enjoying this Agent flexibility you guys are introducing here :)

[ahuaiqom]

Hi @rbadillap 👋

Core idea: experimental_output only guarantees JSON-serializable shapes at runtime. Types like Prompt (from ai) or your own classes aren’t serializable, so you should expose a DTO (plain JSON) for the model, then map ↔︎ your richer types in your app.

**What to do

1. Define a JSON DTO schema (e.g. Zod)**

import { z } from "zod";

export const ClassificationOutputSchema = z.object({
  prompt: z.object({
    text: z.string(),
    // add only serializable fields you need from Prompt
  }),
  context: z.object({
    userId: z.string().uuid().optional(),
    locale: z.string().optional(),
    // ...
  })
});

export type ClassificationOutputDTO = z.infer<typeof ClassificationOutputSchema>;
export type ClassificationOutputPartialDTO = Partial<ClassificationOutputDTO>;

2) Use that schema with experimental_output

import { Output } from "ai"; // vercel ai sdk

export const experimental_output = Output.object<
  ClassificationOutputDTO,
  ClassificationOutputPartialDTO
>({
  schema: ClassificationOutputSchema,
  // if your API supports it, pass a partial schema:
  partialSchema: ClassificationOutputSchema.partial(),
});

The library’s PartialObject is an internal/branded type; don’t import it. Instead, give a partial schema (e.g., schema.partial()). If your version doesn’t expose partialSchema, keep a single schema and make your pipeline tolerant to partials, or cast the second generic to Partial<…>.

3) Map DTO ⟷ domain types in your agent

// From model → your rich types
function hydrate(dto: ClassificationOutputDTO): ClassificationOutput {
  return {
    prompt: new Prompt(dto.prompt.text),
    context: makeContext(dto.context),
  };
}

// From domain → DTO (if you ever need to seed the model)
function dehydrate(x: ClassificationOutput): ClassificationOutputDTO {
  return {
    prompt: { text: x.prompt.toString() },
    context: { userId: x.context.userId, locale: x.context.locale },
  };
}

Answers to your questions

1. Am I over-engineering with these types?
Not really—just separate domain types from LLM I/O types. Keep your rich Prompt/Context internally; expose a JSON DTO to the model.

2. Should I change the output interface to primitives?
Yes, for the model-facing interface. Use strings/numbers/arrays/objects only. Re-hydrate to classes after validation.

3. Is PartialObject the real issue?
Partly. It’s an internal type; use a partial Zod schema (or your SDK’s partial option). The deeper issue is that non-serializable types (classes) can’t be enforced by the grammar/validator.

[rbadillap]

Hi @ahuaiqom you are totally right. Thanks for such a great answer!