Práticas recomendadas com a API Live

Antes de começar a usar a API Live, seguem-se algumas práticas recomendadas para obter melhores resultados dos modelos:

  • Use instruções claras do sistema: os modelos têm o melhor desempenho quando as respetivas funções e resultados ideais estão bem definidos, juntamente com instruções explícitas que indicam ao modelo como se comportar em resposta aos comandos.

  • Defina as personas e as funções: atribua ao modelo uma função clara na interação, com competências e conhecimentos definidos, como dizer ao modelo que é o capitão de um navio com experiência em navegação e manutenção de navios durante a Era dos Descobrimentos.

  • Use comandos claros: forneça exemplos do que os modelos devem e não devem fazer nos comandos e tente limitar os comandos a um comando por perfil ou função de cada vez. Em vez de comandos longos com várias páginas, considere usar a encadeamento de comandos. O modelo tem o melhor desempenho em tarefas com chamadas de função únicas.

Diretrizes para o design de instruções do sistema

Para obter o melhor desempenho da API Live, recomendamos que tenha um conjunto de instruções do sistema (ISs) claramente definido que defina a personalidade do agente, as regras de conversa, as restrições e as definições de ferramentas, por esta ordem.

Para obter os melhores resultados, separe cada agente num SI distinto.

  1. Especifique a personagem do agente: forneça detalhes sobre o nome, a função e quaisquer características preferenciais do agente. Se quiser especificar o sotaque, certifique-se de que também especifica o idioma de saída preferido (como um sotaque britânico para um falante de inglês).

  2. Especifique as regras de conversa: coloque estas regras na ordem em que espera que o modelo as siga. Delimitar os elementos únicos da conversa e os ciclos conversacionais. Por exemplo:

    • Elemento único: recolha os detalhes de um cliente uma vez (como o nome, a localização e o número do cartão de fidelidade).
    • Ciclo de conversa: o utilizador pode discutir recomendações, preços, devoluções e entrega, e pode querer passar de tópico para tópico. Indique ao modelo que não há problema em participar neste ciclo de conversa durante o tempo que o utilizador quiser.

  3. Especifique as chamadas de ferramentas num fluxo em frases distintas: por exemplo, se um passo único para recolher os detalhes de um cliente exigir a invocação de uma função get_user_info, pode dizer: O primeiro passo é recolher as informações do utilizador. Primeiro, pede ao utilizador que indique o respetivo nome, localização e número do cartão de fidelidade. Em seguida, invoque get_user_info com estes detalhes.

  4. Adicione as salvaguardas necessárias: forneça salvaguardas conversacionais gerais que não quer que o modelo faça. Não hesite em fornecer exemplos específicos de que, se acontecer x, quer que o modelo faça y. Se ainda não estiver a obter o nível de precisão preferido, use a palavra inequivocamente para orientar o modelo a ser preciso.

  5. Use definições de ferramentas precisas: seja específico nas definições de ferramentas. Certifique-se de que indica ao Gemini em que condições deve ser invocado um pedido de ferramenta.

Exemplo

Este exemplo combina as práticas recomendadas e as diretrizes para a conceção de instruções do sistema para orientar o desempenho do modelo como orientador de carreira.

**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.

Definições de ferramentas

Este JSON define as funções relevantes chamadas no exemplo do orientador de carreira. Para ter os melhores resultados ao definir funções, inclua os respetivos nomes, descrições, parâmetros e condições de invocação.

[
 {
   "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"]
   }
 }
]

Mais informações

Para mais informações sobre a utilização da API Live, consulte: