Introdução à chamada de função com a API Gemini

Usando o recurso de chamada de função da API Gemini, é possível fornecer definições de função personalizadas ao modelo. O modelo não invoca diretamente essas funções, mas gera uma saída estruturada que especifica um nome de função e argumentos sugeridos. Em seguida, use o nome da função e os argumentos para chamar uma API externa e incorporar a saída da API resultante em outra consulta ao modelo, permitindo que ele forneça uma resposta mais abrangente e realize outras ações.

A chamada de função permite que os usuários interajam com informações e serviços em tempo real, como bancos de dados, sistemas de gestão de relacionamento com o cliente e repositórios de documentos. O recurso também melhora a capacidade do modelo de fornecer respostas relevantes e contextuais. A chamada de função é a melhor opção para interagir com sistemas externos. Se o caso de uso exigir que o modelo realize a computação, mas não envolva sistemas ou APIs externos, use a execução de código.

Para conferir um exemplo de chamada de função, consulte o notebook"light bot".

Como a chamada de funções funciona

Para usar o recurso de chamada de função, adicione dados de consulta estruturados que descrevem interfaces de programação, chamados de declarações de função, a um comando do modelo. As declarações de função fornecem o nome da função da API, explicam a finalidade dela, os parâmetros compatíveis e as descrições desses parâmetros. Depois de transmitir uma lista de declarações de função em uma consulta para o modelo, ele analisa as declarações de função e o restante da consulta para determinar como usar a API declarada em resposta à solicitação.

O modelo retorna um objeto em um esquema compatível com a OpenAPI especificando como chamar uma ou mais das funções declaradas para responder à pergunta do usuário. Em seguida, você pode usar os parâmetros de chamada de função recomendados, chamar a API real, receber uma resposta e fornecer essa resposta ao usuário ou realizar outras ações. O modelo não chama as funções declaradas. Em vez disso, use os parâmetros do objeto de esquema retornado para chamar a função. A API Gemini também oferece suporte a chamadas de função paralelas, em que o modelo recomenda várias chamadas de função da API com base em uma única solicitação.

Declarações de função

Ao implementar a chamada de função em um comando, você cria um objeto tools, que contém um ou mais function declarations. Você define funções usando JSON, especificamente com um subconjunto selecionado do formato esquema da OpenAPI. Uma única declaração de função pode incluir os seguintes parâmetros:

  • name (string): o identificador exclusivo da função na chamada de API.
  • description (string): uma explicação abrangente do propósito e dos recursos da função.
  • parameters (objeto): define os dados de entrada necessários para a função.
    • type (string): especifica o tipo de dados geral, como object.
    • properties (objeto): lista parâmetros individuais, cada um com:
      • type (string): o tipo de dados do parâmetro, como string, integer, boolean.
      • description (string): uma explicação clara do objetivo e do formato esperado do parâmetro.
    • required (matriz): uma matriz de strings que lista os nomes dos parâmetros obrigatórios para que a função funcione.

Para exemplos de código de uma declaração de função usando comandos cURL, consulte os Exemplos de chamada de função. Para exemplos de como criar declarações de função usando os SDKs da API Gemini, consulte o tutorial de chamadas de função.

Práticas recomendadas para declarações de função

Definir as funções com precisão é essencial para integrá-las às suas solicitações. Cada função depende de parâmetros específicos que orientam o comportamento e a interação com o modelo. A lista a seguir fornece orientações sobre como definir os parâmetros de uma função individual em uma matriz functions_declarations.

  • name: use nomes claros e descritivos sem espaços, pontos (.) ou caracteres de traço (-). Em vez disso, use caracteres de sublinhado (_) ou caixa alta e baixa.

  • description: forneça descrições detalhadas, claras e específicas das funções, incluindo exemplos, se necessário. Por exemplo, em vez de find theaters, use find theaters based on location and optionally movie title that is currently playing in theaters. Evite descrições muito amplas ou ambíguas.

  • properties > type: use parâmetros fortemente tipados para reduzir as alucinações do modelo. Por exemplo, se os valores de parâmetro forem de um conjunto limitado, use um campo enum em vez de listar os valores na descrição (por exemplo, "type": "enum", "values": ["now_playing", "upcoming"]). Se o valor do parâmetro for sempre um número inteiro, defina o tipo como integer em vez de integer.number

  • properties > description: forneça exemplos e restrições concretos. Por exemplo, em vez de the location to search, use The city and state, e.g. San Francisco, CA or a zip code e.g. 95616.

