Interações de várias rodadas com modelos de comandos do servidor


Este guia se aplica a qualquer recurso que dependa de interações de várias rodadas, incluindo:

Visão geral detalhada

Para interações com várias rodadas, os SDKs do Firebase AI Logic gerenciam o estado da conversa. Isso também se aplica ao usar modelos de comandos do servidor.

O fluxo de trabalho básico para interações de várias rodadas e modelos de comandos do servidor é fundamentalmente o mesmo que para solicitações de uma única rodada, com algumas diferenças importantes:

  1. Crie o modelo usando a interface guiada no console Firebase.

    Para interações de várias rodadas, adicione a tag {{history}} ao conteúdo do modelo, que informa ao modelo onde inserir as rodadas de conversa gerenciadas pelo SDK do cliente.

  2. Teste o modelo em uma solicitação real usando a experiência de teste no console do Firebase.

    Para interações em vários turnos, a experiência de teste do console do Google Cloud só pode ajudar a testar o turno inicial. Você pode testar como as conversas subsequentes (o histórico) são processadas usando o modelo com seu app real.

  3. Acesse o modelo no código do app usando templateGenerativeModel.

    Para interações de várias etapas, use startChat e sendMessage, assim como você faz para interações de várias etapas quando não usa modelos de solicitação do servidor.

Para chamada de função, há mais algumas diferenças, que são descritas nessa seção mais adiante nesta página.


Conversa com vários turnos (chat)

Se ainda não fez isso, consulte o guia geral para criar conversas de várias rodadas (chat) quando não usar modelos de comandos do servidor.

Formato básico de um modelo de comando do servidor

Para Firebase AI Logic, o console Firebase fornece uma interface guiada para especificar o frontmatter e o conteúdo do modelo.

Os modelos de comandos do servidor usam uma sintaxe e um formato baseados em Dotprompt. Para mais detalhes, consulte Formato, sintaxe e exemplos de modelos.

O modelo de exemplo abaixo mostra os componentes mais importantes para um modelo ao criar uma conversa multiturno (chat). Observe a adição da tag {{history}} no conteúdo do modelo, que informa ao modelo onde inserir as trocas de conversa gerenciadas pelo SDK do cliente.

---
model: 'gemini-3-flash-preview'
---

{{role "system"}}
You help customers with their invoices, including answering questions or providing their invoices to them.
If an invoice is requested, it must be a clearly structured invoice document that uses a tabular or clearly delineated list format for line items.

{{history}}

Usar o modelo no código

Clique no seu provedor de Gemini API para conferir o conteúdo e o código específicos do provedor nesta página.

O exemplo de código do cliente abaixo mostra como usar o modelo no seu código. Observe o uso de templateGenerativeModel com startChat e sendMessage ao criar interações de várias rodadas.

Swift 

For Swift, using server prompt templates with multi-turn interactions is not yet supported. Check back soon!

Kotlin 


// ...

// Initialize the Gemini Developer API backend service
// Create a `TemplateGenerativeModel` instance.
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
                        .templateGenerativeModel()

// Start a chat session with a template.
val chatSession = model.startChat(
  // Specify your template ID
  templateId= "my-chat-template-v1-0-0",
  inputs = emptyMap()
)

// Send messages.
// The template's system instructions and model config apply to every turn automatically.
// The SDK automatically manages the state of the conversation.
val response = chatSession.sendMessage(
  content("user") { text("I need a copy of my invoice.") }
)

val text = response.text
println(text)

Java 

For Java, using server prompt templates with multi-turn interactions is not yet supported. Check back soon!

Web 


// ...

// Initialize the Gemini Developer API backend service.
const ai = getAI(app, { backend: new GoogleAIBackend() });

// Create a `TemplateGenerativeModel` instance.
const model = getTemplateGenerativeModel(ai);

// Start a chat session with a template.
const chatSession = model.startChat({
  // Specify your template ID.
  templateId: 'my-chat-template-v1-0-0',
});

// Send messages.
// The template's system instructions and model config apply to every turn automatically.
// The SDK automatically manages the state of the conversation.
const result = await chatSession.sendMessage("I need a copy of my invoice.");

const text = result.response.text();
console.log(text);

Dart 


// ...

// Initialize the Gemini Developer API backend service.
// Create a `TemplateGenerativeModel` instance.
final model = FirebaseAI.googleAI().templateGenerativeModel();

// Start a chat session with a template.
final chatSession = model.startChat(
  // Specify your template ID.
  templateId: 'my-chat-template-v1-0-0',
);

