Scrivere un prompt che faccia costruire uno strumento a un agente: 3 parti

Hai chiesto a un agente di "creare uno strumento" e hai ottenuto qualcosa di vago che non si adatta alla tua app. La soluzione non è un prompt più lungo, ma un prompt con tre parti specifiche: dove vive lo strumento, cosa fa e i dettagli concreti che devono valere. Aspettati anche più di un giro: persino DeepSeek dice che alcuni dei suoi plugin demo sono stati rifiniti in diversi giri di conversazione.

La maggior parte dei prompt nella raccolta di DeepSeek per il video demo di Harness Creator Mode mostra questa struttura in tre parti. La pagina (la raccolta di prompt di Creator Mode di DeepSeek, verificata il 3 novembre 2026, nessuna data di pubblicazione sulla pagina) elenca sette plugin: una galleria 3D di monumenti famosi, una visualizzazione 3D di un Transformer, un'interfaccia DSH pixelata, un banco di lavoro per il design di poster, un banco di lavoro per il montaggio video, un lettore di paper e statistiche delle conversazioni. Per usarne uno, incolli il prompt in DeepSeek Harness e selezioni l'opzione Creator Mode. Ogni prompt è fornito in inglese e cinese.

Come appaiono le tre parti in un prompt reale#

Prendi il prompt della visualizzazione 3D del Transformer da quella pagina. Si apre con "Create a DeepSeek Harness plugin with a left sidebar entry". Questa è la prima parte: dove vive lo strumento. Poi descrive la funzione: un gioco dimostrativo 3D interattivo che spiega il calcolo di un Transformer. Seconda parte. Si chiude con un requisito facile da dimenticare e fastidioso da correggere dopo: il titolo del pannello e la barra degli strumenti non devono sovrapporsi ai pulsanti nativi della finestra di macOS. Terza parte.

Gli altri prompt della pagina seguono la stessa struttura, con differenze. Il punto di ingresso varia: una voce nella barra laterale sinistra in tre di essi, un punto raggiunto dalla conversazione in due, la barra laterale destra nel lettore di paper. Il finale è dove diventano concreti: cinque stili, uno dei quali pixelato, oppure un titolo di pagina predefinito "Everything is a plugin". Questo è il pattern da copiare, e la differenza si nota subito:

La prima versione lascia l'agente a indovinare su tutto. Dove va? Una barra laterale, un comando, una finestra separata? Cosa conta come "per le mie conversazioni"? La seconda risponde a queste domande prima che l'agente debba porle.

Scrivi il tuo, una parte alla volta#

Supponi di volere un piccolo pannello che legge un paper e ti permette di fargli domande. Procedi con le parti in ordine.

Dove vive. Una frase, e nomina il punto esatto: "un plugin con una voce nella barra laterale sinistra", "un pulsante nella barra degli strumenti", "una pagina aperta dal menu". Se lo ometti, l'agente sceglie per te.

Cosa fa. Descrivi cosa vedi e clicchi, non come è costruito. "Trascini un PDF, il lato sinistro mostra il testo, il lato destro ha una chat al riguardo." Salta il framework a meno che tu non abbia un motivo per nominarne uno.

Requisiti concreti. È qui che finiscono le cose andate storte l'ultima volta. Regole di layout, cose che non devono sovrapporsi, una lingua, un formato di file, un limite come "nessuna chiamata di rete". Righe brevi e verificabili. Se non riesci a capire se un requisito è stato soddisfatto guardando il risultato, riscrivilo finché non ci riesci.

Mettendo insieme:

Create a plugin with a left sidebar entry.
It is a paper reader: I open a PDF, the text is shown
on the left, and a chat about the paper is on the right.
Requirements:
- the panel title must not overlap the window buttons
- the chat answers only from the paper's text
- keep everything in one file

Inviarlo tramite l'API#

Creator Mode è una funzionalità di DeepSeek Harness; il prompt stesso è testo semplice, quindi qualsiasi cosa che legga un prompt può eseguirlo, incluso uno script che chiama l'API di CheapTokens. Il prompt qui sotto è quello sopra, inviato a DeepSeek-V4-Flash (id completo deepseek-ai/DeepSeek-V4-Flash-0731, contesto da 380K, fino a 32.768 token in una risposta, il che lascia spazio per un intero plugin in una sola risposta):

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.cheaptokens.dev/v1",
    api_key=os.environ["CHEAPTOKENS_API_KEY"],
)

prompt = """Create a plugin with a left sidebar entry.
It is a paper reader: I open a PDF, the text is shown
on the left, and a chat about the paper is on the right.
Requirements:
- the panel title must not overlap the window buttons
- the chat answers only from the paper's text
- keep everything in one file"""

resp = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4-Flash-0731",
    messages=[{"role": "user", "content": prompt}],
    max_tokens=8000,
)
print(resp.choices[0].message.content)
print(resp.choices[0].finish_reason, resp.usage)

La chiave va in una variabile d'ambiente, mai nel file. Se finish_reason stampa length, il plugin è stato troncato da max_tokens: alza il limite. Configurare DeepSeek Harness stesso con un provider personalizzato è un lavoro separato, trattato in collegare DeepSeek Harness a CheapTokens. Le basi della prima richiesta sono nella documentazione di CheapTokens.

Perché un solo prompt raramente basta#

DeepSeek lo dice chiaramente: alcuni dei plugin demo sono stati rifiniti in diversi giri di conversazione, quindi un singolo prompt potrebbe non riprodurre il video esattamente. Pensalo come dare istruzioni a un imprenditore edile. Il primo disegno ti dà la maggior parte della stanza, poi la attraversi e dici "la porta si apre dalla parte sbagliata".

Ed è qui che vanno i soldi. Un agente reinvia la conversazione a ogni giro (lo stesso effetto di perché una chat lunga costa di più), quindi il quinto giro porta con sé il prompt, quattro risposte precedenti e tutto il codice finora.

Quanto costa una sessione di build#

Ecco una sessione ipotetica, non una misurazione: cinque giri, circa 12.000 token inviati per giro (prompt, cronologia, codice attuale) e circa 6.000 token riscritti. La tabella qui sotto usa i prezzi live di CheapTokens per ogni modello; la colonna OpenRouter serve a confrontare la stessa sessione in totale, con input e output contati insieme.

Per un giro con DeepSeek-V4-Flash gli stessi numeri arrivano a $0.00078. Se il tuo plugin è più grande, la cronologia cresce a ogni giro, quindi cambia i due numeri e riesegui la stima. Altro sulla stima delle bollette degli agenti in come stimare il costo di un agente AI, e l'elenco dei modelli è nella pagina dei prezzi.

Controlla prima di inviare#

Scrivi il primo prompt, leggi cosa torna indietro e metti ogni correzione nella versione successiva dei requisiti. Dopo due o tre sessioni avrai una breve lista di righe da incollare in ogni nuovo prompt, e il primo giro uscirà più vicino a ciò che intendevi. Per le abitudini di fondo di qualsiasi prompt, vedi come scrivere un buon prompt.