Tutorial su OpenAI AgentKit con progetto demo: crea un agente AI

Il nuovo introdotto OpenAI AgentKit è un nuovo toolkit che permette agli sviluppatori di progettare, collegare e distribuire agenti AI tramite un'interfaccia di workflow visiva. Combina l'Agent Builder, ChatKit e integrazioni di tool integrate (come ricerca sul web, GitHub e server MCP) così puoi passare dall'idea a un agente funzionante in modo rapido ed efficiente.

In questa guida, ti accompagno nella creazione di una demo pratica che scansiona automaticamente i repository, classifica le issue aperte, rileva i duplicati e riassume tutto in un report sintetico. Passo dopo passo vedrai come:

• Progettare un workflow visivamente usando l'interfaccia di Agent Builder.
• Configurare due agenti che collaborano: uno per recuperare e analizzare le issue di GitHub, e un altro per riassumerle.
• Eseguire, testare e pubblicare il workflow tramite ChatKit per l'automazione nel mondo reale.

Alla fine, il tuo workflow AgentKit avrà questo aspetto:

Se stai ancora prendendo confidenza con OpenAI, ti consiglio di dare un'occhiata al nostro percorso di competenze OpenAI Fundamentals. 

Che cos'è AgentKit?

AgentKit è l'ultimo framework di OpenAI per creare, distribuire e ottimizzare agenti AI. È progettato per portarti dal prototipo alla produzione senza richiedere un backend complesso.

Al suo centro, AgentKit ruota attorno a due componenti chiave: Agent Builder e ChatKit.

Agent Builder è un'interfaccia visiva drag-and-drop che ti permette di progettare workflow AI completi senza scrivere codice. Puoi combinare più nodi Agent (basati su un modello GPT) e collegarli in ordine logico. 

Ogni agente può avere le proprie istruzioni, strumenti (come Web Search, Code Interpreter o chiamate API) e schemi di output strutturati, che puoi concatenare per creare automazioni multi-step. Agent Builder gestisce automaticamente il passaggio di contesto, le chiamate al modello e la formattazione dei dati tra i nodi, rendendo semplice prototipare anche pipeline complesse.

Fonte: ChatKit Playground

Una volta pronto il tuo workflow, ChatKit lo rende distribuibile ovunque. Agisce come livello di integrazione che ti permette di incorporare il workflow in un'interfaccia chat, esporlo via API o gestire le sessioni utente tramite configurazione basata su schema. 

Puoi persino scaricare l'SDK e ospitarlo in autonomia per flessibilità e controllo su come girano i tuoi agenti. 

AgentKit si integra anche senza soluzione di continuità con il Connector Registry, un hub centrale che permette agli admin di gestire come le fonti dati e gli strumenti si connettono tra i prodotti OpenAI. 

Questa integrazione significa che i tuoi agenti possono accedere in modo sicuro a risorse enterprise come GitHub, Notion o API interne, senza hard-codare credenziali o gestire integrazioni separate.

Demo di OpenAI AgentKit: creare un workflow di revisione delle issue GitHub

In questa sezione vedremo come costruire un workflow automatizzato di revisione delle issue GitHub usando l'Agent Builder di AgentKit. Questo workflow combina due agenti collegati: uno che analizza le issue da un repository GitHub e un altro che riassume i risultati in un report conciso.

Ecco come funziona:

• Inserisci l'URL del repository GitHub (ad es., https://github.com/OWNER/REPO).
• Il GitHub Agent recupera le issue aperte più recenti, le classifica come bug, feature o question e genera query di ricerca per identificare potenziali duplicati.
• Suggerisce anche possibili assegnatari in base ai contributori o ai commentatori passati.
• Il Summary Agent quindi prende questo output JSON strutturato e produce un riepilogo leggibile su cui i maintainer possono agire subito.

Alla fine, avrai un workflow multi-agente completamente funzionante che trasforma issue grezze di GitHub in insight azionabili.

Passo 1: Configura l'Agent Builder

Vai al AgentKit Playground ed effettua l'accesso o registrati con il tuo account OpenAI. Una volta dentro, atterrerai sull'editor visivo dei workflow, dove puoi progettare, collegare e configurare agenti con un'interfaccia facile da usare.

Ora creiamo un workflow per iniziare.

Passo 2: Crea un workflow

Prima di creare gli agenti, ci serve un workflow che definisca come gli agenti si collegano e interagiscono. Un workflow funge da flusso di controllo tra diversi nodi, come input, elaborazione e output.