// Send messages.
// The template's system instructions and model config apply to every turn automatically.
// The SDK automatically manages the state of the conversation.
final response = await chatSession.sendMessage(
  Content.text('I need a copy of my invoice.'),
);

final text = response.text;
print(text);

Unity 


// ...

// Initialize the Gemini Developer API backend service.
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI());

// Create a `TemplateGenerativeModel` instance.
var model = firebaseAI.GetTemplateGenerativeModel();

// Start a chat session with a template.
var chatSession = model.StartChat(
    // Specify your template ID.
    "my-chat-template-v1-0-0"
);

// Send messages.
// The template's system instructions and model config apply to every turn automatically.
// The SDK automatically manages the state of the conversation.
try
{
   var response = await chatSession.SendMessageAsync(ModelContent.Text("I need a copy of my invoice."));
   Debug.Log($"Response Text: {response.Text}");
}
catch (Exception e) {
  Debug.LogError($"An error occurred: {e.Message}");
}


Chamadas de função

Se ainda não fez isso, consulte o guia geral para chamada de função quando não usar modelos de comandos do servidor. Este guia sobre o uso de modelos de solicitação do servidor pressupõe que você entenda como a chamada de função funciona em geral.

Formato básico de um modelo de comando do servidor

Para Firebase AI Logic, o console Firebase fornece uma interface guiada para especificar o frontmatter e o conteúdo do modelo.

Os modelos de comandos do servidor usam uma sintaxe e um formato baseados em Dotprompt. Para mais detalhes, consulte Formato, sintaxe e exemplos de modelos.

O modelo de exemplo abaixo mostra os componentes mais importantes para um modelo ao usar a chamada de função. Observações:

  • No frontmatter do modelo, liste as funções a que o modelo tem acesso fornecendo declarações de função no objeto tools.

    • Defina o name (obrigatório) e o description (opcional) para cada função a que o modelo tem acesso.

    • Defina o esquema de cada função a que o modelo tem acesso.

      O modelo de exemplo abaixo pressupõe que você está definindo esquemas de função no modelo. No entanto, é possível fornecer o esquema da função no código do cliente. O esquema definido no código do cliente substitui qualquer esquema definido no modelo. Mais adiante nesta página, confira um exemplo de modelo e código do cliente para definir o esquema no código do cliente.

  • No conteúdo do modelo, adicione a tag {{history}}, que informa ao modelo onde inserir as conversas gerenciadas pelo SDK do cliente.

Exemplo de modelo com esquema de função definido no modelo

---
model: gemini-3-flash-preview
tools:
  - name: fetchWeather
    description: Get the weather conditions for a specific city on a specific date.
    input:
      schema:
        location(object, The name of the city and its state for which to get the weather. Only cities in the USA are supported.):
          city: string, The city of the location.
          state: string, The state of the location.
        date: string, The date for which to get the weather. Date must be in the format YYYY-MM-DD.

---

What was the weather like in Boston, Massachusetts on 10/17 in year 2024?

{{history}}

Usar o modelo no código

Clique no seu provedor de Gemini API para conferir o conteúdo e o código específicos do provedor nesta página.

O exemplo de código do cliente abaixo mostra como usar o modelo no seu código. Observações:

  • Use templateGenerativeModel com startChat e sendMessage ao usar interações multiturno.

  • Durante a inicialização do modelo no código do cliente, não liste as funções a que o modelo tem acesso. Em vez disso, as funções precisam ser listadas no objeto tools do frontmatter do modelo (veja acima).

  • O exemplo de código do cliente abaixo pressupõe que você está definindo esquemas de função no modelo. Se você decidir definir o esquema no código do cliente, ele vai substituir o esquema definido pelo modelo. Mais adiante nesta página, confira um exemplo de modelo e código do cliente para definir o esquema no código do cliente.

  • Verifique se o modelo retorna uma chamada de função como parte do atendimento a uma solicitação. Se sim, o app precisa executar a lógica local e enviar o resultado de volta ao modelo.

Exemplo de código do cliente com esquema de função definido no modelo

Swift 

For Swift, using server prompt templates with multi-turn interactions is not yet supported. Check back soon!

Kotlin 


// ...

// Initialize the Gemini Developer API backend service.
// Create a `TemplateGenerativeModel` instance.
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
    .templateGenerativeModel()

// Start a chat session with a template that has functions listed as tools.
val chatSession = model.startChat(
    // Specify your template ID
    templateId = "my-function-calling-template-v1-0-0",
    inputs = emptyMap()
)

