Istruzioni

Le istruzioni dell'agente forniscono indicazioni dettagliate al modello su cosa deve fare. Queste istruzioni sono fornite in linguaggio naturale.

Scrivere istruzioni

Le istruzioni possono contenere uno dei seguenti elementi:

• Obiettivo generale.
• Come comportarsi.
• Persona da utilizzare.
• Un elenco di subagenti, a cui viene fatto riferimento in base al nome visualizzato nel formato: {@AGENT: Agent Name}.
• Un'istruzione per utilizzare uno strumento specifico, a cui viene fatto riferimento tramite il nome visualizzato nel formato: {@TOOL: tool_name}.
• Riferimento a una variabile, dove il nome della variabile in snake case è racchiuso tra parentesi graffe: {variable_name}.

Esempio per un agente principale:

CURRENT CUSTOMER: {username}

You are the main Weather Agent coordinating multiple agents.
Your primary responsibility is to provide weather information.
Use {@TOOL: get_weather} ONLY for specific weather requests 
(for example, 'weather in London').

If you know the user's name, always greet them by their name.

You have specialized sub-agents:
  1. Greeting Agent: Handles simple greetings like 'Hi', 'Hello'.
  2. Farewell Agent: Handles simple farewells like 'Bye', 'See you'.

Analyze the user's query. 
If it's a greeting, call {@AGENT: Greeting Agent} 
If it's a farewell, call {@AGENT: Farewell Agent} 
If it's a weather request, handle it yourself using {@TOOL: get_weather} 

For anything else, respond appropriately or state you cannot handle it.

Evidenziazione della sintassi

Quando una variabile, un strumento o un agente viene menzionato nell'editor delle istruzioni con la sintassi corretta ({variable_name}, {@TOOL: tool_name} o {@AGENT: Agent Name}), viene evidenziato con un "chip" colorato, a indicare che la sintassi è riconosciuta.

Per semplificare l'inserimento di questi riferimenti, l'editor delle istruzioni fornisce due scorciatoie:

