Crea un Agente AI per Presentazioni: Guida Completa per Sviluppatori

Gli agenti AI stanno trasformando il modo in cui il software crea contenuti. Un agente AI per presentazioni può generare, personalizzare e consegnare presentazioni professionali (slide deck) come parte di flussi di lavoro automatizzati — dalle pipeline CRM agli strumenti di reporting interno.

Questa guida ti accompagnerà nella creazione di un agente per presentazioni pronto per la produzione utilizzando l'API di 2Slides.

Panoramica dell'Architettura

Un agente per presentazioni segue tipicamente questo flusso:

User Request → Agent Logic → 2Slides API → Poll Job → Deliver Result
                  ↓
           Context Gathering
           (data, templates, brand assets)

Componenti Chiave

Gestore Input — riceve le richieste di presentazione (testo, dati, file)
Costruttore di Contesto — arricchisce le richieste con modelli, informazioni sul brand, dati
Motore di Generazione — chiama l'API di 2Slides per creare le diapositive
Monitoraggio Stato — verifica lo stato del lavoro fino al completamento
Livello di Consegna — restituisce link per il download, invia via email, pubblica su Slack

Per Iniziare

1. Ottieni la Tua Chiave API

Registrati su 2slides.com e crea una chiave API su 2slides.com/api.

2. Installa le Dipendenze

npm install node-fetch dotenv

3. Implementazione Base dell'Agente

import fetch from 'node-fetch';

class PresentationAgent {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://2slides.com/api/v1';
  }

  async generateSlides({ topic, themeId, language = 'en', resolution = '2K' }) {
    // Passaggio 1: Avvia la generazione
    const response = await fetch(`${this.baseUrl}/slides/generate`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        userInput: topic,
        themeId,
        responseLanguage: language,
        resolution,
        mode: 'async'
      })
    });

    const job = await response.json();
    if (!response.ok) throw new Error(job.error || 'Generation failed');

    // Passaggio 2: Verifica lo stato fino al completamento
    return await this.waitForCompletion(job.jobId);
  }

  async waitForCompletion(jobId, maxWait = 300000) {
    const start = Date.now();
    while (Date.now() - start < maxWait) {
      const response = await fetch(`${this.baseUrl}/jobs/${jobId}`, {
        headers: { 'Authorization': `Bearer ${this.apiKey}` }
      });
      const status = await response.json();

      if (status.status === 'success') return status;
      if (status.status === 'failed') throw new Error('Generation failed');

      await new Promise(r => setTimeout(r, 3000));
    }
    throw new Error('Generation timed out');
  }

  async generateFromFile({ fileUrl, prompt, themeId }) {
    const response = await fetch(`${this.baseUrl}/slides/create-pdf-slides`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        fileUrl,
        userInput: prompt,
        themeId,
        mode: 'async'
      })
    });

    const job = await response.json();
    return await this.waitForCompletion(job.jobId);
  }

  async generateWithDesign({ topic, referenceImageUrl, resolution = '2K' }) {
    const response = await fetch(`${this.baseUrl}/slides/create-like-this`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        userInput: topic,
        designStyle: {
          global: { referenceImageUrl }
        },
        resolution,
        mode: 'async'
      })
    });

    const job = await response.json();
    return await this.waitForCompletion(job.jobId);
  }

  async addNarration({ jobId, mode = 'single', voice = 'Charon' }) {
    const response = await fetch(`${this.baseUrl}/slides/generate-narration`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ jobId, mode, voice, contentMode: 'concise' })
    });

    return await response.json();
  }
}

// Utilizzo
const agent = new PresentationAgent('sk-2slides-xxx');

const result = await agent.generateSlides({
  topic: 'Q1 2026 Business Review',
  themeId: 'mckinsey-theme-id',
  resolution: '2K'
});

console.log('Scarica:', result.downloadUrl);

Implementazione Python

import requests
import time