// Send a message that might trigger a function call.
val response = chatSession.sendMessage(
    content("user") { text(userMessage) }
)

// When the model responds with one or more function calls, invoke the function(s).
// Note that this is the same as when *not* using server prompt templates.
val functionCalls = response.functionCalls
val fetchWeatherCall = functionCalls.find { it.name == "fetchWeather" }

// Forward the structured input data from the model to the hypothetical external API.
val functionResponse = fetchWeatherCall?.let {
  // Alternatively, if your `Location` class is marked as @Serializable, you can use
  // val location = Json.decodeFromJsonElement(it.args["location"]!!)
  val location = Location(
      it.args["location"]!!.jsonObject["city"]!!.jsonPrimitive.content,
      it.args["location"]!!.jsonObject["state"]!!.jsonPrimitive.content
  )
  val date = it.args["date"]!!.jsonPrimitive.content
  fetchWeather(location, date)
}

Java 

For Java, using server prompt templates with multi-turn interactions is not yet supported. Check back soon!

Web 


// ...

// Initialize the Gemini Developer API backend service.
const ai = getAI(app, { backend: new GoogleAIBackend() });

// Create a `TemplateGenerativeModel` instance.
const model = getTemplateGenerativeModel(ai);

// Start a chat session with a template that has functions listed as tools.
const chatSession = model.startChat({
  // Specify your template ID
  templateId: 'my-function-calling-template-v1-0-0',
});

// Send a message that might trigger a function call.
const result = await chatSession.sendMessage(userMessage);

// When the model responds with one or more function calls, invoke the function(s).
// Note that this is the same as when *not* using server prompt templates.
const functionCalls = result.response.functionCalls();
let functionCall;
let functionResult;

if (functionCalls.length > 0) {
  for (const call of functionCalls) {
    if (call.name === "fetchWeather") {
      // Forward the structured input data prepared by the model
      // to the hypothetical external API.
      functionResult = await fetchWeather(call.args);
      functionCall = call;
    }
  }
}

Dart 


// ...

// Initialize the Gemini Developer API backend service.
// Create a `TemplateGenerativeModel` instance.
final model = FirebaseAI.googleAI().templateGenerativeModel()

// Start a chat session with a template that has functions listed as tools.
var chatSession = model.startChat(
    // Specify your template ID
    'my-function-calling-template-v1-0-0',
);

// Send a message that might trigger a function call.
var response = await chatSession.sendMessage(
    Content.text(userMessage),
);

// Check if the model wants to call a function.
// Note that this is the same as when *not* using server prompt templates.
final functionCalls = response?.functionCalls.toList();
// When the model responds with one or more function calls, invoke the function(s).
if (functionCalls != null && functionCalls.isNotEmpty) {
  for (final functionCall in functionCalls) {
    if (functionCall.name == 'fetchWeather') {
      Map<String, dynamic> location =
          functionCall.args['location']! as Map<String, dynamic>;
      var date = functionCall.args['date']! as String;
      var city = location['city'] as String;
      var state = location['state'] as String;
      final functionResult =
          await fetchWeather(Location(city, state), date);
      // Send the response to the model so that it can use the result to
      // generate text for the user.
      response = await chatSession.sendMessage(
        Content.functionResponse(functionCall.name, functionResult),
      );
    }
  }
}

Unity 


// ...

// Initialize the Gemini Developer API backend service.
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI());

// Create a `TemplateGenerativeModel` instance.
var model = firebaseAI.GetTemplateGenerativeModel();

// Start a chat session with a template that has functions listed as tools.
var chatSession = model.StartChat(
    // Specify your template ID
    "my-function-calling-template-v1-0-0"
);

try
{
   // Send a message that might trigger a function call.
   var response = await chatSession.SendMessageAsync(ModelContent.Text(userMessage));
   var functionResponses = new List();

  // When the model responds with one or more function calls, invoke the function(s).
  // Note that this is the same as when *not* using server prompt templates.
  foreach (var functionCall in response.FunctionCalls) {
    if (functionCall.Name == "fetchWeather") {
      // TODO(developer): Handle invalid arguments.
      var location = functionCall.Args["location"] as Dictionary<string, object>;
      var city = location["city"] as string;
      var state = location["state"] as string;
      var date = functionCall.Args["date"] as string;

      functionResponses.Add(ModelContent.FunctionResponse(
        name: functionCall.Name,
        // Forward the structured input data prepared by the model
        // to the hypothetical external API.
        response: FetchWeather(city: city, state: state, date: date)
      ));
    }
    // TODO(developer): Handle other potential function calls, if any.
  }

  // Send the function responses back to the model.
  var functionResponseResult = await chatSession.SendMessageAsync(functionResponses);
}
catch (Exception e) {
  Debug.LogError($"An error occurred: {e.Message}");
}


