Execução do código

A API Gemini oferece uma ferramenta de execução de código que permite ao modelo gerar e executar código em Python. O modelo pode aprender de forma iterativa com os resultados da execução de código até chegar a uma saída final. Você pode usar a execução de código para criar aplicativos que se beneficiam do raciocínio baseado em código. Por exemplo, você pode usar a execução de código para resolver equações ou processar texto. Você também pode usar as bibliotecas incluídas no ambiente de execução de código para realizar tarefas mais especializadas.

O Gemini só pode executar código em Python. Você ainda pode pedir ao Gemini para gerar código em outro idioma, mas o modelo não pode usar a ferramenta de execução de código para executá-lo.

Ativar a execução de código

Para ativar a execução de código, configure a ferramenta de execução de código no modelo. Isso permite que o modelo gere e execute código.

Python

from google import genai from google.genai import types  client = genai.Client()  response = client.models.generate_content(     model="gemini-2.5-flash",     contents="What is the sum of the first 50 prime numbers? "     "Generate and run code for the calculation, and make sure you get all 50.",     config=types.GenerateContentConfig(         tools=[types.Tool(code_execution=types.ToolCodeExecution)]     ), )  for part in response.candidates[0].content.parts:     if part.text is not None:         print(part.text)     if part.executable_code is not None:         print(part.executable_code.code)     if part.code_execution_result is not None:         print(part.code_execution_result.output)

JavaScript

import { GoogleGenAI } from "@google/genai";  const ai = new GoogleGenAI({});  let response = await ai.models.generateContent({   model: "gemini-2.5-flash",   contents: [     "What is the sum of the first 50 prime numbers? " +       "Generate and run code for the calculation, and make sure you get all 50.",   ],   config: {     tools: [{ codeExecution: {} }],   }, });  const parts = response?.candidates?.[0]?.content?.parts || []; parts.forEach((part) => {   if (part.text) {     console.log(part.text);   }    if (part.executableCode && part.executableCode.code) {     console.log(part.executableCode.code);   }    if (part.codeExecutionResult && part.codeExecutionResult.output) {     console.log(part.codeExecutionResult.output);   } });

Go

package main  import (     "context"     "fmt"     "os"     "google.golang.org/genai" )  func main() {      ctx := context.Background()     client, err := genai.NewClient(ctx, nil)     if err != nil {         log.Fatal(err)     }      config := &genai.GenerateContentConfig{         Tools: []*genai.Tool{             {CodeExecution: &genai.ToolCodeExecution{}},         },     }      result, _ := client.Models.GenerateContent(         ctx,         "gemini-2.5-flash",         genai.Text("What is the sum of the first 50 prime numbers? " +                   "Generate and run code for the calculation, and make sure you get all 50."),         config,     )      fmt.Println(result.Text())     fmt.Println(result.ExecutableCode())     fmt.Println(result.CodeExecutionResult()) }

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \ -H "x-goog-api-key: $GEMINI_API_KEY" \ -H 'Content-Type: application/json' \ -d ' {"tools": [{"code_execution": {}}],     "contents": {       "parts":         {             "text": "What is the sum of the first 50 prime numbers? Generate and run code for the calculation, and make sure you get all 50."         }     }, }'

A saída pode ser semelhante a esta, que foi formatada para facilitar a leitura:

Okay, I need to calculate the sum of the first 50 prime numbers. Here's how I'll approach this:  1.  **Generate Prime Numbers:** I'll use an iterative method to find prime     numbers. I'll start with 2 and check if each subsequent number is divisible     by any number between 2 and its square root. If not, it's a prime. 2.  **Store Primes:** I'll store the prime numbers in a list until I have 50 of     them. 3.  **Calculate the Sum:**  Finally, I'll sum the prime numbers in the list.  Here's the Python code to do this:  def is_prime(n):   """Efficiently checks if a number is prime."""   if n <= 1:     return False   if n <= 3:     return True   if n % 2 == 0 or n % 3 == 0:     return False   i = 5   while i * i <= n:     if n % i == 0 or n % (i + 2) == 0:       return False     i += 6   return True  primes = [] num = 2 while len(primes) < 50:   if is_prime(num):     primes.append(num)   num += 1  sum_of_primes = sum(primes) print(f'{primes=}') print(f'{sum_of_primes=}')  primes=[2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67, 71, 73, 79, 83, 89, 97, 101, 103, 107, 109, 113, 127, 131, 137, 139, 149, 151, 157, 163, 167, 173, 179, 181, 191, 193, 197, 199, 211, 223, 227, 229] sum_of_primes=5117  The sum of the first 50 prime numbers is 5117.