class PresentationAgent:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = 'https://2slides.com/api/v1'
        self.headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json'
        }

    def generate_slides(self, topic, theme_id=None, language='en', resolution='2K'):
        response = requests.post(
            f'{self.base_url}/slides/generate',
            headers=self.headers,
            json={
                'userInput': topic,
                'themeId': theme_id,
                'responseLanguage': language,
                'resolution': resolution,
                'mode': 'async'
            }
        )
        response.raise_for_status()
        job = response.json()
        return self._wait_for_completion(job['jobId'])

    def generate_from_file(self, file_url, prompt, theme_id=None):
        response = requests.post(
            f'{self.base_url}/slides/create-pdf-slides',
            headers=self.headers,
            json={
                'fileUrl': file_url,
                'userInput': prompt,
                'themeId': theme_id,
                'mode': 'async'
            }
        )
        response.raise_for_status()
        job = response.json()
        return self._wait_for_completion(job['jobId'])

    def _wait_for_completion(self, job_id, max_wait=300):
        start = time.time()
        while time.time() - start < max_wait:
            response = requests.get(
                f'{self.base_url}/jobs/{job_id}',
                headers=self.headers
            )
            status = response.json()
            if status['status'] == 'success':
                return status
            if status['status'] == 'failed':
                raise Exception('Generation failed')
            time.sleep(3)
        raise TimeoutError('Generation timed out')

# Utilizzo
agent = PresentationAgent('sk-2slides-xxx')
result = agent.generate_slides('AI Trends 2026', resolution='4K')
print(f"Scarica: {result['downloadUrl']}")

Schemi Avanzati

Schema 1: Generazione Basata su Modelli

Pre-configura i temi per diversi casi d'uso:

const TEMPLATES = {
  'pitch-deck': { themeId: 'apple-id', resolution: '2K' },
  'quarterly-review': { themeId: 'mckinsey-id', resolution: '2K' },
  'training': { themeId: 'corporate-id', resolution: '1K' },
  'social-media': { themeId: 'saul-bass-id', resolution: '4K', aspectRatio: '1:1' },
};

async function generateByType(type, topic) {
  const config = TEMPLATES[type];
  return agent.generateSlides({ topic, ...config });
}

Schema 2: Integrazione con Pipeline di Dati

Connettiti alle tue fonti di dati:

async function weeklyReport(dataSource) {
  // 1. Recupera gli ultimi dati
  const data = await dataSource.getWeeklyMetrics();

  // 2. Formatta come input per la presentazione
  const topic = `Weekly Report: Revenue $${data.revenue}, Users ${data.users}, Churn ${data.churn}%`;

  // 3. Genera le diapositive
  const result = await agent.generateSlides({ topic, themeId: 'mckinsey-id' });

  // 4. Consegna
  await slackBot.postMessage('#team-updates', `Rapporto settimanale pronto: ${result.downloadUrl}`);
}

Schema 3: Output Multi-Formato

Genera diapositive + narrazione + video in un'unica pipeline:

async function fullPresentation(topic) {
  // 1. Genera le diapositive
  const slides = await agent.generateSlides({ topic });

  // 2. Aggiungi narrazione vocale
  await agent.addNarration({ jobId: slides.jobId, mode: 'multi', voice: 'Charon' });

  // 3. Scarica con audio
  const download = await fetch(`${agent.baseUrl}/slides/download-slides-pages-voices`, {
    method: 'POST',
    headers: agent.headers,
    body: JSON.stringify({ jobId: slides.jobId })
  });

  return download.json();
}

Considerazioni per la Produzione

Limiti di Frequenza (Rate Limiting)

Predefinito: 60 richieste/minuto
Gestisci le risposte 429 con backoff esponenziale
Utilizza la modalità asincrona per operazioni batch

Gestione degli Errori

Includi tutte le chiamate API in blocchi try/catch
Implementa una logica di retry per errori transitori
Registra gli ID dei lavori per il debug

Gestione dei Costi

Monitora l'utilizzo dei crediti per generazione
Imposta avvisi di budget nella tua dashboard di 2Slides
Utilizza risoluzioni inferiori per contenuti interni/bozze

Sicurezza

Archivia le chiavi API in variabili d'ambiente, mai nel codice
Utilizza solo chiamate API lato server — non esporre mai le chiavi ai client
Implementa la firma delle richieste per i callback webhook

Domande Frequenti

Posso creare un prodotto SaaS basato sull'API di 2Slides?

Sì — l'API è progettata per l'uso in produzione. Non ci sono restrizioni sulle applicazioni commerciali.

Qual è il limite massimo di generazione concorrente?

L'API gestisce le richieste concorrenti tramite limiti di frequenza (rate limiting). Per esigenze di alto volume, contatta il team di 2Slides per limiti aziendali.

Esiste un webhook per il completamento del lavoro?

Attualmente, utilizza il polling tramite l'endpoint dei lavori. Il supporto per i webhook è in programma (on the roadmap).

Crea il tuo agente per presentazioni — ottieni la tua chiave API su 2Slides e inizia a generare diapositive in modo programmatico.