Chamada de função: definir esquema no código do cliente

Confira as seções acima sobre como a chamada de função funciona com modelos de comandos do servidor, em especial o uso da tag {{history}} no conteúdo do modelo. Esta seção fornece um exemplo de modelo e código do cliente se você quiser definir o esquema da função no código do cliente em vez de no modelo.

Observe o seguinte sobre a definição do esquema de função no código do cliente:

  • Se você definir o esquema de uma função no código do cliente (como mostrado no exemplo abaixo), o esquema do lado do cliente vai substituir qualquer esquema definido por modelo para essa função.

  • Para definir o esquema de função no código do cliente, escreva a declaração de função e forneça a declaração em startChat, não durante a inicialização do modelo (que é o que você faz quando não usa modelos de solicitação do servidor).

  • Mesmo que a declaração de função especifique um name, o modelo ainda precisa listar as funções a que você quer que ele tenha acesso. O name no modelo precisa corresponder ao name no código do cliente.

Exemplo de modelo com esquema de função definido no código do cliente

---
model: gemini-3-flash-preview
tools:
  - name: fetchWeather
    description: Get the weather conditions for a specific city on a specific date.
---

What was the weather like in Boston, Massachusetts on 10/17 in year 2024, formatted in CELSIUS?

{{history}}

Exemplo de código do cliente com esquema de função definido no código do cliente
(para detalhes omitidos deste exemplo, consulte o exemplo de código do cliente acima)

Swift 

For Swift, using server prompt templates with multi-turn interactions is not yet supported. Check back soon!

Kotlin 

// ...

// Initialize your desired Gemini API backend service.
// Create a `TemplateGenerativeModel` instance.
...

// Define the schema for any functions listed in your template.
val fetchWeatherTool = functionDeclarations(
    functionDeclarations = listOf(
        FunctionDeclaration(
            name = "fetchWeather",
            description = "Returns the weather for a given location at a given time",
            parameters = mapOf(
                "location" to Schema.obj(
                    description = "The name of the city and its state for which to get the weather. Only cities in the USA are supported.",
                    properties = mapOf(
                        "city" to Schema.string(
                            description = "The city of the location."
                        ),
                        "state" to Schema.string(
                            description = "The state of the location."
                        ),
                        "zipCode" to Schema.string(
                            description = "Optional zip code of the location.",
                            nullable = true
                        )
                    ),
                    optionalProperties = listOf("zipCode")
                ),
                "date" to Schema.string(
                    description = "The date for which to get the weather. Date must be in the format: YYYY-MM-DD."
                ),
                "unit" to Schema.enumeration(
                    description = "The temperature unit.",
                    values = listOf("CELSIUS", "FAHRENHEIT"),
                    nullable = true
                )

            ),
            optionalParameters = listOf("unit"),
        )
    )
)

// Start a chat session with a template that has functions listed as tools.
var chatSessionWithSchemaOverride = model.startChat(
    // Specify your template ID.
    templateId = "my-function-calling-template-with-no-function-schema-v1-0-0",
    // In `startChat`, provide the schema for any functions listed in your template.
    // This client-side schema will override any schema defined in the template.
    tools = listOf(fetchWeatherTool)
)

// Send a message that might trigger a function call.
...

// When the model responds with one or more function calls, invoke the function(s).
// Note that this is the same as when *not* using server prompt templates.
...

// Forward the structured input data from the model to the hypothetical external API.
...

Java 

For Java, using server prompt templates with multi-turn interactions is not yet supported. Check back soon!

Web 

// ...

// Initialize your desired Gemini API backend service.
...

// Create a `TemplateGenerativeModel` instance.
...