Essa saída combina várias partes de conteúdo que o modelo retorna ao usar a execução de código:

  • text: texto inline gerado pelo modelo
  • executableCode: código gerado pelo modelo para ser executado
  • codeExecutionResult: resultado do código executável.

As convenções de nomenclatura dessas partes variam de acordo com a linguagem de programação.

Usar a execução de código na conversa

Você também pode usar a execução de código como parte de uma conversa.

Python

from google import genai from google.genai import types  client = genai.Client()  chat = client.chats.create(     model="gemini-2.5-flash",     config=types.GenerateContentConfig(         tools=[types.Tool(code_execution=types.ToolCodeExecution)]     ), )  response = chat.send_message("I have a math question for you.") print(response.text)  response = chat.send_message(     "What is the sum of the first 50 prime numbers? "     "Generate and run code for the calculation, and make sure you get all 50." )  for part in response.candidates[0].content.parts:     if part.text is not None:         print(part.text)     if part.executable_code is not None:         print(part.executable_code.code)     if part.code_execution_result is not None:         print(part.code_execution_result.output)

JavaScript

import {GoogleGenAI} from "@google/genai";  const ai = new GoogleGenAI({});  const chat = ai.chats.create({   model: "gemini-2.5-flash",   history: [     {       role: "user",       parts: [{ text: "I have a math question for you:" }],     },     {       role: "model",       parts: [{ text: "Great! I'm ready for your math question. Please ask away." }],     },   ],   config: {     tools: [{codeExecution:{}}],   } });  const response = await chat.sendMessage({   message: "What is the sum of the first 50 prime numbers? " +             "Generate and run code for the calculation, and make sure you get all 50." }); console.log("Chat response:", response.text);

Go

package main  import (     "context"     "fmt"     "os"     "google.golang.org/genai" )  func main() {      ctx := context.Background()     client, err := genai.NewClient(ctx, nil)     if err != nil {         log.Fatal(err)     }      config := &genai.GenerateContentConfig{         Tools: []*genai.Tool{             {CodeExecution: &genai.ToolCodeExecution{}},         },     }      chat, _ := client.Chats.Create(         ctx,         "gemini-2.5-flash",         config,         nil,     )      result, _ := chat.SendMessage(                     ctx,                     genai.Part{Text: "What is the sum of the first 50 prime numbers? " +                                           "Generate and run code for the calculation, and " +                                           "make sure you get all 50.",                               },                 )      fmt.Println(result.Text())     fmt.Println(result.ExecutableCode())     fmt.Println(result.CodeExecutionResult()) }

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \ -H "x-goog-api-key: $GEMINI_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"tools": [{"code_execution": {}}],     "contents": [         {             "role": "user",             "parts": [{                 "text": "Can you print \"Hello world!\"?"             }]         },{             "role": "model",             "parts": [               {                 "text": ""               },               {                 "executable_code": {                   "language": "PYTHON",                   "code": "\nprint(\"hello world!\")\n"                 }               },               {                 "code_execution_result": {                   "outcome": "OUTCOME_OK",                   "output": "hello world!\n"                 }               },               {                 "text": "I have printed \"hello world!\" using the provided python code block. \n"               }             ],         },{             "role": "user",             "parts": [{                 "text": "What is the sum of the first 50 prime numbers? Generate and run code for the calculation, and make sure you get all 50."             }]         }     ] }'

Entrada/saída (E/S)

A partir do Gemini 2.0 Flash, a execução de código aceita entrada de arquivos e saída de gráficos. Com esses recursos de entrada e saída, você pode fazer upload de arquivos CSV e de texto, fazer perguntas sobre os arquivos e gerar gráficos do Matplotlib como parte da resposta. Os arquivos de saída são retornados como imagens inline na resposta.

Preços de E/S

Ao usar a E/S de execução de código, você recebe cobranças por tokens de entrada e saída:

