Chiamata di funzione per i modelli Grok

La chiamata di funzione ti consente di definire funzioni personalizzate e di fornire ai LLM la possibilità di chiamarle per recuperare informazioni in tempo reale o interagire con sistemi esterni come database SQL o strumenti di assistenza clienti.

Per ulteriori informazioni concettuali sulla chiamata di funzione, consulta Introduzione alla chiamata di funzione.

Utilizzare la chiamata di funzione con l'API Responses

I seguenti modelli mostrano come utilizzare la chiamata di funzione con l'API Responses:

Python

Prima di provare questo esempio, segui le istruzioni di configurazione Python nella guida rapida di Agent Platform per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Agent Platform, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

Prima di eseguire questo esempio, assicurati di impostare la variabile di ambiente OPENAI_BASE_URL o di configurare le credenziali OAuth. Per saperne di più, consulta Autenticazione e credenziali.

from openai import OpenAI
client = OpenAI()



response = client.responses.create(
    model="MODEL",
    input=[
        {"role": "user", "content": "CONTENT"}
    ],
    tools=[
        {
            "type": "function",
            "name": "FUNCTION_NAME",
            "description": "FUNCTION_DESCRIPTION",
            "parameters": PARAMETERS_OBJECT,
        }
    ],
    tool_choice="auto",
)
  • MODEL: il nome del modello che vuoi utilizzare, ad esempio xai/grok-4.20-reasoning.
  • CONTENT: il prompt dell'utente da inviare al modello.
  • FUNCTION_NAME: il nome della funzione da chiamare.
  • FUNCTION_DESCRIPTION: una descrizione della funzione.
  • PARAMETERS_OBJECT: un dizionario che definisce i parametri della funzione, ad esempio:
    {"type": "object", "properties": {"location": {"type": "string", "description": "The city and state"}}, "required": ["location"]}

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud.
  • MODEL: il nome del modello che vuoi utilizzare, ad esempio xai/grok-4.20-reasoning.
  • INPUT: il prompt o l'input per il modello.
  • FUNCTION_NAME: il nome della funzione da chiamare.
  • FUNCTION_DESCRIPTION: una descrizione della funzione.
  • PARAMETERS_OBJECT: un oggetto JSON che definisce i parametri della funzione.

Metodo HTTP e URL: 

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses

Corpo JSON della richiesta: 

{
  "model": "MODEL",
  "input": [
    {"role": "user", "content": "INPUT"}
  ],
  "tools": [
    {
      "type": "function",
      "name": "FUNCTION_NAME",
      "description": "FUNCTION_DESCRIPTION",
      "parameters": PARAMETERS_OBJECT
    }
  ],
  "tool_choice": "auto"
}

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses"

PowerShell

Salva il corpo della richiesta in un file denominato request.json, e quindi esegui il comando seguente: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses" | Select-Object -Expand Content
 

Esempio

I seguenti esempi mostrano un esempio completo di utilizzo della chiamata di funzione con l'API Responses:

Python

Prima di provare questo esempio, segui le istruzioni di configurazione Python nella guida rapida di Agent Platform per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Agent Platform, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

Prima di eseguire questo esempio, assicurati di impostare la variabile di ambiente OPENAI_BASE_URL o di configurare le credenziali OAuth. Per saperne di più, consulta Autenticazione e credenziali.

from openai import OpenAI
client = OpenAI()



response = client.responses.create(
    model="xai/grok-4.20-reasoning",
    input=[
        {"role": "user", "content": "What is the temperature in San Francisco?"}
    ],
    tools=[
        {
            "type": "function",
            "name": "get_temperature",
            "description": "Get current temperature for a location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "City name"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "fahrenheit"}
                },
                "required": ["location"]
            }
        }
    ],
    tool_choice="auto",
)
print(response)

REST

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses -d \
'{
  "model": "xai/grok-4.20-reasoning",
  "input": [
    {"role": "user", "content": "What is the temperature in San Francisco?"}
  ],
  "tools": [
    {
      "type": "function",
      "name": "get_temperature",
      "description": "Get current temperature for a location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {"type": "string", "description": "City name"},
          "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "fahrenheit"}
        },
        "required": ["location"]
      }
    }
  ]
}'
  • PROJECT_ID: l'ID del tuo progetto Google Cloud.

Risposta di esempio

Di seguito è riportato un esempio di come potrebbe apparire l'output del modello:

{
  "background": false,
  "completed_at": 1778893466,
  "created_at": 1778893464,
  "error": null,
  "frequency_penalty": 0,
  "id": "mMIHaqfCCIjUmAb_mMIHaqfCCIjUmAb_6LbAAg",
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "max_tool_calls": null,
  "metadata": {
    "system_fingerprint": "fp_39c5j0a3e9"
  },
  "model": "xai/grok-4.20-reasoning",
  "object": "response",
  "output": [
    {
      "arguments": "{\"location\":\"San Francisco\"}",
      "call_id": "call-81ad585c-9e8d-47bd-85ef-2ced8a8fc898-0",
      "id": "fc_mMIHaqfCCIjUmAb_6LbAAg",
      "name": "get_temperature",
      "status": "completed",
      "type": "function_call"
    }
  ],
  "parallel_tool_calls": true,
  "presence_penalty": 0,
  "previous_response_id": null,
  "prompt_cache_key": null,
  "reasoning": {
    "effort": "medium",
    "summary": "detailed"
  },
  "safety_identifier": null,
  "service_tier": "default",
  "status": "completed",
  "store": true,
  "temperature": 0.7,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [
    {
      "description": "Get current temperature for a location",
      "name": "get_temperature",
      "parameters": {
        "properties": {
          "location": {
            "description": "City name",
            "type": "string"
          },
          "unit": {
            "default": "fahrenheit",
            "enum": [
              "celsius",
              "fahrenheit"
            ],
            "type": "string"
          }
        },
        "required": [
          "location"
        ],
        "type": "object"
      },
      "strict": false,
      "type": "function"
    }
  ],
  "top_logprobs": 0,
  "top_p": 0.95,
  "truncation": "disabled",
  "usage": {
    "extra_properties": {
      "google": {
        "traffic_type": "ON_DEMAND"
      }
    },
    "input_tokens": 462,
    "input_tokens_details": {
      "cached_tokens": 320
    },
    "num_server_side_tools_used": 0,
    "num_sources_used": 0,
    "output_tokens": 187,
    "output_tokens_details": {
      "reasoning_tokens": 175
    },
    "total_tokens": 649
  },
  "user": null
}

Utilizzare la chiamata di funzione con l'API Chat Completions

I seguenti esempi mostrano come utilizzare la chiamata di funzione con i completamenti della chat.

Python

Prima di provare questo esempio, segui le istruzioni di configurazione Python nella guida rapida di Agent Platform per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Agent Platform, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

Prima di eseguire questo esempio, assicurati di impostare la variabile di ambiente OPENAI_BASE_URL o di configurare le credenziali OAuth. Per saperne di più, consulta Autenticazione e credenziali.

from openai import OpenAI
client = OpenAI()



response = client.chat.completions.create(
  model="MODEL",
  messages=[
    {"role": "user", "content": "CONTENT"}
  ],
  tools=[
    {
      "type": "function",
      "function": {
        "name": "FUNCTION_NAME",
        "description": "FUNCTION_DESCRIPTION",
        "parameters": PARAMETERS_OBJECT,
      }
    }
  ],
  tool_choice="auto",
)
  • MODEL: il nome del modello che vuoi utilizzare, ad esempio xai/grok-4.1-fast-reasoning.
  • CONTENT: il prompt dell'utente da inviare al modello.
  • FUNCTION_NAME: il nome della funzione da chiamare.
  • FUNCTION_DESCRIPTION: una descrizione della funzione.
  • PARAMETERS_OBJECT: un dizionario che definisce i parametri della funzione, ad esempio:
    {"type": "object", "properties": {"location": {"type": "string", "description": "The city and state"}}, "required": ["location"]}

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud.
  • LOCATION: una regione che supporta i modelli Grok.
  • MODEL: il nome del modello che vuoi utilizzare, ad esempio xai/grok-4.1-fast-reasoning.
  • CONTENT: il prompt dell'utente da inviare al modello.
  • FUNCTION_NAME: il nome della funzione da chiamare.
  • FUNCTION_DESCRIPTION: una descrizione della funzione.
  • PARAMETERS_OBJECT: un oggetto schema JSON che definisce i parametri della funzione, ad esempio:
    {"type": "object", "properties": {"location": {"type": "string", "description": "The city and state"}}, "required": ["location"]}

Metodo HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions

Corpo JSON della richiesta: 

{
  "model": "MODEL",
  "messages": [
    {
      "role": "user",
      "content": "CONTENT"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "FUNCTION_NAME",
        "description": "FUNCTION_DESCRIPTION",
        "parameters": PARAMETERS_OBJECT
      }
    }
  ],
  "tool_choice": "auto"
}

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions"