Inizia cliccando + Create per creare un nuovo workflow e dagli un nome come GitHub Issue Assistant. Una volta creato, vedrai una tela vuota con un nodo Start che funge da punto di ingresso per tutte le azioni del tuo workflow.

La nostra tela è pronta e ora possiamo iniziare ad aggiungere e collegare più nodi per costruire la logica del workflow.

Passo 3: Crea un agente GitHub

In questo passaggio, aggiungeremo un nodo GitHub Agent accanto al nodo Start per aiutare a elaborare il link del repository inserito dall'utente. Ecco come farlo in 6 semplici passaggi:

1. Nella sidebar, clicca su Agent e aggiungi un nodo agente accanto al nodo Start. 

2. Fai doppio clic sul nodo agente per accedere ai suoi parametri e cambia il nome dell'agente in "GitHub Agent".

3. Aggiungi le seguenti istruzioni nel riquadro delle istruzioni:

You are a GitHub Issue Triage agent.
Input: a public GitHub repository URL (e.g., https://github.com/OWNER/REPO).
Task:
1) Find the repository and the 10–20 most recent *open* issues.
2) For each issue, produce:
   - `label`: one of ["bug","feature","question","chore","docs"]. Be strict.
   - `summary`: 1–2 sentences in plain English that restates the problem or request.
   - `duplicate_query`: a GitHub search string likely to find duplicates. Use:
       repo:OWNER/REPO is:issue (STATE OR KEYWORDS …)
     Prefer 2–4 high-signal tokens from the issue title/body; include synonyms.
   - `assignee_hints`: array of up to 3 GitHub usernames to consider assigning.
       Heuristics: past commit/file authors, most recent commenters with code
       context, codeowners, or frequent resolvers of similar issues.
   - `evidence`: an array of `{url, title}` for 1–3 canonical links
       (the issue URL itself is allowed; add one extra context link if useful).
   - `confidence`: 0–1 float confidence for your label.
3) If fewer than 3 issues are open, expand to the last 30 days including closed.
Constraints & quality bar:
- Do not invent usernames. Only output handles you can infer from the repo or issues.
- Prefer precise duplicate queries over long ones.
- Keep `summary` ≤ 280 chars.
- Include citations for any non-issue links you add.

4. Nella scheda Tools, clicca su + e abilita lo strumento Web Search per questo agente.

5. Infine, clicca il toggle button vicino alla scheda output format e seleziona JSON per un output strutturato. Si aprirà un pop-up simile a Excel: compila i seguenti parametri come mostrato:

Puoi cliccare su Generate per far compilare automaticamente questo schema a GPT.

6. Clicca su update per salvare le impostazioni.

Ora il nostro agente GitHub è pronto per analizzare i repository e categorizzarne le issue.

Passo 4: Crea un agente di riepilogo

Ora riassumiamo tutto ciò che produce il tuo GitHub Agent in un report. Per questo, configuriamo un agente di riepilogo che prende in input l'output JSON dal nodo precedente e restituisce come output un riassunto testuale. 

1. Nella sidebar, clicca su Agent e aggiungi un nodo agente accanto al nodo start. 
2. Fai doppio clic sul nodo agente per accedere ai suoi parametri e cambia il nome dell'agente in "Summary Agent".
3. Aggiungi le seguenti istruzioni nella scheda delle istruzioni:

You are a Release Manager assistant.
You will receive the JSON produced by the previous GitHub Agent. Create a concise triage report that a maintainer can act on immediately.
Report format:
- Repo header with link.
- Triage table (or bullet list) grouped by label in the order: bug, feature, question, chore, docs.
  For each issue: #number, title (link), 1-line summary, confidence (0–1), and a clickable “Duplicates” GitHub search using duplicate_query.
- “Suggested assignees” section: aggregate the top usernames across all issues and list why they were suggested (e.g., “owns file X”, “fixed similar Y”).
- “Notable risks” section: 2–4 bullets calling out breaking risks or customer impact.
- Keep the whole report under 400 words.
Rules:
- Do not invent data not present in the JSON input.
- If error is set or the issues array is empty, output a short diagnostic instead.

4. Seleziona il formato di output come Text.

Ora il tuo Summary Agent genererà un report di riepilogo pronto per gli sviluppatori e il tuo workflow finale avrà questo aspetto:

Passo 5: Anteprima e pubblicazione

Per eseguire questo workflow, clicca su Preview e testa il tuo workflow in modo interattivo.