As assinaturas de raciocínio são representações criptografadas do processo de raciocínio interno do modelo. Elas preservam o estado de raciocínio do Gemini durante
conversas multiturnos e com várias etapas, o que pode ser útil ao usar
chamadas de função. As respostas podem incluir um campo thought_signature em qualquer parte do conteúdo (por exemplo, text, functionCall).
Os modelos do Gemini 3 aplicam uma validação mais rigorosa nas assinaturas de raciocínio do que as versões anteriores do Gemini, porque melhoram a performance do modelo para chamadas de função. Para garantir que o modelo mantenha o contexto completo em várias interações de uma conversa, retorne as assinaturas de raciocínio das respostas anteriores nas solicitações subsequentes, mesmo ao usar níveis de raciocínio MINIMAL. Se uma assinatura de raciocínio necessária não for retornada ao usar modelos do Gemini 3, o modelo vai retornar um erro 400.
Embora o Gemini 3 Pro Image não aplique essa validação, para garantir que o modelo mantenha o contexto completo em várias interações de uma conversa, ainda é necessário retornar as assinaturas de raciocínio das respostas anteriores nas solicitações subsequentes. O Gemini 3 Pro Image não retorna um erro 400 se uma assinatura de raciocínio não for retornada. Para exemplos de código relacionados à edição de imagens multiturnos
usando o Gemini 3 Pro Image, consulte
Exemplo de edição de imagens multiturnos usando assinaturas de raciocínio.
Se você estiver usando o SDK de IA generativa do Google (Python, Node.js, Go ou Java) e os recursos padrão de histórico de chat ou anexando a resposta completa do modelo ao histórico, as assinaturas de raciocínio serão processadas automaticamente.
Por que elas são importantes?
Quando um modelo de raciocínio chama uma ferramenta externa, ele pausa o processo de raciocínio interno. A assinatura de raciocínio atua como um "estado de salvamento", permitindo que o modelo retome a cadeia de raciocínio sem problemas depois que você fornecer o resultado da função. Sem assinaturas de raciocínio, o modelo "esquece" as etapas de raciocínio específicas durante a fase de execução da ferramenta. A transmissão da assinatura de volta garante:
- Continuidade do contexto:o modelo preserva e pode verificar as etapas de raciocínio que justificaram a chamada da ferramenta.
- Raciocínio complexo:permite tarefas com várias etapas em que a saída de uma ferramenta informa o raciocínio da próxima.
Preservação de raciocínio
Para o Gemini 3.5 Flash e modelos mais recentes, os raciocínios de interações anteriores são preservados por padrão. O serviço retém o histórico de raciocínio no contexto da conversa antes de transmiti-lo ao modelo.
Ao enviar o histórico de conversas, seja consistente com as interações anteriores: inclua o contexto completo (raciocínios, chamadas de função e respostas) ou omita-o completamente. Fornecer contexto parcial pode degradar a performance do modelo.
Assinaturas de raciocínio de outros modelos
Os modelos Flash-Lite não podem ler raciocínios gerados por modelos que não são Flash-Lite. Se uma solicitação para um modelo Flash-Lite incluir assinaturas de raciocínio geradas por um modelo que não é Flash-Lite, a solicitação não vai falhar. Em vez disso, o serviço descarta esses raciocínios do contexto do modelo. Por exemplo, isso acontece quando você envia uma solicitação para um modelo Flash-Lite com histórico de um modelo Gemini Flash ou Pro.
Interações e etapas
No contexto de chamadas de função, é importante entender a diferença entre interações e etapas:
- Uma interação representa uma troca de conversa completa, começando com um comando do usuário e terminando quando o modelo fornece uma resposta final que não é uma chamada de função para esse comando.
- Uma etapa ocorre em uma única interação quando o modelo invoca uma função e exige uma resposta de função para continuar o processo de raciocínio. Como mostrado no diagrama, uma única interação pode envolver várias etapas se o modelo precisar chamar várias funções sequencialmente para atender à solicitação do usuário.
Como usar assinaturas de raciocínio
A maneira mais simples de processar assinaturas de raciocínio é incluir todos os Parts de todas as mensagens anteriores no histórico de conversas ao enviar uma nova solicitação, exatamente como foram retornados pelo modelo.
Se você não estiver usando um dos SDKs de IA generativa do Google ou precisar modificar ou reduzir o histórico de conversas, garanta que as assinaturas de raciocínio sejam preservadas e enviadas de volta ao modelo.
Ao usar o SDK de IA generativa do Google (recomendado)
Ao usar os recursos de histórico de chat dos SDKs ou anexar o objeto do modelo's
content da resposta anterior aos contents da próxima
solicitação, as assinaturas serão processadas automaticamente.
O exemplo de Python a seguir mostra o processamento automático:
from google import genai
from google.genai.types import Content, FunctionDeclaration, GenerateContentConfig, Part, ThinkingConfig, Tool
client = genai.Client()
# 1. Define your tool
get_weather_declaration = FunctionDeclaration(
name="get_weather",
description="Gets the current weather temperature for a given location.",
parameters={
"type": "object",
"properties": {"location": {"type": "string"}},
"required": ["location"],
},
)
get_weather_tool = Tool(function_declarations=[get_weather_declaration])
# 2. Send a message that triggers the tool
prompt = "What's the weather like in London?"
response = client.models.generate_content(
model="gemini-3.5-flash",
contents=prompt,
config=GenerateContentConfig(
tools=[get_weather_tool],
thinking_config=ThinkingConfig(include_thoughts=True)
),
)
# 3. Handle the function call
function_call = response.function_calls[0]
location = function_call.args["location"]
print(f"Model wants to call: {function_call.name}")
# Execute your tool (for example, call an API)
# (This is a mock response for the example)
print(f"Calling external tool for: {location}")
function_response_data = {
"location": location,
"temperature": "30C",
}
# 4. Send the tool's result back
# Append this turn's messages to history for a final response.
# The `content` object automatically attaches the required thought_signature behind the scenes.
history = [
Content(role="user", parts=[Part(text=prompt)]),
response.candidates[0].content, # Signature preserved here
Content(
role="tool",
parts=[
Part.from_function_response(
name=function_call.name,
response=function_response_data,
)
],
)
]
response_2 = client.models.generate_content(
model="gemini-3.5-flash",
contents=history,
config=GenerateContentConfig(
tools=[get_weather_tool],
thinking_config=ThinkingConfig(include_thoughts=True)
),
)
# 5. Get the final, natural-language answer
print(f"\nFinal model response: {response_2.text}")
Ao usar REST ou processamento manual
Se você estiver interagindo diretamente com a API, implemente o processamento de assinatura com base nas regras a seguir para o Gemini 3 Pro:
- Chamada de função:
- Se a resposta do modelo contiver uma ou mais partes
functionCall, umathought_signatureserá necessária para o processamento correto. - Em casos de chamadas de função paralelas em uma única resposta, apenas a primeira parte
functionCallvai conter athought_signature. - Em casos de chamadas de função sequenciais em várias etapas em uma interação, cada parte
functionCallvai conter umathought_signature. - Regra: ao construir a próxima solicitação, inclua a
partque contém afunctionCalle a suathought_signatureexatamente como foi retornada pelo modelo. Para chamadas de função sequenciais (com várias etapas), a validação é realizada em todas as etapas da interação atual, e omitir umathought_signaturenecessária para a primeira partefunctionCallem qualquer etapa da interação atual resulta em um erro400. Uma interação começa com a mensagem do usuário mais recente que não é umafunctionResponse. - Se o modelo retornar chamadas de função paralelas (por exemplo,
FC1+signature,FC2), a resposta precisará conter todas as chamadas de função seguidas de todas as respostas de função (FC1+signature,FC2,FR1,FR2). As respostas intercaladas (FC1+signature,FR1,FC2,FR2) resultam em um erro400. - Há casos raros em que é necessário fornecer partes
functionCallque não foram geradas pela API e, portanto, não têm uma assinatura de raciocínio associada (por exemplo, ao transferir o histórico de um modelo que não inclui assinaturas de raciocínio). Você pode definirthought_signaturecomoskip_thought_signature_validator, mas isso deve ser um último recurso, já que afeta negativamente a performance do modelo.
- Se a resposta do modelo contiver uma ou mais partes
- Chamada de não função:
- Se a resposta do modelo não contiver uma
functionCall, ela poderá incluir umathought_signaturena últimapartda resposta (por exemplo, a última partetext). - Regra: incluir essa assinatura na próxima solicitação é
recomendado para melhor performance, mas omiti-la não vai causar um
erro. Ao fazer streaming, essa assinatura pode ser retornada em uma parte com conteúdo de texto vazio. Portanto, analise todas as partes até que
finish_reasonseja retornado pelo modelo.
- Se a resposta do modelo não contiver uma
Siga estas regras para garantir que o contexto do modelo seja preservado:
- Sempre envie a
thought_signaturede volta ao modelo dentro daPartoriginal. - Não mescle uma
Partque contenha uma assinatura com uma que não tenha. Isso interrompe o contexto posicional do raciocínio. - Não combine duas
Parts que contenham assinaturas, porque as strings de assinatura não podem ser mescladas.
Exemplo de chamada de função sequencial
O exemplo a seguir mostra uma chamada de função com várias etapas em que o usuário pergunta "Verifique o status do voo AA100 e reserve um táxi se houver atraso", o que exige várias tarefas.
REST
O exemplo a seguir demonstra como processar assinaturas de raciocínio em várias etapas em um fluxo de trabalho de chamada de função sequencial usando a API REST.
Interação 1, etapa 1 (solicitação do usuário)
{ "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" ] } } ] } ] }
Interação 1, etapa 1 (resposta do modelo)
{ "content": { "role": "model", "parts": [ { "functionCall": { "name": "check_flight", "args": { "flight": "AA100" } }, "thoughtSignature": "<SIGNATURE_A>" } ] } }
Interação 1, etapa 2 (resposta do usuário: envio de saídas de ferramentas)
Como essa interação do usuário contém apenas uma functionResponse (sem texto novo), ainda estamos na interação 1. É necessário preservar <SIGNATURE_A>.
{ "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>" } ] }, { "role": "user", "parts": [ { "functionResponse": { "name": "check_flight", "response": { "status": "delayed", "departure_time": "12 PM" } } } ] }
Interação 1, etapa 2 (resposta do modelo)
O modelo agora decide reservar um táxi com base na saída da ferramenta anterior.
{ "content": { "role": "model", "parts": [ { "functionCall": { "name": "book_taxi", "args": { "time": "10 AM" } }, "thoughtSignature": "<SIGNATURE_B>" } ] } }
Interação 1, etapa 3 (resposta do usuário: envio da saída da ferramenta)
Para enviar a confirmação da reserva de táxi, inclua assinaturas para todas
as chamadas de função neste loop (<SIGNATURE_A> e <SIGNATURE_B>).
{ "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>" } ] }, { "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>" } ] }, { "role": "user", "parts": [ { "functionResponse": { "name": "book_taxi", "response": { "booking_status": "success" } } } ] } }
Chat Completions
O exemplo a seguir demonstra como processar assinaturas de raciocínio em várias etapas em um fluxo de trabalho de chamada de função sequencial usando a API Chat Completions.
Interação 1, etapa 1 (solicitação do usuário)
{ "model": "google/gemini-3.1-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" ] } } } ] }
Interação 1, etapa 1 (resposta do modelo)
{ "role": "model", "tool_calls": [ { "extra_content": { "google": { "thought_signature": "<SIGNATURE_A>" } }, "function": { "arguments": "{\"flight\":\"AA100\"}", "name": "check_flight" }, "id": "function-call-1", "type": "function" } ] }
Interação 1, etapa 2 (resposta do usuário: envio de saídas de ferramentas)
Como essa interação do usuário contém apenas uma functionResponse (sem texto novo), ainda estamos na interação 1. É necessário preservar <SIGNATURE_A>.
"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>" } }, "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\"}" } ]
Interação 1, etapa 2 (resposta do modelo)
O modelo agora decide reservar um táxi com base na saída da ferramenta anterior.
{ "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" } ] }
Interação 1, etapa 3 (resposta do usuário: envio da saída da ferramenta)
Para enviar a confirmação da reserva de táxi, inclua assinaturas para todas
as chamadas de função neste loop (<SIGNATURE_A> e <SIGNATURE_B>).
"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>" } }, "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>" } }, "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\"}" } ]
Exemplo de chamada de função paralela
O exemplo a seguir mostra uma chamada de função paralela em que o usuário pergunta "Verifique o clima em Paris e Londres".
REST
O exemplo a seguir demonstra como processar assinaturas de raciocínio em um fluxo de trabalho de chamada de função paralela usando a API REST.
Interação 1, etapa 1 (solicitação do usuário)
{ "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" ] } } ] } ] }
Interação 1, etapa 1 (resposta do modelo)
{ "content": { "parts": [ { "functionCall": { "name": "get_current_temperature", "args": { "location": "Paris" } }, "thoughtSignature": "<SIGNATURE_A>" }, { "functionCall": { "name": "get_current_temperature", "args": { "location": "London" } } } ] } }
Interação 1, etapa 2 (resposta do usuário: envio de saídas de ferramentas)
É necessário preservar <SIGNATURE_A> na primeira parte exatamente como recebida.
[ { "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>" }, { "functionCall": { "name": "get_current_temperature", "args": { "city": "London" } } } ] }, { "role": "user", "parts": [ { "functionResponse": { "name": "get_current_temperature", "response": { "temp": "15C" } } }, { "functionResponse": { "functionResponse": { "name": "get_current_temperature", "response": { "temp": "12C" } } } ] } ]
Chat Completions
O exemplo a seguir demonstra como processar assinaturas de raciocínio em um fluxo de trabalho de chamada de função paralela usando a API Chat Completions.
Interação 1, etapa 1 (solicitação do usuário)
{ "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" ] } } ] } ] }
Interação 1, etapa 1 (resposta do modelo)
{ "role": "assistant", "tool_calls": [ { "extra_content": { "google": { "thought_signature": "<SIGNATURE_A>" } }, "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" } ] }
Interação 1, etapa 2 (resposta do usuário: envio de saídas de ferramentas)
É necessário preservar <SIGNATURE_A> na primeira parte exatamente como recebida.
"messages": [ { "role": "user", "content": "Check the weather in Paris and London." }, { "role": "assistant", "tool_calls": [ { "extra_content": { "google": { "thought_signature": "<SIGNATURE_A>" } }, "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" } ] }, { "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\"}" } ]
Assinaturas em Parts que não são functionCall
O Gemini também pode retornar uma thought_signature na Part final de uma resposta, mesmo que nenhuma chamada de função esteja presente.
- Comportamento:o conteúdo final
Part(text,inlineDataetc.) retornado pelo modelo pode conter umathought_signature. - Requisito:retornar essa assinatura é recomendado para garantir que o modelo mantenha um raciocínio de alta qualidade, especialmente para instruções complexas ou Agentic Workflows simulados.
- Validação:a API não aplica estritamente a validação de assinaturas em partes que não são
functionCall. Você não vai receber um erro de bloqueio se omiti-las, embora a performance possa ser degradada.
Exemplo de resposta do modelo com assinatura na parte de texto:
Os exemplos a seguir mostram uma resposta do modelo em que uma thought_signature é incluída em uma Part que não é functionCall e como processá-la em uma solicitação subsequente.
Interação 1, etapa 1 (resposta do modelo)
{ "role": "model", "parts": [ { "text": "I need to calculate the risk. Let me think step-by-step...", "thought_signature": "<SIGNATURE_C>" // OPTIONAL (Recommended) } ] }
Interação 2, etapa 1 (usuário)
[ { "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." }] } ]
Exemplo de edição de imagens multiturnos usando assinaturas de raciocínio
Os exemplos a seguir ilustram como recuperar e transmitir assinaturas de raciocínio durante a criação e edição de imagens multiturnos com o Gemini 3 Pro Image.
Interação 1: receba a resposta e salve os dados que incluem assinaturas de raciocínio
chat = client.chats.create( model="gemini-3-pro-image-preview", config=types.GenerateContentConfig( response_modalities=['TEXT', 'IMAGE'] ) ) message = "Create an image of a clear perfume bottle sitting on a vanity." response = chat.send_message(message) data = b'' for part in response.candidates[0].content.parts: if part.text: display(Markdown(part.text)) if part.inline_data: data = part.inline_data.data display(Image(data=data, width=500))
Interação 2: transmita os dados que incluem assinaturas de raciocínio
response = chat.send_message( message=[ types.Part.from_bytes( data=data, mime_type="image/png", ), "Make the perfume bottle purple and add a vase of hydrangeas next to the bottle.", ], ) for part in response.candidates[0].content.parts: if part.text: display(Markdown(part.text)) if part.inline_data: display(Image(data=part.inline_data.data, width=500))
A seguir
Raciocínio
Aprenda mais sobre os recursos de raciocínio do Gemini e como configurar os níveis de raciocínio.
Guia de comandos de raciocínio
Conheça as técnicas de engenharia de comandos e as práticas recomendadas personalizadas para modelos de raciocínio do Gemini.
Introdução às chamadas de função
Saiba como ativar os modelos do Gemini para usar ferramentas externas durante a geração de respostas usando chamadas de função.