La chiamata di funzioni ti consente di definire funzioni personalizzate e 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 funzioni, consulta Introduzione alla chiamata di funzioni.
Utilizzare la chiamata di funzioni
Gli esempi seguenti mostrano come utilizzare la chiamata di funzioni.
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 saperne di più, consulta la documentazione di riferimento dell'Python API di Agent Platform.
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.
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
qwen/qwen3-next-80b-a3b-instruct-maas. - 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
Dopo aver configurato l'ambiente, puoi utilizzare REST per testare un prompt di testo. L'esempio seguente invia una richiesta all'endpoint del modello del publisher.
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 open.
- MODEL: il nome del modello che vuoi utilizzare,
ad esempio
qwen/qwen3-next-80b-a3b-instruct-maas. - 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="qwen/qwen3-next-80b-a3b-instruct-maas", 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": "qwen/qwen3-next-80b-a3b-instruct-maas", "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" }'
{ "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": "qwen/qwen3-next-80b-a3b-instruct-maas", "object": "chat.completion", "system_fingerprint": "", "usage": { "completion_tokens": 66, "prompt_tokens": 217, "total_tokens": 283 } }
Indicazioni specifiche per il modello
Le sezioni seguenti forniscono indicazioni specifiche per il modello per la chiamata di funzioni.
DeepSeek
I modelli DeepSeek non funzionano altrettanto bene per la chiamata di funzioni se utilizzi un prompt di sistema. Per prestazioni ottimali, ometti il prompt di sistema quando utilizzi la chiamata di funzioni con i modelli DeepSeek.
Llama
meta/llama3-405b-instruct-maas non supporta tool_choice = 'required'.
OpenAI
Quando utilizzi openai/gpt-oss-120b-instruct-maas e openai/gpt-oss-20b-instruct-maas, inserisci le definizioni degli strumenti nel prompt di sistema per prestazioni ottimali. Ad esempio:
{"messages": [ {"role": "system", "content": "You are a helpful assistant with access to the following functions. Use them if required:\n..."}, {"role": "user", "content": "What's the weather like in Boston?"}, ... ]}
Questi modelli non supportano tool_choice = 'required' o la chiamata di strumenti denominati.
Qwen
I modelli Qwen funzionano al meglio quando tool_choice è impostato esplicitamente su auto o none. Se tool_choice non è impostato, il modello potrebbe non funzionare altrettanto bene.
Passaggi successivi
- Scopri di più sull'output strutturato.
- Scopri di più sul pensiero.
- Scopri di più sulle previsioni batch.