Esegui codice con l'API Gemini

Questa guida mostra come utilizzare la funzionalità di esecuzione del codice dell'API Gemini, che consente al modello di generare ed eseguire codice Python per risolvere i problemi.

Quando utilizzare l'esecuzione del codice e la chiamata di funzione

L'API Gemini fornisce due strumenti principali per l'esecuzione delle attività: l'esecuzione del codice e la chiamata di funzione. Il modello decide quale strumento utilizzare in base al prompt. La seguente tabella confronta questi due strumenti.

Strumento Descrizione Caratteristica chiave Caso d'uso
Esecuzione di codice Il modello genera ed esegue codice Python in un ambiente con stato e limitato tramite sandbox per risolvere un problema. Lo strumento gestisce automaticamente l'esecuzione. Esecuzione automatica: il modello scrive ed esegue il codice senza il tuo intervento. Risolvere calcoli complessi, eseguire trasformazioni dei dati o affrontare problemi di logica in cui i passaggi non sono predefiniti. Ad esempio, "Calcola il 20° numero di Fibonacci e trova il palindromo più vicino".
Chiamata di funzione Il modello identifica una funzione definita dall'utente;utente che può soddisfare una richiesta e restituisce il nome e gli argomenti della funzione. È tua responsabilità chiamare la funzione con gli argomenti forniti. Richiede l'esecuzione da parte dell'utente:il modello fornisce i dettagli della chiamata di funzione. Devi eseguire la funzione nel tuo ambiente e restituire il risultato al modello. Integrazione del modello con API esterne o sistemi interni. Ad esempio, "Che tempo fa a Boston?" potrebbe attivare una chiamata di funzione get_weather(location="Boston").

Modelli supportati e limitazioni

Limitazioni

  • La funzionalità non supporta l'I/O dei file.
  • L'esecuzione del codice può durare al massimo 30 secondi prima del timeout.

Sintassi di esempio

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":  {}
    }]
  }'

Elenco dei parametri

Per informazioni dettagliate sull'implementazione, consulta gli esempi.

Python

Per attivare l'esecuzione del codice, specifica un tool di esecuzione del codice nella richiesta.

CodeExecution

Strumento che esegue il codice generato dal modello e restituisce automaticamente il risultato al modello. Vedi anche ExecutableCode e CodeExecutionResult, che sono input e output di questo strumento.

Part

executable_code

(Facoltativo) ExecutableCode

Codice generato dal modello che deve essere eseguito.
Vedi Esecuzione del codice [API].

code_execution_result

(Facoltativo) CodeExecutionResult

Risultato dell'esecuzione di [ExecutableCode].
Vedi Esecuzione del codice [API].

ExecutableCode

language

Obbligatorio: string (enum)

Linguaggi di programmazione supportati per code generato.


Supportato:
  • PYTHON

code

Obbligatorio: string

Il codice da eseguire.
Vedi Esecuzione del codice [API].

CodeExecutionResult

outcome

Obbligatorio: string (enum)

Risultato dell'esecuzione del codice.


Possibili risultati:
  • Esecuzione del codice completata correttamente. (OUTCOME_OK)
  • L'esecuzione del codice è terminata, ma con un errore. stderr deve contenere il motivo. (OUTCOME_FAILED)
  • L'esecuzione del codice è durata troppo a lungo ed è stata annullata. Potrebbe essere presente o meno un output parziale. (OUTCOME_DEADLINE_EXCEEDED)

output

Obbligatorio: string

Contiene stdout quando l'esecuzione del codice va a buon fine, stderr o un'altra descrizione in caso contrario.
Vedi Esecuzione del codice [API].

Esempi

Ecco alcune illustrazioni di come puoi inviare una query e dichiarazioni di funzioni al modello.

Caso d'uso di base

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'

Abilita l'esecuzione del codice sul modello

Per attivare l'esecuzione di base del codice, consulta Esecuzione del codice.

Passaggi successivi