// Start a chat session with a template that has functions listed as tools.
const chatSessionWithSchemaOverride = model.startChat({
  // Specify your template ID.
  templateId: 'my-function-calling-template-with-no-function-schema-v1-0-0',
  // In `startChat`, provide the schema for any functions listed in your template.
  // This client-side schema will override any schema defined in the template.
  tools: [
    {
      functionDeclarations: [
        {
          name: "fetchWeather",
          parameters: {
            type: Type.OBJECT,
            properties: {
              location: {
                type: Type.OBJECT,
                description: "The name of the city and its state for which to get the weather. Only cities in the USA are supported.",
                properties: {
                  city: {
                    type: Type.STRING,
                    description: "The city of the location."
                  },
                  state: {
                    type: Type.STRING,
                    description: "The state of the location."
                  },
                  zipCode: {
                    type: Type.INTEGER,
                    description: "Optional zip code of the location.",
                    nullable: true
                  },
                },
                required: ["city", "state"],
              },
              date: {
                type: Type.STRING,
                description: "The date for which to get the weather. Date must be in the format: YYYY-MM-DD.",
              },
              unit: {
                type: Type.STRING,
                description: "The temperature unit.",
                enum: ["CELSIUS", "FAHRENHEIT"],
                nullable: true,
              },
            },
            required: ["location", "date"],
          },
        },
      ],
    }
  ],
});

// Send a message that might trigger a function call.
...

// When the model responds with one or more function calls, invoke the function(s).
// Note that this is the same as when *not* using server prompt templates.
...

Dart 

// ...

// Initialize your desired Gemini API backend service.
// Create a `TemplateGenerativeModel` instance.
...

// Start a chat session with a template that has functions listed as tools.
final chatSessionWithSchemaOverride = model?.startChat(
      // Specify your template ID.
      'my-function-calling-template-with-no-function-schema-v1-0-0',
      inputs: {},
      // In `startChat`, provide the schema for any functions listed in your template.
      // This client-side schema will override any schema defined in the template.
      tools: [
        TemplateTool.functionDeclarations(
          [
            TemplateFunctionDeclaration(
              'fetchWeather',
              parameters: {
                'location': JSONSchema.object(
                  description:
                      'The name of the city and its state for which to get '
                      'the weather. Only cities in the USA are supported.',
                  properties: {
                    'city': JSONSchema.string(
                      description: 'The city of the location.',
                    ),
                    'state': JSONSchema.string(
                      description: 'The state of the location.',
                    ),
                    'zipCode': JSONSchema.integer(
                      description: 'Optional zip code of the location.',
                      nullable: true,
                    ),
                  },
                  optionalProperties: ['zipCode'],
                ),
                'date': JSONSchema.string(
                  description: 'The date for which to get the weather. '
                      'Date must be in the format: YYYY-MM-DD.',
                ),
                'unit': JSONSchema.enumString(
                  enumValues: ['CELSIUS', 'FAHRENHEIT'],
                  description: 'The temperature unit.',
                  nullable: true,
                ),
              },
              optionalParameters: ['unit'],
            ),
          ],
        ),
      ],
    );

// Send a message that might trigger a function call.
...

// Check if the model wants to call a function.
// Note that this is the same as when *not* using server prompt templates.
...

Unity 

// ...

// Initialize your desired Gemini API backend service.
...

// Create a `TemplateGenerativeModel` instance.
...

// Define the schema for any functions listed in your template.
var fetchWeatherTool = new TemplateTool.FunctionDeclaration(
    name: "fetchWeather",
    parameters: new Dictionary<string, JsonSchema>() {
        { "location", JsonSchema.Object(
            description: "The name of the city and its state for which to get the weather. Only cities in the USA are supported.",
            properties: new Dictionary<string, JsonSchema>() {
                { "city", JsonSchema.String(description: "The city of the location.") },
                { "state", JsonSchema.String(description: "The state of the location.") },
                { "zipCode", JsonSchema.Int(description: "Optional zip code of the location.", nullable: true) }
            },
            optionalProperties: new[] { "zipCode" })
        },
        { "date", JsonSchema.String(description: "The date for which to get the weather. Date must be in the format: YYYY-MM-DD.")},
        { "unit", JsonSchema.Enum(
            values: new[] { "CELSIUS", "FAHRENHEIT" },
            description: "The temperature unit.",
            nullable: true)
        }
    },
    optionalParameters: new[] { "unit" }
);

// Start a chat session with a template that has functions listed as tools.
var chatSessionWithSchemaOverride = model.StartChat(
    // Specify your template ID.
    templateId: "my-function-calling-template-with-no-function-schema-v1-0-0",
    // In `startChat`, provide the schema for any functions listed in your template.
    // This client-side schema will override any schema defined in the template.
    tools: new[] { fetchWeatherTool }
);

try
{
   // Send a message that might trigger a function call.
   ...

  // When the model responds with one or more function calls, invoke the function(s).
  // Note that this is the same as when *not* using server prompt templates.
  ...
}

// ...


A seguir