Para conferir mais práticas recomendadas ao usar a chamada de função, consulte a seção Práticas recomendadas.

Modo da chamada de função

É possível usar a função que chama o parâmetro mode para modificar o comportamento de execução do recurso. Há três modos disponíveis:

  • AUTO: o comportamento padrão do modelo. O modelo decide se quer prever uma chamada de função ou uma resposta de linguagem natural.
  • ANY: o modelo é restrito a sempre prever uma chamada de função. Se allowed_function_names não for fornecido, o modelo vai escolher entre todas as declarações de função disponíveis. Se allowed_function_names for fornecido, o modelo vai escolher entre o conjunto de funções permitidas.
  • NONE: o modelo não vai prever uma chamada de função. Nesse caso, o comportamento do modelo é o mesmo que se você não transmitisse nenhuma declaração de função.

O uso do modo ANY ("chamada de função forçada") é compatível apenas com os modelos Gemini 1.5 Pro e Gemini 1.5 Flash.

Também é possível transmitir um conjunto de allowed_function_names que, quando fornecido, limita as funções que o modelo vai chamar. Só inclua allowed_function_names quando o modo for ANY. Os nomes das funções precisam corresponder aos nomes de declaração de função. Com o modo definido como ANY e o allowed_function_names definido, o modelo vai prever uma chamada de função do conjunto de nomes de função fornecido.

O snippet de código abaixo de um pedido de exemplo mostra como definir o mode como ANY e especificar uma lista de funções permitidas:

"tool_config": {
  "function_calling_config": {
    "mode": "ANY",
    "allowed_function_names": ["find_theaters", "get_showtimes"]
  },
}

Exemplos de chamada de função

Esta seção apresenta exemplos de comandos cURL para chamada de função. Os exemplos incluem cenários de um e vários turnos e a ativação de diferentes modos de chamada de função.

Ao usar comandos cURL com esse recurso, as informações de função e parâmetro são incluídas no elemento tools. Cada declaração de função no elemento tools contém o nome da função, e você especifica os parâmetros usando um esquema compatível com a OpenAPI e uma descrição da função.

Exemplo de curva única

Interação única é quando você chama o modelo de idioma uma vez. Com a chamada de função, um caso de uso de uma única resposta pode ser ao fornecer ao modelo uma consulta em linguagem natural e uma lista de funções. Nesse caso, o modelo usa a declaração da função, que inclui o nome, os parâmetros e a descrição da função, para prever qual função será chamada e os argumentos com os quais será feita a chamada.

O exemplo de curl a seguir é um exemplo de transmissão da descrição de uma função que retorna informações sobre onde um filme está sendo reproduzido. Várias declarações de função estão incluídas na solicitação, como find_movies e find_theaters.

Solicitação de exemplo de chamada de função de uma só atividade

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "Which theaters in Mountain View show Barbie movie?"
    }
  },
  "tools": [
    {
      "function_declarations": [
        {
          "name": "find_movies",
          "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "description": {
                "type": "string",
                "description": "Any kind of description including category or genre, title words, attributes, etc."
              }
            },
            "required": [
              "description"
            ]
          }
        },
        {
          "name": "find_theaters",
          "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              }
            },
            "required": [
              "location"
            ]
          }
        },
        {
          "name": "get_showtimes",
          "description": "Find the start times for movies playing in a specific theater",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              },
              "theater": {
                "type": "string",
                "description": "Name of the theater"
              },
              "date": {
                "type": "string",
                "description": "Date for requested showtime"
              }
            },
            "required": [
              "location",
              "movie",
              "theater",
              "date"
            ]
          }
        }
      ]
    }
  ]
}'

A resposta a esse exemplo de curl pode ser semelhante a esta.

Função de uma só atividade que chama a resposta de exemplo de curl

[{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_theaters",
              "args": {
                "movie": "Barbie",
                "location": "Mountain View, CA"
              }
            }
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "totalTokenCount": 9
  }
}]

Exemplo de curva única usando o modo ANY

O exemplo de curl a seguir é semelhante ao exemplo de uma única volta, mas define o modo como ANY:

"tool_config": {
  "function_calling_config": {
    "mode": "ANY"
  },
}