• Se digiti @, si apre un menu contestuale con tre opzioni: Agente, Strumento o Variabile. Puoi navigare in questo menu con i tasti freccia e il tasto Tab oppure facendo clic. Se selezioni un'opzione, verranno visualizzate altre opzioni finché il riferimento non sarà completo, a quel punto diventerà un chip.
• Se digiti {, si apre un menu contestuale che mostra le variabili disponibili per l'inserimento rapido.

Nota: per l'opzione Strumento, nel menu contestuale vengono visualizzati solo gli strumenti che sono stati aggiunti all'agente corrente.

Supporto dei linguaggi

Quando progetti prompt e istruzioni per l'agente, utilizza sempre l'inglese per garantire la massima qualità di comprensione da parte dell'agente. Quando i tuoi agenti interagiscono con gli utenti, sono in grado di rilevare la lingua dell'input utente finale e rispondere automaticamente utilizzando la stessa lingua, se non diversamente indicato.

Se vuoi che il tuo agente parli (o non parli) solo in determinate lingue, devi includere un'istruzione che descriva il supporto. Ad esempio, se l'agente deve rispondere solo in italiano, puoi includere "parli solo italiano e nessun'altra lingua" nelle istruzioni.

Per l'elenco delle lingue supportate, consulta il riferimento alle lingue.

Istruzioni per la ristrutturazione

Puoi inserire le istruzioni in linguaggio naturale, ma il tuo agente potrebbe funzionare meglio se formatti le istruzioni utilizzando una struttura XML, che può aiutare il modello a seguirle meglio. Forniamo una struttura XML standard con tag che puoi utilizzare per strutturare le istruzioni. Dopo aver inserito le istruzioni in linguaggio naturale, puoi fare clic sul pulsante Ristruttura istruzioni sopra il riquadro delle istruzioni per formattarle nella struttura XML consigliata.

La tabella seguente descrive i tag XML consigliati e come possono essere utilizzati:

Tag	Descrizione
role	Definisce la funzione o la responsabilità principale dell'agente.
persona	Descrive la personalità, il tono e le linee guida comportamentali dell'agente.
primary_goal	All'interno di <persona>, specifica l'obiettivo principale dell'agente.
constraints	Elenca le regole o le limitazioni che l'agente deve seguire.
taskflow	Delinea i flussi conversazionali come una serie di attività secondarie.
subtask	All'interno di <taskflow>, una parte specifica del flusso della conversazione, contenente uno o più passaggi.
step	All'interno di <subtask>, un singolo passaggio che include un attivatore e un'azione.
trigger	All'interno di <step>, la condizione o l'input utente che avvia un passaggio.
action	All'interno di <step>, l'azione che l'agente deve intraprendere quando viene attivato un passaggio.
examples	Contiene esempi few-shot per guidare il comportamento dell'agente in scenari specifici.

Ecco un esempio delle stesse istruzioni utilizzando la struttura XML consigliata:

CURRENT CUSTOMER: {username}

<role>The main Weather Agent coordinating multiple agents.</role>

<persona>
    <primary_goal>To provide weather information.</primary_goal>
    How to handle prohibited topics and violations: Respond appropriately or
    state inability to handle the request.
    General guidelines: Follow the constraints and task flow precisely.
</persona>

<constraints>
    1. Use {@TOOL: get_weather} ONLY for specific weather requests 
      (for example, 'weather in London').
    2. If the user's name is known (from the 'CURRENT CUSTOMER' context), always
      greet them by their name.
</constraints>

<taskflow>
    These define the conversational subtasks that you can take. Each subtask
    has a sequence of steps that should be taken in order.
    <subtask name="Initial Greeting">
        <step name="Check for Username and Greet">
            <trigger>Start of conversation or new user interaction.</trigger>
            <action>If a username is provided in the 'CURRENT CUSTOMER' context,
              greet the user by their name. Otherwise, proceed without a 
              personalized greeting.
            </action>
        </step>
    </subtask>
    <subtask name="Query Analysis and Routing">
        <step name="Analyze User Query">
            <trigger>User provides a query.</trigger>
            <action>Determine the intent of the user's query 
              (greeting, farewell, weather request, or other).
            </action>
        </step>
        <step name="Handle Greeting">
            <trigger>User query is identified as a simple greeting
              (e.g., 'Hi', 'Hello').
            </trigger>
            <action>Call {@AGENT: Greeting Agent}.</action>
        </step>
        <step name="Handle Farewell">
            <trigger>User query is identified as a simple farewell
              (e.g., 'Bye', 'See you').
            </trigger>
            <action>Call {@AGENT: Farewell Agent}.</action>
        </step>
        <step name="Handle Weather Request">
            <trigger>User query is identified as a specific weather request
              (e.g., 'weather in London').
            </trigger>
            <action>Use {@TOOL: get_weather} to retrieve weather information and
              provide it to the user.
            </action>
        </step>
        <step name="Handle Other Queries">
            <trigger>User query does not fall into greeting, farewell, or
              specific weather request categories.
            </trigger>
            <action>Respond appropriately to the query or state that the request
              cannot be handled.
            </action>
        </step>
    </subtask>
</taskflow>
<examples>
</examples>

Esempi few-shot in linea

Il prompt few-shot è una tecnica in cui a un modello linguistico di grandi dimensioni (LLM) viene fornito un piccolo insieme di esempi per guidarne il comportamento, il tono o la logica. Nel contesto degli agenti, "Esempi inline di pochi scatti" si riferisce al posizionamento di questi esempi direttamente all'interno delle istruzioni dell'agente anziché in un riquadro separato dell'interfaccia utente. Questo metodo aiuta il modello a comprendere requisiti complessi mostrando, anziché semplicemente dicendo, colmando essenzialmente il divario tra istruzioni astratte ed esecuzione concreta.

Quando utilizzare gli esempi few-shot

Gli esempi few-shot sono uno strumento potente per la calibrazione, ma devono essere utilizzati in modo strategico. Valuta la possibilità di aggiungerli nei seguenti scenari:

• Risoluzione dei problemi di qualità: utilizza gli esempi principalmente per correggere errori specifici in cui il modello fraintende costantemente le istruzioni.
• Formattazione complessa: quando l'agente deve restituire i dati in un formato molto specifico e non standard.
• Logica sfumata: quando le istruzioni "se-allora" non sono sufficienti per cogliere la sottigliezza di un processo decisionale.

Best practice e avvisi

Sebbene efficaci, gli esempi few-shot devono essere selezionati con cura per evitare di peggiorare le prestazioni dell'agente.

• Usali con parsimonia: se aggiungi troppi esempi, l'agente potrebbe "sovradattarsi", il che significa che potrebbe seguire rigidamente gli esempi e perdere la capacità di generalizzare a nuove query utente mai viste.
• Descrittive, non esaustive: non è necessario elencare ogni possibile query dell'utente. Gli esempi hanno lo scopo di fornire indicazioni sul modello di ragionamento del modello, non di fungere da database di ricerca.
• Inizia con le istruzioni: prova sempre a risolvere i problemi di comportamento con istruzioni chiare e descrittive. Aggiungi pochi esempi solo se le istruzioni da sole non riescono a ottenere il risultato desiderato.

Componenti di un esempio few-shot

Un esempio standard di few-shot per gli agenti è costituito da quattro componenti distinti che simulano un turno di conversazione.

Componente	Tag / sintassi	Descrizione
Utente	[user]	Rappresenta l'input o la query dell'utente finale.
Modello	[model]	Rappresenta la risposta testuale o il processo di pensiero dell'agente.
Input dello strumento	tool_code	Mostra come l'agente deve strutturare l'input o la "chiamata" a uno strumento o una funzione esterna (ad es. argomenti/sintassi specifici).
Output dello strumento	tool_outputs	Simula i dati restituiti dallo strumento, insegnando all'agente come interpretarli e utilizzarli nella risposta finale.

Per gli esempi few-shot deve essere utilizzato il seguente formato:

<examples>
  EXAMPLE 1:
  Begin example
  [user]
  What's the weather in London?
  [model]
  ```tool_code
  get_weather(location="London")
  ```
  ```tool_outputs
  {"temperature": "15 C", "condition": "Cloudy"}
  ```
  [model]
  The weather in London is 15 C and Cloudy.
  End example
</examples>

Perfeziona le istruzioni

Puoi selezionare una parte dei contenuti delle istruzioni, poi viene visualizzato un pulsante Perfeziona. Puoi fare clic su questo pulsante per utilizzare l'AI per migliorare i contenuti selezionati. Nel campo Requisiti, inserisci informazioni su come vuoi migliorare i contenuti selezionati.

Formattare le risposte dell'agente

Puoi dare istruzioni all'agente su come formattare le risposte testuali per una migliore leggibilità. Di seguito sono riportate le best practice per le istruzioni sulla formattazione:

Chunking e spazio vuoto

• Non scrivere mai paragrafi densi. Gli utenti scorrono, non leggono.
• Limita i blocchi di testo a un massimo di 1-2 frasi.
• Inserisci un'interruzione di riga tra ogni idea distinta per creare uno spazio vuoto.

Grassetto strategico

• Devi mettere in grassetto i punti dati più importanti in modo che si distinguano immediatamente.
• Sempre in grassetto: nomi dei prodotti, prezzi, date, numeri d'ordine e scadenze.
• Esempio: "La T-shirt classica costa 25 €."

Elenchi sopra il testo

• Se menzioni più di due elementi o passaggi, convertili automaticamente in un elenco puntato o numerato.
• Utilizza punti elenco standard (-) per le opzioni ed elenchi numerati (1.) per le istruzioni.

Istruzioni globali

Oltre a definire istruzioni specifiche per l'agente, puoi definire istruzioni globali nelle impostazioni avanzate dell'applicazione dell'agente.

Ogni agente nell'applicazione agente eredita le istruzioni globali, che vengono inviate al modello per ogni turno di conversazione in aggiunta alle istruzioni specifiche dell'agente.

Le istruzioni globali sono adatte per informazioni generiche che ogni agente deve conoscere. Ad esempio: tono del brand, "COSA FARE e COSA NON FARE" generali, variabili condivise a livello globale e profili dei clienti.