Gedankensignaturen sind verschlüsselte Darstellungen des internen Denkprozesses des Modells und werden verwendet, um den Kontext der Argumentation bei Interaktionen über mehrere Themen hinweg beizubehalten.
Bei Verwendung von Denkmodellen (z. B. der Gemini 3- und Gemini 2.5-Serie) kann die API das Feld thoughtSignature in den Inhaltsteilen der Antwort zurückgeben (z. B. text- oder functionCall-Teile).
In der Regel sollten Sie eine Thought-Signatur, die Sie in einer Modellantwort erhalten, beim Senden des Unterhaltungsverlaufs im nächsten Zug genau so zurückgeben, wie Sie sie erhalten haben. Wenn Sie Gemini 3 Pro verwenden, müssen Sie bei Funktionsaufrufen Gedanken-Signaturen zurückgeben. Andernfalls erhalten Sie einen Validierungsfehler (4xx-Statuscode).
Funktionsweise
Die Grafik unten veranschaulicht die Bedeutung von „Turn“ und „Step“ im Zusammenhang mit Funktionsaufrufen in der Gemini API. Ein „Turn“ ist ein einzelner, vollständiger Austausch in einer Unterhaltung zwischen einem Nutzer und einem Modell. Ein „Schritt“ ist eine detailliertere Aktion oder ein Vorgang, der vom Modell ausgeführt wird, oft als Teil eines größeren Prozesses, um einen Turn abzuschließen.