Chamada de função de uma única atividade usando o modo ANY (solicitação)

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "What movies are showing in North Seattle tonight?"
    }
  },
  "tools": [
    {
      "function_declarations": [
        {
          "name": "find_movies",
          "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "description": {
                "type": "string",
                "description": "Any kind of description including category or genre, title words, attributes, etc."
              }
            },
            "required": [
              "description"
            ]
          }
        },
        {
          "name": "find_theaters",
          "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              }
            },
            "required": [
              "location"
            ]
          }
        },
        {
          "name": "get_showtimes",
          "description": "Find the start times for movies playing in a specific theater",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              },
              "theater": {
                "type": "string",
                "description": "Name of the theater"
              },
              "date": {
                "type": "string",
                "description": "Date for requested showtime"
              }
            },
            "required": [
              "location",
              "movie",
              "theater",
              "date"
            ]
          }
        }
      ]
    }
  ],
  "tool_config": {
    "function_calling_config": {
      "mode": "ANY"
    },
  }
}'

O resultado será mais ou menos assim:

Chamada de função de uma única volta usando o modo ANY (resposta)

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_movies",
              "args": {
                "description": "",
                "location": "North Seattle, WA"
              }
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HARASSMENT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
        "probability": "NEGLIGIBLE"
      }
    ]
  }
}

Exemplo de uma única atividade usando o modo ANY e as funções permitidas

O exemplo de curl a seguir é semelhante ao exemplo de uma única volta, mas define o modo como ANY e inclui uma lista de funções permitidas:

"tool_config": {
  "function_calling_config": {
    "mode": "ANY",
    "allowed_function_names": ["find_theaters", "get_showtimes"]
  },
}

Chamada de função de uma única atividade usando o modo ANY e as funções permitidas (solicitação)

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "What movies are showing in North Seattle tonight?"
    }
  },
  "tools": [
    {
      "function_declarations": [
        {
          "name": "find_movies",
          "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "description": {
                "type": "string",
                "description": "Any kind of description including category or genre, title words, attributes, etc."
              }
            },
            "required": [
              "description"
            ]
          }
        },
        {
          "name": "find_theaters",
          "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              }
            },
            "required": [
              "location"
            ]
          }
        },
        {
          "name": "get_showtimes",
          "description": "Find the start times for movies playing in a specific theater",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              },
              "theater": {
                "type": "string",
                "description": "Name of the theater"
              },
              "date": {
                "type": "string",
                "description": "Date for requested showtime"
              }
            },
            "required": [
              "location",
              "movie",
              "theater",
              "date"
            ]
          }
        }
      ]
    }
  ],
  "tool_config": {
    "function_calling_config": {
      "mode": "ANY",
      "allowed_function_names": ["find_theaters", "get_showtimes"]
    },
  }
}'

O modelo não pode prever a função find_movies porque ela não está na lista de funções permitidas. Por isso, ele prevê uma função diferente. A resposta pode ser semelhante a esta:

Chamada de função de uma única etapa usando QUALQUER modo e funções permitidas (resposta)

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_theaters",
              "args": {
                "location": "North Seattle, WA",
                "movie": null
              }
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HARASSMENT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
        "probability": "NEGLIGIBLE"
      }
    ]
  }
}

Exemplos de várias interações

Você pode implementar um cenário de chamada de função com vários turnos fazendo o seguinte:

  1. Receba uma resposta de chamada de função chamando o modelo de linguagem. Esta é a primeira rodada.
  2. Chame o modelo de linguagem usando a resposta da chamada de função da primeira curva e a resposta da função recebida ao chamar essa função. Esta é a segunda curva.

A resposta da segunda curva resume os resultados para responder à consulta na primeira curva ou contém uma segunda chamada de função que pode ser usada para receber mais informações sobre a consulta.

Este tópico inclui dois exemplos de curl de várias interações:

Usar uma resposta de uma rodada anterior

A amostra de curl a seguir chama a função e os argumentos retornados pelo exemplo de turno único anterior para receber uma resposta. O método e os parâmetros retornados pelo exemplo de conversão única estão nesse JSON.

"functionCall": {
  "name": "find_theaters",
  "args": {
    "movie": "Barbie",
    "location": "Mountain View, CA"
  }
}

