Anvia Docs

Plan for structured output failures. Models can omit fields, produce invalid values, or return text when you expected data.

1. Retry Extraction Failures

const extractor = new ExtractorBuilder(model, ticketSchema)
  .instructions("Return only fields present in the ticket.")
  .retries(2)
  .build();

Use retries for extraction because the model has one focused job: call the generated submit tool with valid data.

2. Catch Validation Errors

try {
  const ticket = await extractor.extract(rawTicket);
  return ticket;
} catch (error) {
  logger.warn(error, "ticket extraction failed");
  return null;
}

Keep the fallback explicit. Do not silently coerce invalid model output into valid application data.

3. Handle Agent Output Parsing

const response = await agent.prompt("Classify this message.").send();

try {
  return classificationSchema.parse(JSON.parse(response.output));
} catch (error) {
  logger.warn({ output: response.output, error }, "invalid classifier output");
  throw error;
}

If the result drives user-visible or financial behavior, fail closed and ask for another attempt.

4. Make Optional Data Optional

Do not require fields that might not exist in the source text.

const invoiceSchema = z.object({
  invoiceId: z.string(),
  dueDate: z.string().optional(),
  amountDue: z.number().optional(),
});

Use required fields for data your workflow cannot continue without.

Failure Handling

1. Retry Extraction Failures

2. Catch Validation Errors

3. Handle Agent Output Parsing

4. Make Optional Data Optional