Votre première application ChatGPT

Construire une app météo en 30 minutes

La meilleure façon d’apprendre le Apps SDK est de construire quelque chose de concret. Dans cette leçon, vous allez créer une application météo complète qui combine une action (récupérer les données) et un widget (afficher le résultat).

Étape 1 : Définir le manifest

Partez du projet initialisé dans la leçon précédente et mettez à jour votre chatgpt-app.json :

{
  "name": "Météo Express",
  "slug": "meteo-express",
  "description": "Consultez la météo en temps réel avec un affichage visuel",
  "version": "1.0.0",
  "runtime": "node",
  "entry": "src/index.ts",
  "permissions": ["actions", "widgets"]
}

Étape 2 : Créer l’action météo

L’action est le pont entre ChatGPT et une API externe. Ici, nous utilisons une API météo publique.

// src/actions/weather.ts
import { defineAction } from "@openai/apps-sdk";

export const getWeather = defineAction({
  name: "getWeather",
  description: "Récupère les conditions météo actuelles pour une ville",
  parameters: {
    city: {
      type: "string",
      description: "Nom de la ville (ex: Paris, Lyon, Marseille)",
      required: true,
    },
  },
  handler: async ({ city }) => {
    const response = await fetch(
      `https://api.open-meteo.com/v1/forecast?` +
      `latitude=${await getCoords(city)}&current_weather=true`
    );
    const data = await response.json();
    const weather = data.current_weather;

    return {
      city,
      temperature: weather.temperature,
      windSpeed: weather.windspeed,
      condition: interpretWeatherCode(weather.weathercode),
      timestamp: new Date().toISOString(),
    };
  },
});

function interpretWeatherCode(code: number): string {
  const conditions: Record<number, string> = {
    0: "Ciel dégagé",
    1: "Principalement dégagé",
    2: "Partiellement nuageux",
    3: "Couvert",
    45: "Brouillard",
    61: "Pluie légère",
    63: "Pluie modérée",
    65: "Pluie forte",
    71: "Neige légère",
    80: "Averses",
    95: "Orage",
  };
  return conditions[code] ?? "Conditions inconnues";
}

Étape 3 : Créer le widget météo

Le widget affiche les données récupérées par l’action sous forme d’une carte visuelle.

// src/widgets/weather-card.ts
import { defineWidget } from "@openai/apps-sdk";

export const weatherCard = defineWidget({
  name: "weatherCard",
  description: "Affiche les conditions météo d'une ville",
  render: (data) => ({
    type: "card",
    title: `Météo à ${data.city}`,
    content: [
      {
        type: "grid",
        columns: 2,
        items: [
          {
            type: "metric",
            label: "Température",
            value: `${data.temperature}°C`,
            icon: "thermometer",
          },
          {
            type: "metric",
            label: "Vent",
            value: `${data.windSpeed} km/h`,
            icon: "wind",
          },
        ],
      },
      {
        type: "text",
        value: data.condition,
        style: "subtitle",
      },
      {
        type: "text",
        value: `Mis à jour : ${new Date(data.timestamp).toLocaleTimeString("fr-FR")}`,
        style: "caption",
      },
    ],
  }),
});

Étape 4 : Assembler l’application

Le fichier d’entrée connecte les actions et les widgets.

// src/index.ts
import { ChatGPTApp } from "@openai/apps-sdk";
import { getWeather } from "./actions/weather";
import { weatherCard } from "./widgets/weather-card";

const app = new ChatGPTApp({
  slug: "meteo-express",
});

// Enregistrer l'action
app.action("getWeather", getWeather);

// Enregistrer le widget
app.widget("weatherCard", weatherCard);

// Lier l'action au widget : quand getWeather retourne des données,
// elles sont automatiquement affichées via weatherCard
app.flow("showWeather", {
  trigger: "getWeather",
  display: "weatherCard",
});

app.start();

Étape 5 : Tester en local

Le SDK inclut un serveur de développement qui simule l’environnement ChatGPT :

# Lancer le serveur de développement
npx chatgpt-app dev

# Vous verrez :
# ✓ App "Météo Express" démarrée sur http://localhost:3100
# ✓ 1 action enregistrée : getWeather
# ✓ 1 widget enregistré : weatherCard
# ✓ Playground disponible sur http://localhost:3100/playground

Ouvrez le playground dans votre navigateur. Vous disposez d’une interface qui simule ChatGPT. Tapez « Quelle est la météo à Lyon ? » et observez :

1. Le modèle détecte l’intention et appelle l’action getWeather
2. Votre handler contacte l’API météo
3. Les données sont passées au widget weatherCard
4. Le widget s’affiche dans la conversation avec les informations formatées

Structure finale du projet

meteo-express/
├── src/
│   ├── index.ts              # Point d'entrée, assemblage
│   ├── actions/
│   │   └── weather.ts        # Action : récupérer la météo
│   └── widgets/
│       └── weather-card.ts   # Widget : afficher la météo
├── chatgpt-app.json
├── tsconfig.json
├── package.json
└── .env

Ce que vous avez appris

Avec cette première app, vous avez mis en pratique les concepts fondamentaux :

• Définir une action avec ses paramètres et son handler
• Créer un widget qui affiche des données structurées
• Lier action et widget via un flow
• Tester en local avec le playground intégré

Points clés à retenir

• Une app ChatGPT minimale nécessite au moins une action ou un widget
• Le pattern action → widget est le flux de base : récupérer puis afficher
• Le playground local simule l’environnement ChatGPT pour tester sans publier
• Les actions reçoivent des paramètres typés et retournent des données structurées
• Les widgets transforment ces données en composants visuels interactifs