Função de várias interações que chama a solicitação de exemplo curl

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Which theaters in Mountain View show Barbie movie?"
    }]
  }, {
    "role": "model",
    "parts": [{
      "functionCall": {
        "name": "find_theaters",
        "args": {
          "location": "Mountain View, CA",
          "movie": "Barbie"
        }
      }
    }]
  }, {
    "role": "user",
    "parts": [{
      "functionResponse": {
        "name": "find_theaters",
        "response": {
          "name": "find_theaters",
          "content": {
            "movie": "Barbie",
            "theaters": [{
              "name": "AMC Mountain View 16",
              "address": "2000 W El Camino Real, Mountain View, CA 94040"
            }, {
              "name": "Regal Edwards 14",
              "address": "245 Castro St, Mountain View, CA 94040"
            }]
          }
        }
      }
    }]
  }],
  "tools": [{
    "functionDeclarations": [{
      "name": "find_movies",
      "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "description": {
            "type": "STRING",
            "description": "Any kind of description including category or genre, title words, attributes, etc."
          }
        },
        "required": ["description"]
      }
    }, {
      "name": "find_theaters",
      "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          }
        },
        "required": ["location"]
      }
    }, {
      "name": "get_showtimes",
      "description": "Find the start times for movies playing in a specific theater",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          },
          "theater": {
            "type": "STRING",
            "description": "Name of the theater"
          },
          "date": {
            "type": "STRING",
            "description": "Date for requested showtime"
          }
        },
        "required": ["location", "movie", "theater", "date"]
      }
    }]
  }]
}'

A resposta a este exemplo de curl inclui o resultado da chamada do método find_theaters. O resultado será mais ou menos assim:

Função de várias interações que chama a resposta de exemplo de curl

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": " OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14."
          }
        ]
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 27,
    "totalTokenCount": 36
  }
}

Chamar o modelo várias vezes

O exemplo de cURL a seguir chama o modelo de IA generativa várias vezes para chamar uma função. Cada vez que o modelo chama a função, ele pode usar uma função diferente para responder a uma consulta do usuário diferente na solicitação.

Função de várias interações que chama a solicitação de exemplo curl

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Which theaters in Mountain View show Barbie movie?"
    }]
  }, {
    "role": "model",
    "parts": [{
      "functionCall": {
        "name": "find_theaters",
        "args": {
          "location": "Mountain View, CA",
          "movie": "Barbie"
        }
      }
    }]
  }, {
    "role": "user",
    "parts": [{
      "functionResponse": {
        "name": "find_theaters",
        "response": {
          "name": "find_theaters",
          "content": {
            "movie": "Barbie",
            "theaters": [{
              "name": "AMC Mountain View 16",
              "address": "2000 W El Camino Real, Mountain View, CA 94040"
            }, {
              "name": "Regal Edwards 14",
              "address": "245 Castro St, Mountain View, CA 94040"
            }]
          }
        }
      }
    }]
  },
  {
    "role": "model",
    "parts": [{
      "text": " OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14."
    }]
  },{
    "role": "user",
    "parts": [{
      "text": "Can we recommend some comedy movies on show in Mountain View?"
    }]
  }],
  "tools": [{
    "functionDeclarations": [{
      "name": "find_movies",
      "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "description": {
            "type": "STRING",
            "description": "Any kind of description including category or genre, title words, attributes, etc."
          }
        },
        "required": ["description"]
      }
    }, {
      "name": "find_theaters",
      "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          }
        },
        "required": ["location"]
      }
    }, {
      "name": "get_showtimes",
      "description": "Find the start times for movies playing in a specific theater",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          },
          "theater": {
            "type": "STRING",
            "description": "Name of the theater"
          },
          "date": {
            "type": "STRING",
            "description": "Date for requested showtime"
          }
        },
        "required": ["location", "movie", "theater", "date"]
      }
    }]
  }]
}'

Função de várias interações que chama a resposta de exemplo de curl

[{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_movies",
              "args": {
                "description": "comedy",
                "location": "Mountain View, CA"
              }
            }
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 48,
    "totalTokenCount": 48
  }
}
]

Práticas recomendadas

Siga estas práticas recomendadas para melhorar a precisão e a confiabilidade das chamadas de função.

Comando do usuário

Para melhores resultados, adicione ao início os seguintes detalhes antes da consulta do usuário:

  • Contexto adicional para o modelo. Por exemplo, You are a movie API assistant to help users find movies and showtimes based on their preferences..
  • Detalhes ou instruções sobre como e quando usar as funções. Por exemplo: Don't make assumptions on showtimes. Always use a future date for showtimes.
  • Instruções para fazer perguntas esclarecedoras se as consultas do usuário forem ambíguas. Exemplo: Ask clarifying questions if not enough information is available to complete the request.

Parâmetros de amostragem

Para o parâmetro de temperatura, use 0 ou outro valor baixo. Isso instrui o modelo a gerar resultados mais confiáveis e reduz alucinações.

Invocação da API

Se o modelo propor a invocação de uma função que envia uma ordem, atualiza um banco de dados ou tem consequências significativas, valide a chamada de função com o usuário antes de executá-la.