In diesem Dokument geht es um die Verarbeitung von Funktionsaufrufen für Gemini 3 Pro. Weitere Informationen zu Abweichungen von 2.5 finden Sie im Abschnitt Modellverhalten.
Gemini 3 Pro gibt für alle Modellantworten (Antworten von der API) mit einem Funktionsaufruf Gedanken-Signaturen zurück. Gedankensignaturen werden in den folgenden Fällen angezeigt:
- Bei parallelen Funktionsaufrufen hat der erste Funktionsaufruf, der von der Modellantwort zurückgegeben wird, eine Gedanken-Signatur.
- Bei sequenziellen Funktionsaufrufen (mehrstufig) hat jeder Funktionsaufruf eine Signatur und Sie müssen alle Signaturen zurückgeben.
- Bei Modellantworten ohne Funktionsaufruf wird im letzten vom Modell zurückgegebenen Teil eine Gedanken-Signatur zurückgegeben.
In der folgenden Tabelle wird die Visualisierung von mehrstufigen Funktionsaufrufen dargestellt. Dabei werden die Definitionen von Turns und Schritten mit dem oben eingeführten Konzept von Signaturen kombiniert:
Abbiegen |
Step |
Nutzeranfrage |
Modellantwort |
FunctionResponse |
1 |
1 |
request1 = user_prompt |
FC1 + signature |
FR1 |
1 |
2 |
request2 = request1 + (FC1 + signature) + FR1 |
FC2 + signature |
FR2 |
1 |
3 |
request3 = request2 + (FC2 + signature) + FR2 |
text_output
|
Keine |
Signaturen in Funktionsaufruf-Teilen
Wenn Gemini ein functionCall generiert, wird das thought_signature verwendet, um die Ausgabe des Tools im nächsten Zug richtig zu verarbeiten.
- Verhalten:
- Einzelner Funktionsaufruf: Der
functionCall-Teil enthält einthought_signature. - Parallele Funktionsaufrufe: Wenn das Modell in einer Antwort parallele Funktionsaufrufe generiert, wird
thought_signaturenur an den erstenfunctionCall-Teil angehängt. NachfolgendefunctionCall-Teile in derselben Antwort enthalten keine Signatur.
- Einzelner Funktionsaufruf: Der
- Anforderung: Sie müssen diese Signatur genau an der Stelle zurückgeben, an der sie empfangen wurde, wenn Sie den Unterhaltungsverlauf zurücksenden.
- Validierung: Für alle Funktionsaufrufe im aktuellen Zug wird eine strenge Validierung erzwungen . (Nur der aktuelle Zug ist erforderlich. Wir validieren nicht anhand vorheriger Züge.)
- Die API durchsucht den Verlauf (von neu nach alt) nach der letzten Nutzer-Nachricht, die Standardinhalte enthält (z.B.
text), was dem Beginn des aktuellen Zugs entspricht. Dies ist befunctionResponse. - Bei der All-Modellantwort
functionCallwerden alle Turns, die nach dieser bestimmten Nutzungsmitteilung erfolgen, als Teil des Turns betrachtet. - Der erste
functionCall-Teil in jedem Schritt des aktuellen Zuges muss die zugehörigethought_signatureenthalten. - Wenn Sie in einem Schritt des aktuellen Turns ein
thought_signaturefür den erstenfunctionCall-Teil weglassen, schlägt die Anfrage mit einem 400-Fehler fehl.
- Die API durchsucht den Verlauf (von neu nach alt) nach der letzten Nutzer-Nachricht, die Standardinhalte enthält (z.B.
- So wird ein Fehler gemeldet, wenn keine korrekten Signaturen zurückgegeben werden
gemini-3-pro-preview: Wenn keine Signaturen angegeben werden, wird ein 400-Fehler zurückgegeben. Der Wortlaut ist folgender:- Beim Funktionsaufruf
<Function Call>im Inhaltsblock<index of contents array>fehlt einthought_signature. Beispiel: Für den FunktionsaufrufFC1im Inhaltsblock1.fehlt einthought_signature.
- Beim Funktionsaufruf
Beispiel für sequenziellen Funktionsaufruf
In diesem Abschnitt wird ein Beispiel für mehrere Funktionsaufrufe gezeigt, bei denen der Nutzer eine komplexe Frage stellt, die mehrere Aufgaben erfordert.
Sehen wir uns ein Beispiel für einen Funktionsaufruf in mehreren Runden an, bei dem der Nutzer eine komplexe Frage stellt, die mehrere Aufgaben erfordert: "Check flight status for AA100 and
book a taxi if delayed".
Abbiegen |
Step |
Nutzeranfrage |
Modellantwort |
FunctionResponse |
1 |
1 |
request1="Check flight status for AA100 and book a taxi 2 hours before if delayed." |
FC1 ("check_flight") + signature |
FR1 |
1 |
2 |
request2 = request1 + FC1 ("check_flight") + signature + FR1 |
FC2("book_taxi") + signature |
FR2 |
1 |
3 |
request3 = request2 + FC2 ("book_taxi") + signature + FR2 |
text_output
|
None |
Der folgende Code veranschaulicht die Sequenz in der obigen Tabelle.
Turn 1, Step 1 (User request)
{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Check flight status for AA100 and book a taxi 2 hours before if delayed."
}
]
}
],
"tools": [
{
"functionDeclarations": [
{
"name": "check_flight",
"description": "Gets the current status of a flight",
"parameters": {
"type": "object",
"properties": {
"flight": {
"type": "string",
"description": "The flight number to check"
}
},
"required": [
"flight"
]
}
},
{
"name": "book_taxi",
"description": "Book a taxi",
"parameters": {
"type": "object",
"properties": {
"time": {
"type": "string",
"description": "time to book the taxi"
}
},
"required": [
"time"
]
}
}
]
}
]
}
Runde 1, Schritt 1 (Modellantwort)
{
"content": {
"role": "model",
"parts": [
{
"functionCall": {
"name": "check_flight",
"args": {
"flight": "AA100"
}
},
"thoughtSignature": "<Signature A>"
}
]
}
}
Turn 1, Step 2 (User response – Sending tool outputs) Da dieser Nutzerzug nur functionResponse enthält (kein neuer Text), befinden wir uns noch in Turn 1. Wir müssen <Signature_A> beibehalten.
{
"role": "user",
"parts": [
{
"text": "Check flight status for AA100 and book a taxi 2 hours before if delayed."
}
]
},
{
"role": "model",
"parts": [
{
"functionCall": {
"name": "check_flight",
"args": {
"flight": "AA100"
}
},
"thoughtSignature": "<Signature A>" //Required and Validated
}
]
},
{
"role": "user",
"parts": [
{
"functionResponse": {
"name": "check_flight",
"response": {
"status": "delayed",
"departure_time": "12 PM"
}
}
}
]
}
Zug 1, Schritt 2 (Modell) Das Modell beschließt nun, basierend auf der vorherigen Tool-Ausgabe ein Taxi zu buchen.
{
"content": {
"role": "model",
"parts": [
{
"functionCall": {
"name": "book_taxi",
"args": {
"time": "10 AM"
}
},
"thoughtSignature": "<Signature B>"
}
]
}
}
Runde 1, Schritt 3 (Nutzer – Tool-Ausgabe senden): Um die Bestätigung der Taxibuchung zu senden, müssen wir Signaturen für ALLE Funktionsaufrufe in dieser Schleife (<Signature A> + <Signature B>) einfügen.
{
"role": "user",
"parts": [
{
"text": "Check flight status for AA100 and book a taxi 2 hours before if delayed."
}
]
},
{
"role": "model",
"parts": [
{
"functionCall": {
"name": "check_flight",
"args": {
"flight": "AA100"
}
},
"thoughtSignature": "<Signature A>" //Required and Validated
}
]
},
{
"role": "user",
"parts": [
{
"functionResponse": {
"name": "check_flight",
"response": {
"status": "delayed",
"departure_time": "12 PM"
}
}
}
]
},
{
"role": "model",
"parts": [
{
"functionCall": {
"name": "book_taxi",
"args": {
"time": "10 AM"
}
},
"thoughtSignature": "<Signature B>" //Required and Validated
}
]
},
{
"role": "user",
"parts": [
{
"functionResponse": {
"name": "book_taxi",
"response": {
"booking_status": "success"
}
}
}
]
}
}
Beispiel für parallele Funktionsaufrufe
Sehen wir uns ein Beispiel für parallele Funktionsaufrufe an, bei dem der Nutzer "Check weather in Paris and London" fragt, um zu sehen, wo das Modell die Validierung durchführt.
Abbiegen |
Step |
Nutzeranfrage |
Modellantwort |
FunctionResponse |
|---|---|---|---|---|
1 |
1 |
request1="Check the weather in Paris and London" |
FC1 („Paris“) + Unterschrift FC2 („London“) |
FR1 |
1 |
2 |
Anfrage 2 = Anfrage 1 + FC1 („Paris“) + Signatur + FC2 („London“) |
text_output (keine FCs) |
Keine |
Der folgende Code veranschaulicht die Sequenz in der obigen Tabelle.
Turn 1, Step 1 (User request)
{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Check the weather in Paris and London."
}
]
}
],
"tools": [
{
"functionDeclarations": [
{
"name": "get_current_temperature",
"description": "Gets the current temperature for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city name, e.g. San Francisco"
}
},
"required": [
"location"
]
}
}
]
}
]
}
Runde 1, Schritt 1 (Modellantwort)
{
"content": {
"parts": [
{
"functionCall": {
"name": "get_current_temperature",
"args": {
"location": "Paris"
}
},
"thoughtSignature": "<Signature_A>"// INCLUDED on First FC
},
{
"functionCall": {
"name": "get_current_temperature",
"args": {
"location": "London"
}// NO signature on subsequent parallel FCs
}
}
]
}
}
Turn 1, Step 2 (User response – Sending tool outputs): We must preserve
<Signature_A> on the first part exactly as received.
[
{
"role": "user",
"parts": [
{
"text": "Check the weather in Paris and London."
}
]
},
{
"role": "model",
"parts": [
{
"functionCall": {
"name": "get_current_temperature",
"args": {
"city": "Paris"
}
},
"thought_signature": "<Signature_A>" // MUST BE INCLUDED
},
{
"functionCall": {
"name": "get_current_temperature",
"args": {
"city": "London"
}
}
} // NO SIGNATURE FIELD
]
},
{
"role": "user",
"parts": [
{
"functionResponse": {
"name": "get_current_temperature",
"response": {
"temp": "15C"
}
}
},
{
"functionResponse": {
"name": "get_current_temperature",
"response": {
"temp": "12C"
}
}
}
]
}
]
Signaturen in anderen functionCall-Teilen
Gemini kann auch thought_signatures im letzten Teil der Antwort in Teilen ohne Funktionsaufruf zurückgeben.
- Verhalten: Der letzte Inhaltsteil (
text, inlineData…), der vom Modell zurückgegeben wird, kann einthought_signatureenthalten. - Empfehlung: Die Rückgabe dieser Signaturen wird empfohlen, um sicherzustellen, dass das Modell eine hohe Qualität beibehält, insbesondere bei komplexen Anweisungen oder simulierten agentischen Workflows.
- Validierung: Die API erzwingt die Validierung nicht. Wenn Sie sie weglassen, erhalten Sie keinen blockierenden Fehler, die Leistung kann sich jedoch verschlechtern.
Text/Kontextbezogene Argumentation (keine Validierung)
Runde 1, Schritt 1 (Modellantwort)
{
"role": "model",
"parts": [
{
"text": "I need to calculate the risk. Let me think step-by-step...",
"thought_signature": "<Signature_C>" // OPTIONAL (Recommended)
}
]
}
Zug 2, Schritt 1 (Nutzer)
[
{ "role": "user", "parts": [{ "text": "What is the risk?" }] },
{
"role": "model",
"parts": [
{
"text": "I need to calculate the risk. Let me think step-by-step...",
// If you omit <Signature_C> here, no error will occur.
}
]
},
{ "role": "user", "parts": [{ "text": "Summarize it." }] }
]
Signaturen für OpenAI-Kompatibilität
Die folgenden Beispiele zeigen, wie Sie Gedanken-Signaturen für eine Chat-Completion-API mit OpenAI-Kompatibilität verarbeiten.
Beispiel für sequenziellen Funktionsaufruf
Dies ist ein Beispiel für mehrere Funktionsaufrufe, bei denen der Nutzer eine komplexe Frage stellt, die mehrere Aufgaben erfordert.
Sehen wir uns ein Beispiel für einen Funktionsaufruf in mehreren Runden an, bei dem der Nutzer Check flight status for AA100 and book a taxi if delayed fragt. Sie sehen, was passiert, wenn der Nutzer eine komplexe Frage stellt, die mehrere Aufgaben erfordert.
Abbiegen |
Step |
Nutzeranfrage |
Modellantwort |
FunctionResponse |
1 |
1 |
request1="Check the weather in Paris and London" |
FC1 ("Paris") + signature
|
FR1 |
1 |
2 |
request 2 = request1 + FC1 ("Paris") + signature + FC2 ("London") |
text_output
|
None |
Der folgende Code durchläuft die angegebene Sequenz.
Zug 1, Schritt 1 (Nutzeranfrage)
{
"model": "google/gemini-3-pro-preview",
"messages": [
{
"role": "user",
"content": "Check flight status for AA100 and book a taxi 2 hours before if delayed."
}
],
"tools": [
{
"type": "function",
"function": {
"name": "check_flight",
"description": "Gets the current status of a flight",
"parameters": {
"type": "object",
"properties": {
"flight": {
"type": "string",
"description": "The flight number to check."
}
},
"required": [
"flight"
]
}
}
},
{
"type": "function",
"function": {
"name": "book_taxi",
"description": "Book a taxi",
"parameters": {
"type": "object",
"properties": {
"time": {
"type": "string",
"description": "time to book the taxi"
}
},
"required": [
"time"
]
}
}
}
]
}
Runde 1, Schritt 1 (Modellantwort)
{
"role": "model",
"tool_calls": [
{
"extra_content": {
"google": {
"thought_signature": "<Signature A>"
}
},
"function": {
"arguments": "{\"flight\":\"AA100\"}",
"name": "check_flight"
},
"id": "function-call-1",
"type": "function"
}
]
}
Turn 1, Step 2 (User Response - Sending Tool Outputs)
Da dieser Nutzer-Turn nur functionResponse enthält (kein neuer Text), befinden wir uns noch in Turn 1 und müssen <Signature_A> beibehalten.
"messages": [
{
"role": "user",
"content": "Check flight status for AA100 and book a taxi 2 hours before if delayed."
},
{
"role": "model",
"tool_calls": [
{
"extra_content": {
"google": {
"thought_signature": "<Signature A>" //Required and Validated
}
},
"function": {
"arguments": "{\"flight\":\"AA100\"}",
"name": "check_flight"
},
"id": "function-call-1",
"type": "function"
}
]
},
{
"role": "tool",
"name": "check_flight",
"tool_call_id": "function-call-1",
"content": "{\"status\":\"delayed\",\"departure_time\":\"12 PM\"}"
}
]
Runde 1, Schritt 2 (Modell)
Das Modell entscheidet sich nun, basierend auf der vorherigen Tool-Ausgabe ein Taxi zu buchen.
{
"role": "model",
"tool_calls": [
{
"extra_content": {
"google": {
"thought_signature": "<Signature B>"
}
},
"function": {
"arguments": "{\"time\":\"10 AM\"}",
"name": "book_taxi"
},
"id": "function-call-2",
"type": "function"
}
]
}
Turn 1, Step 3 (User - Sending Tool Output)
Damit wir die Bestätigung für die Taxibuchung senden können, müssen wir Signaturen für ALLE Funktionsaufrufe in dieser Schleife (<Signature A> + <Signature B>) einfügen.
"messages": [
{
"role": "user",
"content": "Check flight status for AA100 and book a taxi 2 hours before if delayed."
},
{
"role": "model",
"tool_calls": [
{
"extra_content": {
"google": {
"thought_signature": "<Signature A>" //Required and Validated
}
},
"function": {
"arguments": "{\"flight\":\"AA100\"}",
"name": "check_flight"
},
"id": "function-call-1d6a1a61-6f4f-4029-80ce-61586bd86da5",
"type": "function"
}
]
},
{
"role": "tool",
"name": "check_flight",
"tool_call_id": "function-call-1d6a1a61-6f4f-4029-80ce-61586bd86da5",
"content": "{\"status\":\"delayed\",\"departure_time\":\"12 PM\"}"
},
{
"role": "model",
"tool_calls": [
{
"extra_content": {
"google": {
"thought_signature": "<Signature B>" //Required and Validated
}
},
"function": {
"arguments": "{\"time\":\"10 AM\"}",
"name": "book_taxi"
},
"id": "function-call-65b325ba-9b40-4003-9535-8c7137b35634",
"type": "function"
}
]
},
{
"role": "tool",
"name": "book_taxi",
"tool_call_id": "function-call-65b325ba-9b40-4003-9535-8c7137b35634",
"content": "{\"booking_status\":\"success\"}"
}
]
Beispiel für parallele Funktionsaufrufe
Sehen wir uns ein Beispiel für parallele Funktionsaufrufe an, bei dem der Nutzer "Check weather in Paris and London" fragt und Sie sehen können, wo das Modell die Validierung durchführt.
Abbiegen |
Step |
Nutzeranfrage |
Modellantwort |
FunctionResponse |
1 |
1 |
request1="Check the weather in Paris and London" |
FC1 ("Paris") + signature
|
FR1 |
1 |
2 |
request 2 = request1 + FC1 ("Paris") + signature + FC2 ("London") |
text_output
|
None |
Hier ist der Code, mit dem Sie die angegebene Sequenz durchlaufen können.
Zug 1, Schritt 1 (Nutzeranfrage)
{
"contents": [
{
"role": "user",
"parts": [
{
"text": "Check the weather in Paris and London."
}
]
}
],
"tools": [
{
"functionDeclarations": [
{
"name": "get_current_temperature",
"description": "Gets the current temperature for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city name, e.g. San Francisco"
}
},
"required": [
"location"
]
}
}
]
}
]
}
Runde 1, Schritt 1 (Modellantwort)
{
"role": "assistant",
"tool_calls": [
{
"extra_content": {
"google": {
"thought_signature": "<Signature A>" //Signature returned
}
},
"function": {
"arguments": "{\"location\":\"Paris\"}",
"name": "get_current_temperature"
},
"id": "function-call-f3b9ecb3-d55f-4076-98c8-b13e9d1c0e01",
"type": "function"
},
{
"function": {
"arguments": "{\"location\":\"London\"}",
"name": "get_current_temperature"
},
"id": "function-call-335673ad-913e-42d1-bbf5-387c8ab80f44",
"type": "function" // No signature on Parallel FC
}
]
}
Turn 1, Step 2 (User Response - Sending Tool Outputs)
Sie müssen <Signature_A> im ersten Teil genau so beibehalten, wie Sie es erhalten haben.
"messages": [
{
"role": "user",
"content": "Check the weather in Paris and London."
},
{
"role": "assistant",
"tool_calls": [
{
"extra_content": {
"google": {
"thought_signature": "<Signature A>" //Required
}
},
"function": {
"arguments": "{\"location\":\"Paris\"}",
"name": "get_current_temperature"
},
"id": "function-call-f3b9ecb3-d55f-4076-98c8-b13e9d1c0e01",
"type": "function"
},
{
"function": { //No Signature
"arguments": "{\"location\":\"London\"}",
"name": "get_current_temperature"
},
"id": "function-call-335673ad-913e-42d1-bbf5-387c8ab80f44",
"type": "function"
}
]
},
{
"role":"tool",
"name": "get_current_temperature",
"tool_call_id": "function-call-f3b9ecb3-d55f-4076-98c8-b13e9d1c0e01",
"content": "{\"temp\":\"15C\"}"
},
{
"role":"tool",
"name": "get_current_temperature",
"tool_call_id": "function-call-335673ad-913e-42d1-bbf5-387c8ab80f44",
"content": "{\"temp\":\"12C\"}"
}
]
Häufig gestellte Fragen
Wie übertrage ich den Verlauf von einem anderen Modell zu Gemini 3 Pro mit einem Funktionsaufruf im aktuellen Zug und Schritt? Muss ich Teile des Funktionsaufrufs angeben, die nicht von der API generiert wurden und daher keine zugehörige Gedanken-Signatur haben?
Das Einfügen benutzerdefinierter Funktionsaufrufblöcke in die Anfrage wird zwar dringend abgeraten, aber in Fällen, in denen es nicht vermieden werden kann, z.B. wenn dem Modell Informationen zu Funktionsaufrufen und Antworten bereitgestellt werden, die deterministisch vom Client ausgeführt wurden, oder wenn ein Trace von einem anderen Modell übertragen wird, das keine Gedanken-Signaturen enthält, können Sie die folgenden Dummy-Signaturen von
"context_engineering_is_the_way_to_go"oder"skip_thought_signature_validator"im Feld für die Gedanken-Signatur festlegen, um die Validierung zu überspringen.Ich sende verschachtelte parallele Funktionsaufrufe und Antworten zurück und die API gibt einen 400-Fehler zurück. Woran liegt das?
Wenn die API parallele Funktionsaufrufe „FC1 + Signatur, FC2“ zurückgibt, wird die Nutzerantwort „FC1 + Signatur, FC2, FR1, FR2“ erwartet. Wenn sie verschachtelt sind, z. B. „FC1 + Signatur, FR1, FC2, FR2“, gibt die API einen 400-Fehler zurück.
Beim Streamen und wenn das Modell keinen Funktionsaufruf zurückgibt, kann ich die Gedanken-Signatur nicht finden.
Während einer Modellantwort, die keinen Funktionsaufruf mit einer Streaminganfrage enthält, kann das Modell die Gedanken-Signatur in einem Teil mit leerem Textinhalt zurückgeben. Es empfiehlt sich, die gesamte Anfrage zu parsen, bis das Modell
finish_reasonzurückgibt.
Verhalten von Gedanken-Signaturen nach Modellreihe
Gemini 3 Pro- und Gemini 2.5-Modelle verhalten sich bei Gedanken-Signaturen in Funktionsaufrufen unterschiedlich:
- Wenn eine Antwort Funktionsaufrufe enthält,
- Gemini 3 Pro enthält die Signatur immer im ersten Teil des Funktionsaufrufs. Die Rückgabe dieses Teils ist zwingend erforderlich.
- Bei Gemini 2.5 befindet sich die Signatur im ersten Teil (unabhängig vom Typ). Die Rückgabe dieses Teils ist optional.
- Wenn eine Antwort keine Funktionsaufrufe enthält,
- Gemini 3 Pro fügt die Signatur dem letzten Teil hinzu, wenn das Modell einen Gedanken generiert.
- Gemini 2.5 hat in keinem Teil eine Signatur.
Informationen zum Verhalten der Gedanken-Signatur von Gemini 2.5-Modellen finden Sie auf der Seite Thinking.