Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Competenze: Incapsulare le funzionalità

Lezione 17 di 20 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Competenze: Incapsulare le funzionalità
  2. Il concetto di Competenza
  3. Strutturare una libreria di competenze
  4. Comporre le competenze
  5. Competenze con stato
  6. Registro delle competenze
  7. Punti chiave

Lezione aggiornata il 2 novembre 2026 sulla base della documentazione OpenAI: lo strumento Code Interpreter richiede ora un parametro container (aggiunto a tutti gli esempi), le parti di input testuale sono di tipo input_text e la ricerca web utilizza lo strumento web_search (web_search_preview è ora uno strumento legacy senza filtri di dominio). I file generati vengono recuperati utilizzando le funzioni fichiers_generes e telecharger della Lezione 10. Fonti: Code Interpreter · Ricerca web.

Competenze: Incapsulare le funzionalità

Una Competenza (Skill) risolve un problema che tutti incontrano entro la seconda settimana: lo stesso prompt di sistema copiato in quattro file, che divergono non appena ne migliori solo uno. L’idea è trattare una funzionalità come un’unità singola—le sue istruzioni, i suoi strumenti, i suoi dati di riferimento—e chiamarla per nome invece di riscriverla.

Il vantaggio non è solo evitare ripetizioni. Una funzionalità nominata diventa un oggetto che puoi versionare, testare e consegnare a qualcun altro. Quando un avvocato ti dice che una clausola standard è cambiata, modifichi una sola competenza e ogni chiamata ne beneficia, invece di dover cercare dove il prompt era stato duplicato.

Il concetto di Competenza

Una Competenza incapsula tutto ciò di cui un modello ha bisogno per svolgere un compito specifico. I tre elementi seguenti non sono intercambiabili: le istruzioni definiscono il ruolo e il formato, gli strumenti determinano cosa il modello può recuperare e il contesto ancorano le risposte ai tuoi riferimenti piuttosto che alla conoscenza generale del modello.

  • Istruzioni: Il prompt di sistema specializzato
  • Strumenti: Le funzioni e gli strumenti integrati necessari
  • Contesto: Dati di riferimento ed esempi
from openai import OpenAI

client = OpenAI()

# Definisci una competenza di analisi finanziaria
skill_analyse_financiere = {
    "instructions": (
        "You are a financial analyst specializing in French SMEs. "
        "You analyze accounting documents and produce structured reports "
        "with key indicators, trends, and recommendations. "
        "Use French accounting standards (PCG). "
        "Format amounts in euros with thousands separators."
    ),
    "tools": [
        {"type": "file_search", "vector_store_ids": ["vs_normes_comptables"]},
        {"type": "code_interpreter", "container": {"type": "auto"}}
    ]
}

# Usa la competenza
response = client.responses.create(
    model="gpt-5.6-terra",
    instructions=skill_analyse_financiere["instructions"],
    input=[{
        "role": "user",
        "content": [
            {"type": "input_text", "text": "Analyze this balance sheet and produce a report"},
            {"type": "input_file", "file_id": fichier_bilan.id}
        ]
    }],
    tools=skill_analyse_financiere["tools"]
)

Strutturare una libreria di competenze

Passare da un dizionario a una classe non è solo una questione estetica: ti permette di allegare esempi a una competenza e iniettarli sistematicamente. Due o tre coppie input/output ben scelte fanno di più per la coerenza del formato di un paragrafo aggiuntivo di istruzioni, perché mostrano invece di descrivere. L’implementazione seguente le concatena alle istruzioni ad ogni chiamata.

class Skill:
    def __init__(self, nom: str, instructions: str, tools: list, exemples: list = None):
        self.nom = nom
        self.instructions = instructions
        self.tools = tools
        self.exemples = exemples or []

    def executer(self, client: OpenAI, requete: str, fichiers: list = None) -> str:
        content = [{"type": "input_text", "text": requete}]
        if fichiers:
            for fid in fichiers:
                content.append({"type": "input_file", "file_id": fid})

        # Aggiungi esempi al contesto
        instructions = self.instructions
        if self.exemples:
            instructions += "\n\nReference examples:\n"
            for ex in self.exemples:
                instructions += f"- Input: {ex['input']}\n  Output: {ex['output']}\n"

        response = client.responses.create(
            model="gpt-5.6-terra",
            instructions=instructions,
            input=[{"role": "user", "content": content}],
            tools=self.tools
        )
        return response.output_text


# Definisci le competenze
skill_redaction_contrat = Skill(
    nom="redaction-contrat",
    instructions=(
        "You are a lawyer specializing in contract law. "
        "You draft clear, precise clauses compliant with French law. "
        "Each clause must be numbered and structured."
    ),
    tools=[
        {"type": "file_search", "vector_store_ids": ["vs_modeles_contrats"]},
        {"type": "web_search"}
    ],
    exemples=[
        {
            "input": "Confidentiality clause for a contractor",
            "output": "Article X - Confidentiality\nX.1 The Contractor undertakes..."
        }
    ]
)

