O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Chamada de função para modelos do Grok

A chamada de função permite definir funções personalizadas e dar 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ção, consulte Introdução às chamadas de função.

Usar chamadas de função com a API Responses

Observação: no momento, não é possível definir store como true e o parâmetro previous_response_id para chamadas de API com estado para modelos Grok, e store assume false como padrão. O suporte está planejado para uma versão futura. Quando o suporte for adicionado, o comportamento padrão vai mudar para store: true, e previous_response_id será ativado. Se você quiser impedir que suas respostas sejam armazenadas após essa mudança, defina explicitamente store como false (ou False em Python) nas suas solicitações.

Os modelos a seguir mostram como usar a chamada de função com a API Responses:

Python

Antes de testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido da plataforma de agentes: como usar bibliotecas de cliente.

Para autenticar na Plataforma de Agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Antes de executar este exemplo, defina a variável de ambiente OPENAI_BASE_URL ou configure as credenciais do OAuth. Para mais informações, consulte Autenticação e credenciais.

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: o nome do modelo que você quer usar, por exemplo, xai/grok-4.20-reasoning.
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

Antes de usar os dados da solicitação abaixo, faça estas substituições:

PROJECT_ID: o ID do projeto do Google Cloud .
MODEL: o nome do modelo que você quer usar, por exemplo, xai/grok-4.20-reasoning.
INPUT: o comando ou a entrada 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 JSON que define os parâmetros da função.

Método HTTP e URL:

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, escolha uma destas opções:

curl

Observação: o comando a seguir pressupõe que você tenha feito login na gcloud CLI com sua conta de usuário executando gcloud init ou gcloud auth login ou usando o Cloud Shell, que faz login automaticamente na gcloud CLI. Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

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://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses"

PowerShell

Observação: o comando a seguir pressupõe que você fez login na gcloud CLI com sua conta de usuário executando gcloud init ou gcloud auth login. Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

$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

Exemplo

Os exemplos a seguir mostram um exemplo completo de como usar a chamada de função com a API Responses:

Python

Antes de testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido da plataforma de agentes: como usar bibliotecas de cliente.

Para autenticar na Plataforma de Agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Antes de executar este exemplo, defina a variável de ambiente OPENAI_BASE_URL ou configure as credenciais do OAuth. Para mais informações, consulte Autenticação e credenciais.

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: o ID do projeto do Google Cloud .

Exemplo de resposta

Confira um exemplo de como seria a saída do modelo:

{
  "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
}

Usar a chamada de função com a API Chat Completions

Os exemplos a seguir mostram como usar a chamada de função com preenchimentos de chat.

Python

Antes de testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido da plataforma de agentes: como usar bibliotecas de cliente.

Para autenticar na Plataforma de Agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Antes de executar este exemplo, defina a variável de ambiente OPENAI_BASE_URL ou configure as credenciais do OAuth. 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, xai/grok-4.1-fast-reasoning.
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

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 Grok.
MODEL: o nome do modelo que você quer usar, por exemplo, xai/grok-4.1-fast-reasoning.
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 a seguir 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="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"
}'

Depois de receber as informações recuperadas ao chamar a função externa `get_current_weather`, o modelo pode sintetizar as informações das duas respostas de `tool` e responder à pergunta do usuário. Confira um exemplo de como seria a resposta do modelo:

{
 "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
 }
}

A seguir

Saiba mais sobre a saída estruturada.
Aprenda mais sobre o Raciocínio.

Chamada de função para modelos do Grok Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Usar chamadas de função com a API Responses

Python

REST

curl

PowerShell

Exemplo

Python

REST

Exemplo de resposta

Usar a chamada de função com a API Chat Completions

Python

REST

curl

PowerShell

Exemplo

Python

curl

A seguir

Chamada de função para modelos do Grok