Com a chamada de função, é possível definir funções personalizadas e oferecer aos LLMs a capacidade de chamá-las para recuperar informações em tempo real ou interagir com sistemas externos, como bancos de dados SQL ou ferramentas de atendimento ao cliente.
Para mais informações conceituais sobre chamadas de funções, consulte Introdução à chamada de função.
Usar a chamada de função
Os exemplos a seguir mostram como usar a chamada de função.
Python
Antes de testar esse exemplo, siga as instruções de configuração para Python no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Python.
Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Antes de executar esta amostra, defina a variável de ambiente OPENAI_BASE_URL.
Para mais informações, consulte Autenticação e credenciais.
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: o nome do modelo que você quer usar, por exemplo,
qwen/qwen3-next-80b-a3b-instruct-maas. - CONTENT: o comando do usuário a ser enviado para o modelo.
- FUNCTION_NAME: o nome da função a ser chamada.
- FUNCTION_DESCRIPTION: uma descrição da função.
- PARAMETERS_OBJECT: um dicionário que define os parâmetros da função, por exemplo:
{"type": "object", "properties": {"location": {"type": "string", "description": "The city and state"}}, "required": ["location"]}
REST
Depois de configurou seu ambiente use REST para testar uma solicitação de texto. O exemplo a seguir envia uma solicitação ao publisher endpoint do modelo.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- PROJECT_ID pelo ID do projeto no Google Cloud.
- LOCATION: uma região compatível com modelos abertos.
- MODEL: o nome do modelo que você quer usar, por exemplo,
qwen/qwen3-next-80b-a3b-instruct-maas. - CONTENT: o comando do usuário a ser enviado para o modelo.
- FUNCTION_NAME: o nome da função a ser chamada.
- FUNCTION_DESCRIPTION: uma descrição da função.
- PARAMETERS_OBJECT: um objeto de esquema JSON que define os parâmetros da função. Por exemplo:
{"type": "object", "properties": {"location": {"type": "string", "description": "The city and state"}}, "required": ["location"]}
Método HTTP e URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions
Corpo JSON da solicitação:
{
"model": "MODEL",
"messages": [
{
"role": "user",
"content": "CONTENT"
}
],
"tools": [
{
"type": "function",
"function": {
"name": "FUNCTION_NAME",
"description": "FUNCTION_DESCRIPTION",
"parameters": PARAMETERS_OBJECT
}
}
],
"tool_choice": "auto"
}
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:
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
Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:
$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
Você receberá um código de status bem-sucedido (2xx) e uma resposta vazia.
Exemplo
Confira abaixo a saída completa que você pode esperar depois de usar a
função get_current_weather para buscar informações meteorológicas.
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 } }
Orientações específicas para o modelo
As seções a seguir oferecem orientações específicas do modelo para a chamada de função.
DeepSeek
Os modelos DeepSeek não têm um bom desempenho na chamada de função se você usa um comando do sistema. Para ter um desempenho ideal, omita o comando do sistema ao usar a chamada de função com modelos do DeepSeek.
Llama
meta/llama3-405b-instruct-maas não é compatível com tool_choice = 'required'.
OpenAI
Ao usar openai/gpt-oss-120b-instruct-maas e
openai/gpt-oss-20b-instruct-maas, coloque as definições de ferramentas no
comando do sistema para um desempenho ideal. Exemplo:
{"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?"}, ... ]}
Esses modelos não são compatíveis com tool_choice = 'required' ou chamadas de função nomeadas.
Qwen
Os modelos Qwen têm melhor desempenho quando tool_choice é definido explicitamente como auto ou none. Se tool_choice não estiver definido, o modelo poderá não funcionar tão bem.
A seguir
- Saiba mais sobre a saída estruturada.
- Saiba mais sobre Pensamento.
- Saiba mais sobre previsões em lote.