Ejecuta código con la API de Gemini

En esta guía, se muestra cómo usar la función de ejecución de código de la API de Gemini, que permite que el modelo genere y ejecute código de Python para resolver problemas.

Cuándo usar la ejecución de código y cuándo usar la llamada a funciones

La API de Gemini proporciona dos herramientas principales para ejecutar tareas: la ejecución de código y las llamadas a funciones. El modelo decide qué herramienta usar en función de tu instrucción. En la siguiente tabla, se comparan estas dos herramientas.

Herramienta Descripción Característica clave Caso de uso
Ejecución de código El modelo genera y ejecuta código de Python en un entorno con estado y de zona de pruebas para resolver un problema. La herramienta controla la ejecución automáticamente. Ejecución automática: El modelo escribe y ejecuta el código sin tu intervención. Resolver cálculos complejos, realizar transformaciones de datos o abordar problemas de lógica en los que los pasos no están predefinidos Por ejemplo, "Calcula el vigésimo número de Fibonacci y encuentra el palíndromo más cercano".
Llamada a función El modelo identifica una función definida por el usuario que puede satisfacer una solicitud y devuelve el nombre y los argumentos de la función. Eres responsable de llamar a la función con los argumentos proporcionados. Requiere ejecución del usuario: El modelo proporciona los detalles de la llamada a la función. Debes ejecutar la función en tu entorno y devolver el resultado al modelo. Integrar el modelo con APIs externas o sistemas internos Por ejemplo, "¿Cómo está el clima en Boston?" podría activar una llamada a la función get_weather(location="Boston").

Modelos y limitaciones admitidos

Limitaciones

  • La función no admite E/S de archivos.
  • La ejecución de código puede durar un máximo de 30 segundos antes de que se agote el tiempo de espera.

Ejemplo de sintaxis

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

Consulta ejemplos para obtener detalles sobre la implementación.

Python

Para habilitar la ejecución de código, especifica un tool de ejecución de código en tu solicitud.

CodeExecution

Herramienta que ejecuta el código generado por el modelo y devuelve automáticamente el resultado al modelo. Consulta también ExecutableCode y CodeExecutionResult, que son la entrada y la salida de esta herramienta.

Part

executable_code

Opcional: ExecutableCode

Es el código generado por el modelo que se debe ejecutar.
Consulta Ejecución de código [API].

code_execution_result

Opcional: CodeExecutionResult

Es el resultado de ejecutar el [ExecutableCode].
Consulta Ejecución de código [API].

ExecutableCode

language

Obligatorio:string (enum)

Lenguajes de programación compatibles con el code generado.


Compatible:
  • PYTHON

code

Obligatorio:string

Es el código que se ejecutará.
Consulta Ejecución de código [API].

CodeExecutionResult

outcome

Obligatorio:string (enum)

Es el resultado de la ejecución del código.


Resultados posibles:
  • La ejecución del código se completó correctamente. (OUTCOME_OK)
  • La ejecución del código finalizó, pero con un error. stderr debe contener el motivo. (OUTCOME_FAILED)
  • La ejecución del código se realizó durante demasiado tiempo y se canceló. Puede haber o no un resultado parcial presente. (OUTCOME_DEADLINE_EXCEEDED)

output

Obligatorio:string

Contiene stdout cuando la ejecución del código se realiza correctamente, stderr o alguna otra descripción en caso contrario.
Consulta Ejecución de código [API].

Ejemplos

A continuación, se muestran ilustraciones de cómo puedes enviar una consulta y declaraciones de funciones al 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'

Habilita la ejecución de código en el modelo

Para habilitar la ejecución de código básica, consulta Ejecución de código.

¿Qué sigue?