develop-ai-functions-example

Exemples de fonctions IA

Le répertoire examples/ai-functions/ contient des scripts pour valider, tester et itérer sur les fonctions du SDK IA entre les fournisseurs.

Catégories d'exemples

Les exemples sont organisés par fonction du SDK IA dans examples/ai-functions/src/ :

Convention de nommage des fichiers

Les exemples suivent le modèle : {provider}-{feature}.ts

Structure des exemples

Tous les exemples utilisent le wrapper run() de lib/run.ts qui :

• Charge les variables d'environnement à partir de .env
• Fournit la gestion des erreurs avec un logging détaillé des erreurs API

Template de base

import { providerName } from '@ai-sdk/provider-name';
import { generateText } from 'ai';
import { run } from '../lib/run';

run(async () => {
  const result = await generateText({
    model: providerName('model-id'),
    prompt: 'Your prompt here.',
  });

  console.log(result.text);
  console.log('Token usage:', result.usage);
  console.log('Finish reason:', result.finishReason);
});

Template de streaming

import { providerName } from '@ai-sdk/provider-name';
import { streamText } from 'ai';
import { printFullStream } from '../lib/print-full-stream';
import { run } from '../lib/run';

run(async () => {
  const result = streamText({
    model: providerName('model-id'),
    prompt: 'Your prompt here.',
  });

  await printFullStream({ result });
});

Template d'appels de tools

import { providerName } from '@ai-sdk/provider-name';
import { generateText, tool } from 'ai';
import { z } from 'zod';
import { run } from '../lib/run';

run(async () => {
  const result = await generateText({
    model: providerName('model-id'),
    tools: {
      myTool: tool({
        description: 'Tool description',
        inputSchema: z.object({
          param: z.string().describe('Parameter description'),
        }),
        execute: async ({ param }) => {
          return { result: `Processed: ${param}` };
        },
      }),
    },
    prompt: 'Use the tool to...',
  });

  console.log(JSON.stringify(result, null, 2));
});

Template de sortie structurée

import { providerName } from '@ai-sdk/provider-name';
import { generateObject } from 'ai';
import { z } from 'zod';
import { run } from '../lib/run';

run(async () => {
  const result = await generateObject({
    model: providerName('model-id'),
    schema: z.object({
      name: z.string(),
      items: z.array(z.string()),
    }),
    prompt: 'Generate a...',
  });

  console.log(JSON.stringify(result.object, null, 2));
  console.log('Token usage:', result.usage);
});

Exécuter les exemples

À partir du répertoire examples/ai-functions :

pnpm tsx src/generate-text/openai.ts
pnpm tsx src/stream-text/openai-tool-call.ts
pnpm tsx src/agent/openai-generate.ts

Quand écrire des exemples

Écrivez des exemples quand :

1. Ajouter un nouveau fournisseur : Créez des exemples basiques pour chaque API supportée (generateText, streamText, generateObject, etc.)

2. Implémenter une nouvelle feature : Démontrez la feature avec au moins un exemple de fournisseur

3. Reproduire un bug : Créez un exemple qui montre le problème pour le débogage

4. Ajouter des options spécifiques au fournisseur : Montrez comment utiliser providerOptions pour les paramètres spécifiques au fournisseur

5. Créer des fixtures de test : Utilisez les exemples pour générer des fixtures de réponses API (voir la skill capture-api-response-test-fixture)

Utilitaires

Le répertoire lib/ contient des utilitaires partagés :

Utiliser les utilitaires print

import { print } from '../lib/print';

// Afficher les objets joliment sans valeurs undefined
print('Result:', result);
print('Usage:', result.usage, { depth: 2 });

Utiliser printFullStream

import { printFullStream } from '../lib/print-full-stream';

const result = streamText({ ... });
await printFullStream({ result }); // Sortie colorée pour texte, tool calls, reasoning

Tools réutilisables

Le répertoire tools/ contient les définitions de tools réutilisables :

import { weatherTool } from '../tools/weather-tool';

const result = await generateText({
  model: openai('gpt-4o'),
  tools: { weather: weatherTool },
  prompt: 'What is the weather in San Francisco?',
});

Bonnes pratiques

1. Gardez les exemples focalisés : Chaque exemple devrait démontrer une feature ou un cas d'usage

2. Utilisez des prompts descriptifs : Rendez clair ce que l'exemple teste

3. Gérez les erreurs gracieusement : Le wrapper run() gère cela automatiquement

4. Utilisez des IDs de modèles réalistes : Utilisez les IDs de modèles réels qui fonctionnent avec le fournisseur

5. Ajoutez des commentaires pour la logique complexe : Expliquez les patterns de code non évidents

6. Réutilisez les tools quand approprié : Utilisez weatherTool ou créez de nouveaux tools réutilisables dans tools/