skill_support_technique = Skill(
    nom="support-technique",
    instructions=(
        "You are a level 2 technical support agent. "
        "You diagnose problems by asking targeted questions. "
        "Search the knowledge base first before proposing solutions. "
        "Document every resolution."
    ),
    tools=[
        {"type": "file_search", "vector_store_ids": ["vs_base_connaissances"]},
        {
            "type": "function",
            "name": "creer_ticket_escalade",
            "description": "Escalate an issue to level 3",
            "parameters": {
                "type": "object",
                "properties": {
                    "titre": {"type": "string"},
                    "description": {"type": "string"},
                    "priorite": {"type": "string", "enum": ["basse", "moyenne", "haute", "critique"]}
                },
                "required": ["titre", "description", "priorite"],
                "additionalProperties": False
            },
            "strict": True
        }
    ]
)

Comporre le competenze

La composizione concatena le competenze passando il risultato di una come contesto alla successiva. È potente, ed è esattamente qui che iniziano i problemi, per una ragione specifica: ad ogni passo, il contesto trasmesso è l’output del passo precedente, non i dati originali. Qualsiasi informazione che la prima competenza ha considerato secondaria scompare per tutte quelle successive.

Due conseguenze pratiche. Ordina i passaggi dal più generale al più specifico, in modo che il filtraggio avvenga il più tardi possibile. E quando un passaggio a valle ha bisogno di dati grezzi, passa di nuovo i file invece di affidarti al riepilogo: è proprio ciò che fa il parametro fichiers nell’esempio, che viene passato solo al primo passo ma dovrebbe essere passato a tutti quelli che ne dipendono.

class SkillComposee:
    def __init__(self, nom: str, etapes: list[dict]):
        self.nom = nom
        self.etapes = etapes
        self.client = OpenAI()

    def executer(self, requete_initiale: str, fichiers: list = None) -> dict:
        contexte = requete_initiale
        resultats = {}

        for etape in self.etapes:
            skill = etape["skill"]
            instruction_etape = etape.get("instruction", "")
            prompt = f"{instruction_etape}\n\nPrevious context: {contexte}"

            resultat = skill.executer(self.client, prompt, fichiers)
            resultats[etape["nom"]] = resultat
            contexte = resultat
            fichiers = None  # File usati solo al primo passo

        return resultats


# Flusso di lavoro: analisi contrattuale seguita dalla stesura di un riepilogo
workflow_audit_contrat = SkillComposee(
    nom="audit-contrat",
    etapes=[
        {
            "nom": "analyse",
            "skill": skill_analyse_financiere,
            "instruction": "Analyze the financial aspects of this contract"
        },
        {
            "nom": "juridique",
            "skill": skill_redaction_contrat,
            "instruction": "Identify legal risks and propose improvements"
        }
    ]
)

Competenze con stato

Una competenza che ricorda le sue chiamate precedenti abilita conversazioni lunghe—una diagnosi tecnica, una negoziazione, il tracciamento di un caso. Introduce anche l’unico costo che cresce inosservato: ad ogni turno, l’intera cronologia viene reinviata e rifatturata. Pianifica fin dall’inizio una politica di troncamento o riassunto periodico, altrimenti la ventesima domanda costerà dieci volte la prima per una qualità che non è migliorata di dieci volte.

class SkillAvecEtat:
    def __init__(self, skill: Skill):
        self.skill = skill
        self.client = OpenAI()
        self.historique = []
        self.contexte_accumule = ""

    def appeler(self, requete: str, fichiers: list = None) -> str:
        # Costruisci il prompt con la cronologia
        instructions = self.skill.instructions
        if self.contexte_accumule:
            instructions += f"\n\nContext from previous interactions:\n{self.contexte_accumule}"

        content = [{"type": "input_text", "text": requete}]
        if fichiers:
            for fid in fichiers:
                content.append({"type": "input_file", "file_id": fid})

        response = self.client.responses.create(
            model="gpt-5.6-terra",
            instructions=instructions,
            input=[{"role": "user", "content": content}],
            tools=self.skill.tools
        )

        resultat = response.output_text
        self.historique.append({"requête": requete, "reponse": resultat})
        self.contexte_accumule += f"\n- {requete} -> {resultat[:200]}..."

        return resultat

# Utilizzo: supporto tecnico con tracciamento della conversazione
session = SkillAvecEtat(skill_support_technique)
r1 = session.appeler("My application crashes at startup")
r2 = session.appeler("I have version 3.2.1 on Ubuntu 24.04")
r3 = session.appeler("The log shows a database connection error")

Registro delle competenze

Centralizza la gestione delle tue competenze:

class RegistreSkills:
    def __init__(self):
        self.skills = {}

    def enregistrer(self, skill: Skill):
        self.skills[skill.nom] = skill

    def obtenir(self, nom: str) -> Skill:
        if nom not in self.skills:
            raise KeyError(f"Skill '{nom}' not found. "
                          f"Available: {list(self.skills.keys())}")
        return self.skills[nom]

    def lister(self) -> list[str]:
        return list(self.skills.keys())

# Registro globale
registre = RegistreSkills()
registre.enregistrer(skill_analyse_financiere_obj)
registre.enregistrer(skill_redaction_contrat)
registre.enregistrer(skill_support_technique)

# Utilizzo
skill = registre.obtenir("support-technique")
resultat = skill.executer(client, "My printer isn't working")

Punti chiave

  • Una Competenza incapsula istruzioni, strumenti e contesto in un pacchetto riutilizzabile
  • Componi le competenze per flussi di lavoro multi-step
  • Usa lo stato per le competenze conversazionali
  • Centralizza le tue competenze in un registro per semplificarne la scoperta
  • Gli esempi nelle istruzioni migliorano l’accuratezza del modello