PowerShell

Salva il corpo della richiesta in un file denominato request.json, e quindi esegui il comando seguente: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions" | Select-Object -Expand Content

Dovresti ricevere un codice di stato riuscito (2xx) e una risposta vuota.

Esempio

Di seguito è riportato l'output completo che potresti aspettarti dopo aver utilizzato la funzione get_current_weather per recuperare informazioni meteorologiche.

Python

from openai import OpenAI
client = OpenAI()

response = client.chat.completions.create(
  model="xai/grok-4.1-fast-reasoning",
  messages=[
    {
      "role": "user",
      "content": "Which city has a higher temperature, Boston or New Delhi and by how much in F?"
    },
    {
      "role": "assistant",
      "content": "I'll check the current temperatures for Boston and New Delhi in Fahrenheit and compare them. I'll call the weather function for both cities.",
      "tool_calls": [{"function":{"arguments":"{\"location\":\"Boston, MA\",\"unit\":\"fahrenheit\"}","name":"get_current_weather"},"id":"get_current_weather","type":"function"},{"function":{"arguments":"{\"location\":\"New Delhi, India\",\"unit\":\"fahrenheit\"}","name":"get_current_weather"},"id":"get_current_weather","type":"function"}]
    },
    {
      "role": "tool",
      "content": "The temperature in Boston is 75 degrees Fahrenheit.",
      "tool_call_id": "get_current_weather"
    },
    {
      "role": "tool",
      "content": "The temperature in New Delhi is 50 degrees Fahrenheit.",
      "tool_call_id": "get_current_weather"
    }
  ],
  tools=[
    {
      "type": "function",
      "function": {
        "name": "get_current_weather",
        "description": "Get the current weather in a given location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"]
            }
          },
          "required": ["location"]
        }
      }
    }
  ],
  tool_choice="auto"
)

curl

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1/projects/sample-project/locations/us-central1/endpoints/openapi/chat/completions -d \
'{
  "model": "xai/grok-4.1-fast-reasoning",
  "messages": [
    {
      "role": "user",
      "content": "Which city has a higher temperature, Boston or New Delhi and by how much in F?"
    },
    {
      "role": "assistant",
      "content": "I'll check the current temperatures for Boston and New Delhi in Fahrenheit and compare them. I'll call the weather function for both cities.",
      "tool_calls": [{"function":{"arguments":"{\"location\":\"Boston, MA\",\"unit\":\"fahrenheit\"}","name":"get_current_weather"},"id":"get_current_weather","type":"function"},{"function":{"arguments":"{\"location\":\"New Delhi, India\",\"unit\":\"fahrenheit\"}","name":"get_current_weather"},"id":"get_current_weather","type":"function"}]
    },
    {
      "role": "tool",
      "content": "The temperature in Boston is 75 degrees Fahrenheit.",
      "tool_call_id": "get_current_weather"
    },
    {
      "role": "tool",
      "content": "The temperature in New Delhi is 50 degrees Fahrenheit.",
      "tool_call_id": "get_current_weather"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_current_weather",
        "description": "Get the current weather in a given location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"]
            }
          },
          "required": ["location"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}'
Dopo aver ricevuto le informazioni recuperate tramite la chiamata alla funzione esterna `get_current_weather`, il modello può sintetizzare le informazioni dalle due risposte `tool` e rispondere alla domanda dell'utente. Di seguito è riportato un esempio di come potrebbe apparire l'output del modello: 
{
 "choices": [
  {
   "finish_reason": "stop",
   "index": 0,
   "logprobs": null,
   "message": {
    "content": "Based on the current weather data:\n\n- **Boston, MA**: 75°F
    \n- **New Delhi, India**: 50°F  \n\n**Comparison**:
    \nBoston is **25°F warmer** than New Delhi.  \n\n**Answer**:
    \nBoston has a higher temperature than New Delhi by 25 degrees Fahrenheit.",
    "role": "assistant"
   }
  }
 ],
 "created": 1750450289,
 "id": "2025-06-20|13:11:29.240295-07|6.230.75.101|-987540014",
 "model": "xai/grok-4.1-fast-reasoning",
 "object": "chat.completion",
 "system_fingerprint": "",
 "usage": {
  "completion_tokens": 66,
  "prompt_tokens": 217,
  "total_tokens": 283
 }
}

Passaggi successivi