Tokens de entrada:

  • Comando do usuário

Tokens de saída:

  • Código gerado pelo modelo
  • Saída da execução de código no ambiente de programação
  • Tokens de pensamento
  • Resumo gerado pelo modelo

Detalhes de E/S

Ao trabalhar com E/S de execução de código, fique atento aos seguintes detalhes técnicos:

  • O tempo de execução máximo do ambiente de código é de 30 segundos.
  • Se o ambiente de código gerar um erro, o modelo poderá decidir regenerar a saída de código. Isso pode acontecer até cinco vezes.
  • O tamanho máximo de entrada de arquivo é limitado pela janela de token do modelo. No AI Studio, usando o Gemini Flash 2.0, o tamanho máximo do arquivo de entrada é de 1 milhão de tokens (aproximadamente 2 MB para arquivos de texto dos tipos de entrada aceitos). Se você fizer upload de um arquivo muito grande, o AI Studio não vai permitir o envio.
  • A execução de código funciona melhor com arquivos de texto e CSV.
  • O arquivo de entrada pode ser transmitido em part.inlineData ou part.fileData (enviado por upload pela API Files), e o arquivo de saída sempre é retornado como part.inlineData.
Interação única Bidirecional (API Multimodal Live)
Modelos compatíveis Todos os modelos Gemini 2.0 e 2.5 Apenas modelos experimentais do Flash
Tipos de entrada de arquivo compatíveis .png, .jpeg, .csv, .xml, .cpp, .java, .py, .js, .ts .png, .jpeg, .csv, .xml, .cpp, .java, .py, .js, .ts
Bibliotecas de geração de gráficos compatíveis Matplotlib, seaborn Matplotlib, seaborn
Uso de várias ferramentas Sim (somente execução de código + embasamento) Sim

Faturamento

Não há cobrança extra para ativar a execução de código da API Gemini. Você vai receber cobranças na taxa atual de tokens de entrada e saída com base no modelo do Gemini que estiver usando.

Confira outras informações importantes sobre o faturamento da execução de código:

  • Você só é cobrado uma vez pelos tokens de entrada transmitidos ao modelo e pelos tokens de saída finais retornados a você pelo modelo.
  • Os tokens que representam o código gerado são contados como tokens de saída. O código gerado pode incluir texto e saída multimodal, como imagens.
  • Os resultados da execução de código também são contados como tokens de saída.

O modelo de faturamento é mostrado no diagrama a seguir:

modelo de faturamento de execução de código

  • Você recebe cobranças na taxa atual de tokens de entrada e saída com base no modelo do Gemini que está usando.
  • Se o Gemini usar a execução de código ao gerar sua resposta, o comando original, o código gerado e o resultado do código executado serão rotulados como tokens intermediários e cobrados como tokens de entrada.
  • Em seguida, o Gemini gera um resumo e retorna o código gerado, o resultado do código executado e o resumo final. Eles são cobrados como tokens de saída.
  • A API Gemini inclui uma contagem intermediária de tokens na resposta da API para que você saiba por que está recebendo tokens de entrada extras além do comando inicial.

Limitações

  • O modelo só pode gerar e executar código. Não é possível retornar outros artefatos, como arquivos de mídia.
  • Em alguns casos, ativar a execução de código pode levar a regressões em outras áreas da saída do modelo (por exemplo, escrever uma história).
  • Há algumas variações na capacidade dos diferentes modelos de usar a execução de código com sucesso.

Bibliotecas permitidas

O ambiente de execução de código inclui as seguintes bibliotecas:

  • attrs
  • xadrez
  • contourpy
  • fpdf
  • geopandas
  • imageio
  • jinja2
  • joblib
  • jsonschema
  • jsonschema-specifications
  • lxml
  • matplotlib
  • mpmath
  • numpy
  • opencv-python
  • openpyxl
  • empacotamento
  • pandas
  • pillow
  • protobuf
  • pylatex
  • pyparsing
  • PyPDF2
  • python-dateutil
  • python-docx
  • python-pptx
  • reportlab
  • scikit-learn
  • scipy
  • seaborn
  • six
  • striprtf
  • sympy
  • tabulate
  • tensorflow
  • toolz
  • xlrd

Não é possível instalar suas próprias bibliotecas.

A seguir