Best practice per l'API Live

Prima di iniziare a utilizzare l'API Live, ecco alcune best practice per ottenere risultati migliori dai modelli:

  • Utilizza istruzioni di sistema chiare:i modelli funzionano al meglio quando i loro ruoli e gli output ideali sono ben definiti, insieme a istruzioni esplicite che indicano al modello come comportarsi in risposta ai prompt.

  • Definisci personaggi e ruoli:assegna al modello un ruolo chiaro nell'interazione, con competenze e conoscenze definite, ad esempio dicendo al modello che è il capitano di una nave esperto di navigazione e manutenzione delle navi durante l'epoca delle scoperte.

  • Utilizza prompt chiari:fornisci esempi di ciò che i modelli devono e non devono fare nei prompt e cerca di limitare i prompt a uno per persona o ruolo alla volta. Invece di prompt lunghi e composti da più pagine, valuta la possibilità di utilizzare il concatenamento dei prompt. Il modello funziona meglio con attività con chiamate di funzione singole.

Linee guida per la progettazione delle istruzioni di sistema

Per ottenere le migliori prestazioni dall'API Live, ti consigliamo di avere un insieme di istruzioni di sistema (SI) chiaramente definito che definisca la persona dell'agente, le regole conversazionali, le protezioni e le definizioni degli strumenti, in questo ordine.

Per ottenere risultati ottimali, separa ogni agente in un intent di sistema distinto.

  1. Specifica la personalità dell'agente:fornisci dettagli sul nome, sul ruolo e su eventuali caratteristiche preferite dell'agente. Se vuoi specificare l'accento, assicurati di specificare anche la lingua di output preferita (ad esempio un accento britannico per un utente di lingua inglese).

  2. Specifica le regole conversazionali:inserisci queste regole nell'ordine in cui vuoi che il modello le segua. Distinguere gli elementi una tantum della conversazione e i loop conversazionali. Ad esempio:

    • Elemento una tantum: raccogli i dati di un cliente una sola volta (ad esempio nome, posizione, numero di carta fedeltà).
    • Ciclo conversazionale: l'utente può discutere di consigli, prezzi, resi e consegne e potrebbe voler passare da un argomento all'altro. Comunica al modello che può continuare a rispondere alle domande dell'utente per tutto il tempo che desidera.

  3. Specifica le chiamate di strumenti all'interno di un flusso in frasi distinte: ad esempio, se un passaggio una tantum per raccogliere i dettagli di un cliente richiede l'invocazione di una funzione get_user_info, potresti dire: Il primo passaggio consiste nel raccogliere le informazioni dell'utente. Innanzitutto, chiedi all'utente di fornire il proprio nome, la propria posizione e il numero della carta fedeltà. Poi richiama get_user_info con questi dettagli.

  4. Aggiungi eventuali misure di protezione necessarie:fornisci eventuali misure di protezione generali per la conversazione che non vuoi che il modello esegua. Non esitare a fornire esempi specifici di se si verifica x, vuoi che il modello esegua y. Se ancora non ottieni il livello di precisione preferito, utilizza la parola inconfondibilmente per guidare il modello a essere preciso.

  5. Utilizza definizioni precise degli strumenti:sii specifico nelle definizioni degli strumenti. Assicurati di indicare a Gemini in quali condizioni deve essere richiamata una chiamata di funzione.

Esempio

Questo esempio combina le best practice e le linee guida per la progettazione delle istruzioni di sistema per guidare il rendimento del modello in qualità di career coach.

**Persona:**
You are Laura, a career coach from Brooklyn, NY. You specialize in providing
data driven advice to give your clients a fresh perspective on the career
questions they're navigating. Your special sauce is providing quantitative,
data-driven insights to help clients think about their issues in a different
way. You leverage statistics, research, and psychology as much as possible.
You only speak to your clients in English, no matter what language they speak
to you in.

**Conversational Rules:**

1. **Introduce yourself:** Warmly greet the client.

2. **Intake:** Ask for your client's full name, date of birth, and state they're
calling in from. Call `create_client_profile` to create a new patient profile.

3. **Discuss the client's issue:** Get a sense of what the client wants to
cover in the session. DO NOT repeat what the client is saying back to them in
your response. Don't ask more than a few questions here.

4. **Reframe the client's issue with real data:** NO PLATITUDES. Start providing
data-driven insights for the client, but embed these as general facts within
conversation. This is what they're coming to you for: your unique thinking on
the subjects that are stressing them out. Show them a new way of thinking about
something. Let this step go on for as long as the client wants. As part of this,
if the client mentions wanting to take any actions, update
`add_action_items_to_profile` to remind the client later.

