This guide applies to any capability that depends on multi-turn interactions, including:
-
Multi-turn conversation (chat) , including text-output-only chat and iterative image editing
High-level overview
For multi-turn interactions, the Firebase AI Logic SDKs manage the state of the conversation. This applies when using server prompt templates, too.
The basic workflow for multi-turn interactions and server prompt templates is fundamentally the same as for single-turn requests, with some important differences:
-
Create the template using the guided UI in the Firebase console .
For multi-turn interactions, you must add the
{{history}}tag in the template's content, which tells the template where to inject the conversation turns managed by the client SDK. -
Test the template in a real request using the testing experience in the Firebase console.
For multi-turn interactions, the console testing experience can only help test the initial turn. You can test how subsequent turns (the history) are handled by using the template with your actual app.
-
Access the template from your app's code using
templateGenerativeModel.For multi-turn interactions, you must use
startChatandsendMessage(just like you do for multi-turn interactions when not using server prompt templates).
Note that for function calling , there are a few more differences, which are described in that section later on this page.
Multi-turn conversation (chat)
If you haven't already, review the general guide for building multi-turn conversations (chat) when not using server prompt templates.
Basic format of a server prompt template
For Firebase AI Logic , the Firebase console provides a guided UI for you to specify the template's frontmatter and contents.
Server prompt templates use a Dotprompt-based syntax and format. For more details, see Template format, syntax, and examples .
The example template below shows the most important components for a template
when building a multi-turn conversation (chat). Note the addition of the {{history}}
tag in the template's content,
which tells the template where to inject the conversation turns managed by the
client SDK.
---
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}}
Use your template in code
Click your Gemini API provider to view provider-specific content and code on this page.
The example client code below shows how to use the template in your code. Note
the use of templateGenerativeModel
along with startChat
and sendMessage
when building multi-turn interactions.
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}"
);
}
Function calling
If you haven't already, review the general guide for function calling when not using server prompt templates. This guide about using server prompt templates assumes that you understand how function calling works generally.
Basic format of a server prompt template
For Firebase AI Logic , the Firebase console provides a guided UI for you to specify the template's frontmatter and contents.
Server prompt templates use a Dotprompt-based syntax and format. For more details, see Template format, syntax, and examples .
The example template below shows the most important components for a template when using function calling. Note the following:
-
In the template's frontmatter, list the functions that the model has access to by providing function declarations in the
toolsobject.-
Define the
name(required) and thedescription(optional) for each function that the model has access to. -
Define the schema for each function that the model has access to.
This example template below assumes that you're defining function schemas in the template. However, you can instead provide the function's schema in the client code. Schema defined in client code will override any schema defined in the template. Later on this page, find an example of a template and client code for defining schema in client code .
-
-
In the template's content, add the
{{history}}tag, which tells the template where to inject the conversation turns managed by the client SDK.
Example template with function schema defined in template
---
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}}
Use your template in code
Click your Gemini API provider to view provider-specific content and code on this page.
The example client code below shows how to use the template in your code. Note the following:
-
Use
templateGenerativeModelalong withstartChatandsendMessagewhen using multi-turn interactions. -
During initialization of the model in your client code, do not list the functions that the model has access to. Instead, functions must be listed in the
toolsobject of the template's frontmatter (see above). -
This example client code below assumes that you're defining function schemas in the template. If you instead decide to define schema in your client code, it will override the template-defined schema. Later on this page, see an example template and client code for defining schema in client code .
-
Check whether the model returns a function call as part of fulfilling a request. If it does, your app needs to execute the local logic and then send the result back to the model.
Example client code with function schema defined in template
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}"
);
}
Function calling - define schema in client code
Make sure to review the sections above about how function calling works with
server prompt templates (in particular, the use of the {{history}}
tag in the content of the
template). This section here provides an example template and client code if you
want to define your function schema in client code (instead of in the template).
Note the following about defining function schema in client code:
-
If you define a function's schema in your client code (as shown in the example below), the client-side schema will override any template-defined schema for that function.
-
To define the function schema in client code, write the function declaration and then provide the declaration in
startChat, not during model initialization (which is what you do when not using server prompt templates). -
Even though the function declaration specifies a
name, the template must still list the functions that you want the model to have access to. Thenamein the template must match thenamein the client code.
Example template with function schema defined in client code
---
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}}
Example client code with function schema defined in client code (for details omitted from this example, see the example client code above )
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.
...
}
// ...
What's next?
-
Learn about best practices and considerations for using server prompt templates.
-
Learn details about the template format and syntax, along with examples .
-
Manage templates , including editing, locking, and version control.
