> ## Documentation Index
> Fetch the complete documentation index at: https://ai.aidalinfo.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Sorties structurées

> Valider les réponses de vos agents avec Zod et `structuredOutput`.

Utilisez `structuredOutput` pour contraindre l’agent à respecter un schéma `zod`. Appuyez-vous systématiquement sur `Output.object({ schema: z.object(...) })` pour fournir les bonnes indications aux modèles OpenAI/Google et récupérer un typage automatique.

```ts theme={null}
import { Output } from "@ai_kit/core";
import { z } from "zod";

const personSpec = Output.object({
  schema: z.object({
    name: z.string(),
    age: z.number().nullable().describe("Âge de la personne."),
    contact: z.object({
      type: z.literal("email"),
      value: z.string(),
    }),
    occupation: z.object({
      type: z.literal("employed"),
      company: z.string(),
      position: z.string(),
    }),
  }),
});

const structured = await assistant.generate({
  prompt: "Crée un profil de test pour un client potentiel.",
  structuredOutput: personSpec,
});

console.log(structured.experimental_output);
// -> { name: "...", age: 32, contact: { ... }, occupation: { ... } }
```

* `Output.object` fournit une syntaxe fluide pour décrire la réponse attendue.
* Les descriptions du schéma sont transmises au modèle pour améliorer la précision.
* En cas de parsing invalide, le SDK lève une exception que vous pouvez intercepter.

## Extraction ciblée

```ts theme={null}
import { Agent, Output } from "@ai_kit/core";
import { z } from "zod";
import { google } from "@ai-sdk/google";

const siretOutput = Output.object({
  schema: z.object({
    siret: z
      .string()
      .length(14, "Le SIRET doit contenir exactement 14 chiffres."),
  }),
});

const assistant = new Agent({
  name: "assistant-vie",
  instructions: "Assistant de vie",
  model: google("gemini-2.5-flash"),
  tools: {
    google_search: google.tools.googleSearch({}),
  },
});

const result = await assistant.generate({
  prompt: "Cherche le SIRET de la société Aidalinfo",
  structuredOutput: siretOutput,
});

console.log(result.experimental_output);
// -> { siret: "12345678901234" }
```

## Recommandations

* Préférez `agent.generate` pour la génération structurée : le mode streaming reste expérimental.
* Logguez les erreurs de parsing pour affiner vos prompts ou relancer une tentative.
* Distinguez les sorties « strictes » (identifiants, métadonnées) des contenus libres (résumés, réponses longues).

## Modèles Scaleway

L’API compatible OpenAI de Scaleway applique encore les schémas côté client. La librairie infère désormais automatiquement `AgentStructuredOutput` à partir de votre schéma Zod, vous pouvez donc conserver exactement la même écriture :

```ts theme={null}
import { Agent, Output, scaleway } from "@ai_kit/core";
import { z } from "zod";

const codeSchema = Output.object({
  schema: z.object({
    language: z.string(),
    code: z.string(),
    explanation: z.string(),
  }),
});

const assistant = new Agent({
  name: "code-assistant",
  model: scaleway("qwen3-coder-30b-a3b-instruct"),
});

const result = await assistant.generate({
  prompt: "Produis un snippet Python commenté.",
  structuredOutput: codeSchema,
});
```

`codeSchema` est automatiquement typé comme `AgentStructuredOutput<typeof schema>`, ce qui garantit la compatibilité Scaleway tout en conservant la même DX qu’avec OpenAI/Google.

> Lorsque vous ciblez un provider non-OpenAI **sans outil**, AI Kit appelle désormais directement `generateObject`. Les messages (texte ou image) que vous passez à l’agent suffisent donc pour alimenter `experimental_output`, même sans rappeler au modèle comment formater la réponse.