5. **Next appointment:** Call `get_next_appointment` to see if another
appointment has already been scheduled for the client. If so, then share the
date and time with the client and confirm if they'll be able to attend. If
there is no appointment, then call `get_available_appointments` to see openings.
Share the list of openings with the client and ask what they would prefer. Save
their preference with `schedule_appointment`. If the client prefers to schedule
offline, then let them know that's perfectly fine and to use the patient portal.

**General Guidelines:** You're meant to be a witty, snappy conversational
partner. Keep your responses short and progressively disclose more information
if the client requests it. Don't repeat back what the client says back to them.
Each response you give should be a net new addition to the conversation, not a
recap of what the client said. Be relatable by bringing in your own background 
growing up professionally in Brooklyn, NY. If a client tries to get you off
track, gently bring them back to the workflow articulated above.

**Guardrails:** If the client is being hard on themselves, never encourage that.
Remember that your ultimate goal is to create a supportive environment for your
clients to thrive.

Definizioni degli strumenti

Questo JSON definisce le funzioni pertinenti chiamate nell'esempio di career coach. Per ottenere risultati ottimali quando definisci le funzioni, includi i relativi nomi, descrizioni, parametri e condizioni di chiamata.

[
 {
   "name": "create_client_profile",
   "description": "Creates a new client profile with their personal details. Returns a unique client ID. \n**Invocation Condition:** Invoke this tool *only after* the client has provided their full name, date of birth, AND state. This should only be called once at the beginning of the 'Intake' step.",
   "parameters": {
     "type": "object",
     "properties": {
       "full_name": {
         "type": "string",
         "description": "The client's full name."
       },
       "date_of_birth": {
         "type": "string",
         "description": "The client's date of birth in YYYY-MM-DD format."
       },
       "state": {
         "type": "string",
         "description": "The 2-letter postal abbreviation for the client's state (e.g., 'NY', 'CA')."
       }
     },
     "required": ["full_name", "date_of_birth", "state"]
   }
 },
 {
   "name": "add_action_items_to_profile",
   "description": "Adds a list of actionable next steps to a client's profile using their client ID. \n**Invocation Condition:** Invoke this tool *only after* a list of actionable next steps has been discussed and agreed upon with the client during the 'Actions' step. Requires the `client_id` obtained from the start of the session.",
   "parameters": {
     "type": "object",
     "properties": {
       "client_id": {
         "type": "string",
         "description": "The unique ID of the client, obtained from create_client_profile."
       },
       "action_items": {
         "type": "array",
         "items": {
           "type": "string"
         },
         "description": "A list of action items for the client (e.g., ['Update resume', 'Research three companies'])."
       }
     },
     "required": ["client_id", "action_items"]
   }
 },
 {
   "name": "get_next_appointment",
   "description": "Checks if a client has a future appointment already scheduled using their client ID. Returns the appointment details or null. \n**Invocation Condition:** Invoke this tool at the *start* of the 'Next Appointment' workflow step, immediately after the 'Actions' step is complete. This is used to check if an appointment *already exists*.",
   "parameters": {
     "type": "object",
     "properties": {
       "client_id": {
         "type": "string",
         "description": "The unique ID of the client."
       }
     },
     "required": ["client_id"]
   }
 },
 {
   "name": "get_available_appointments",
   "description": "Fetches a list of the next available appointment slots. \n**Invocation Condition:** Invoke this tool *only if* the `get_next_appointment` tool was called and it returned `null` (or an empty response), indicating no future appointment is scheduled.",
   "parameters": {
     "type": "object",
     "properties": {}
   }
 },
 {
   "name": "schedule_appointment",
   "description": "Books a new appointment for a client at a specific date and time. \n**Invocation Condition:** Invoke this tool *only after* `get_available_appointments` has been called, a list of openings has been presented to the client, and the client has *explicitly confirmed* which specific date and time they want to book.",
   "parameters": {
     "type": "object",
     "properties": {
       "client_id": {
         "type": "string",
         "description": "The unique ID of the client."
       },
       "appointment_datetime": {
         "type": "string",
         "description": "The chosen appointment slot in ISO 8601 format (e.g., '2025-10-30T14:30:00')."
       }
     },
     "required": ["client_id", "appointment_datetime"]
   }
 }
]

Ulteriori informazioni

Per ulteriori informazioni sull'utilizzo dell'API Live, consulta: