Executar código com a API Gemini

O recurso de execução de código da API Gemini permite que o modelo gere e execute código Python e aprenda de forma iterativa com os resultados até chegar a uma saída final. Use esse recurso para criar aplicativos que se beneficiam do raciocínio baseado em código e que produzem saídas de texto. Por exemplo, é possível usar a execução de código em um aplicativo que resolve equações ou processa textos.

A API Gemini inclui a execução de código como uma ferramenta, semelhante à chamada de função. Depois de adicionar a execução de código como uma ferramenta, o modelo decide quando usá-la.

Modelos compatíveis

Limitações

  • O recurso não oferece suporte a E/S de arquivos.
  • A execução do código pode durar no máximo 30 segundos antes do tempo limite.

Exemplo de sintaxe

curl

PROJECT_ID = myproject
REGION = us-central1
MODEL_ID = gemini-2.0-flash-001

https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/publishers/google/models/${MODEL_ID}:generateContent \
  -d '{
    "contents": [{
      ...
    }],
    "tools": [{
      "code_execution":  {}
    }]
  }'

Lista de parâmetros

Confira exemplos para detalhes de implementação.

Python

Para ativar a execução de código, especifique um tool de execução de código na solicitação.

CodeExecution

Ferramenta que executa o código gerado pelo modelo e retorna automaticamente o resultado para ele. Consulte também ExecutableCode e CodeExecutionResult, que são entradas e saídas para essa ferramenta.

Part

executable_code

Opcional: ExecutableCode

Código gerado pelo modelo que deve ser executado.
Consulte Execução de código [API].

code_execution_result

Opcional: CodeExecutionResult

Resultado da execução do [ExecutableCode].
Consulte Execução de código [API].

ExecutableCode

language

Obrigatório: string (enum)

Linguagens de programação compatíveis para o code gerado.


Compatível:
  • PYTHON

code

Obrigatório: string

O código a ser executado.
Consulte Execução de código [API].

CodeExecutionResult

outcome

Obrigatório: string (enum)

Resultado da execução do código.


Possíveis resultados:
  • A execução do código foi concluída. (OUTCOME_OK)
  • A execução do código foi concluída, mas com uma falha. stderr precisa conter o motivo. (OUTCOME_FAILED)
  • A execução do código demorou muito e foi cancelada. Pode haver ou não uma saída parcial. (OUTCOME_DEADLINE_EXCEEDED)

output

Obrigatório: string

Contém stdout quando a execução do código é bem-sucedida, stderr ou outra descrição.
Consulte Execução de código [API].

Exemplos

Confira ilustrações de como enviar uma consulta e declarações de função para o modelo.

Caso de uso básico

curl

PROJECT_ID = myproject
REGION = us-central1
MODEL_ID = gemini-2.0-flash-001

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/publishers/google/models/${MODEL_ID}:generateContent \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Calculate 20th fibonacci number. Then find the nearest palindrome to it."
      }]
    }],
    "tools": [{'codeExecution': {}}],
  }'

Python

from google import genai
from google.genai.types import Tool, ToolCodeExecution, GenerateContentConfig

client = genai.Client()
model_id = "gemini-2.0-flash-001"

code_execution_tool = Tool(
    code_execution=ToolCodeExecution()
)
response = client.models.generate_content(
    model=model_id,
    contents="Calculate 20th fibonacci number. Then find the nearest palindrome to it.",
    config=GenerateContentConfig(
        tools=[code_execution_tool],
        temperature=0,
    ),
)
for part in response.candidates[0].content.parts:
    if part.executable_code:
        print(part.executable_code)
    if part.code_execution_result:
        print(part.code_execution_result)
# Example response:
# code='...' language='PYTHON'
# outcome='OUTCOME_OK' output='The 20th Fibonacci number is: 6765\n'
# code='...' language='PYTHON'
# outcome='OUTCOME_OK' output='Lower Palindrome: 6666\nHigher Palindrome: 6776\nNearest Palindrome to 6765: 6776\n'

Ativar a execução de código no modelo

Para ativar a execução de código básica, consulte Execução de código.

A seguir