Gemini מאפשר לשלב כלים מובנים, כמו google_search, וקריאות לפונקציות (שנקראות גם כלים מותאמים אישית) באינטראקציה אחת, על ידי שמירה של היסטוריית ההקשר של הקריאות לכלים וחשיפה שלה. שילובים מובנים ומותאמים אישית של כלים מאפשרים תהליכי עבודה מורכבים ודינמיים. לדוגמה, המודל יכול להסתמך על נתונים מהאינטרנט בזמן אמת לפני שהוא מפעיל את הלוגיקה העסקית הספציפית שלכם.
דוגמה שבה מופעלים שילובים מובנים ומותאמים אישית של כלים באמצעות google_search ופונקציה מותאמת אישית getWeather:
Python
# This will only work for SDK newer than 2.0.0
from google import genai
client = genai.Client()
getWeather = {
"type": "function",
"name": "getWeather",
"description": "Gets the weather for a requested city.",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "The city and state, e.g. Utqiaġvik, Alaska",
},
},
"required": ["city"],
},
}
# The Interactions API manages context automatically across tool calls.
# The model will first use Google Search, then call getWeather.
interaction = client.interactions.create(
model="gemini-3.5-flash",
input="What is the northernmost city in the United States? What's the weather like there today?",
tools=[
{"type": "google_search"},
getWeather,
],
)
# Process steps: the interaction contains search results and a function call
for step in interaction.steps:
if step.type == "function_call":
print(f"Function call: {step.name} with args: {step.arguments}")
# In a real application, you would execute the function here
# and provide the result back to the model.
JavaScript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const getWeather = {
type: "function",
name: "getWeather",
description: "Get the weather in a given location",
parameters: {
type: "object",
properties: {
location: {
type: "string",
description: "The city and state, e.g. San Francisco, CA"
}
},
required: ["location"]
}
};
// The Interactions API manages context automatically across tool calls.
// The model will first use Google Search, then call getWeather.
const interaction = await client.interactions.create({
model: "gemini-3.5-flash",
input: "What is the northernmost city in the United States? What's the weather like there today?",
tools: [
{ type: "google_search" },
getWeather,
],
});
// Process steps: the interaction contains search results and a function call
for (const step of interaction.steps) {
if (step.type === "function_call") {
console.log(`Function call: ${step.name} with args: ${JSON.stringify(step.arguments)}`);
// In a real application, you would execute the function here
// and provide the result back to the model.
}
}
REST
# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"model": "gemini-3.5-flash",
"input": "What is the northernmost city in the United States? What'\''s the weather like there today?",
"tools": [
{ "type": "google_search" },
{
"type": "function",
"name": "getWeather",
"description": "Get the weather in a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
}
},
"required": ["location"]
}
}
]
}'
איך זה עובד
מודלים של Gemini 3 משתמשים בהעברת הקשר של כלי כדי לאפשר שילובים מובנים ומותאמים אישית של כלים. הפצת הקשר של כלי מאפשרת לשמור את ההקשר של כלים מובנים ולחשוף אותו, ולשתף אותו עם כלים בהתאמה אישית באותו אינטראקציה.
הפעלת שילוב של כלים
- כדי להפעיל את ההתנהגות המשולבת, צריך לכלול את
function_declarations, יחד עם הכלים המובנים שרוצים להשתמש בהם.
שלבים שמוחזרים על ידי ה-API
בתגובה לאינטראקציה, ה-API מחזיר שלבים נפרדים לקריאות של כלים מובנים ולקריאות של פונקציות (כלים בהתאמה אישית):
- שלבים מובנים של כלי: ה-API מנהל את השלבים האלה באופן אוטומטי, ושומר על ההקשר בין התורות.
- שלבים להפעלת פונקציות: ה-API מחזיר
function_callשלבים לפונקציות המותאמות אישית. מריצים את הפונקציה ומחזירים את התוצאה.
שדות קריטיים בשלבים שמוחזרים
יש שדות מסוימים בשלבים שמוחזרים שחשובים לשמירה על ההקשר של הכלי ולאפשר שילוב של כלים:
-
id: נמצא בשלביםfunction_callו-function_response. מזהה ייחודי שממפה קריאה לתגובה שלה. -
signature: מופיע בשלביםthought, וגם בכל השלבים של קריאה לכלי (למשל,function_call) ותוצאה (למשל,function_response) עבור מודלים של Gemini 3 ואילך. ההקשר המוצפן הזה מאפשר העברה של הקשר הכלי בין אינטראקציות.
ניהול השדות האלה:
- מצב Stateful (מומלץ): כשמשתמשים ב-
previous_interaction_id, השרת מטפל אוטומטית בשדותidו-signature. - מצב חסר מצב: כשמנהלים את היסטוריית השיחות באופן ידני, צריך לוודא שמעבירים את השדות
idו-signatureבחזרה למודל בבקשות הבאות כדי לאמת את האותנטיות ולשמור על ההקשר. ערכות ה-SDK הרשמיות מטפלות בזה באופן אוטומטי אם מעבירים את אובייקט התשובה המלא בחזרה להיסטוריה.
נתונים ספציפיים לכלי
חלק מהכלים המובנים מחזירים ארגומנטים של נתונים שגלויים למשתמשים, שספציפיים לסוג הכלי.
| כלי | User visible tool call args (if any) | תגובה של הכלי שגלויה למשתמש (אם יש) |
|---|---|---|
| google_search | queries |
search_suggestions |
| google_maps | queries |
placesgoogle_maps_widget_context_token |
| url_context | urlsכתובות URL לבדיקה |
status: סטטוס הגלישהretrieved_url: כתובות URL שנסרקו |
| file_search | ללא | ללא |
אסימונים ותמחור
שימו לב: חלקי בקשות של קריאות לכלים מובנים נספרים במסגרת prompt_token_count. השלבים האלה של כלי הביניים גלויים לכם עכשיו ומוחזרים לכם, ולכן הם חלק מהיסטוריית השיחה. זה קורה רק בבקשות, ולא בתגובות.
הכלי של חיפוש Google הוא חריג לכלל הזה. חיפוש Google כבר מחיל מודל תמחור משלו ברמת השאילתה, כך שלא מתבצע חיוב כפול על טוקנים (ראו את הדף תמחור).
מידע נוסף זמין בדף אסימונים.
מגבלות
- ברירת המחדל היא מצב
validated(מצבautoלא נתמך) כשמופעלת העברת הקשר של כלי. - כלים מובנים כמו
google_searchמסתמכים על מידע לגבי המיקום והשעה הנוכחית, ולכן אם יש סתירה במידע לגבי המיקום והשעה ב-system_instructionאו ב-function_declaration.description, יכול להיות שהתכונה של שילוב כלים לא תפעל בצורה טובה.
כלים נתמכים
ההפצה הרגילה של הקשר של הכלי חלה על כלים בצד השרת (כלים מובנים). הכלי Code Execution (הרצת קוד) הוא גם כלי בצד השרת, אבל יש לו פתרון מובנה משלו להעברת הקשר. השימוש במחשב והפעלת פונקציות הם כלים בצד הלקוח, ויש להם גם פתרונות מובנים להעברת הקשר.
| כלי | צד הביצוע | תמיכה בהעברת הקשר |
|---|---|---|
| חיפוש Google | בצד השרת | כן |
| מפות Google | בצד השרת | כן |
| הקשר של כתובת ה-URL | בצד השרת | כן |
| חיפוש קבצים | בצד השרת | כן |
| Code Execution | בצד השרת | נתמך (מוטמע, משתמש בשלבים code_execution ו-code_execution_result) |
| שימוש במחשב | בצד הלקוח | נתמך (מוטמע, משתמש בשלבים function_call ו-function_response) |
| פונקציות מותאמות אישית | בצד הלקוח | נתמך (מוטמע, משתמש בשלבים function_call ו-function_response) |
המאמרים הבאים
- מידע נוסף על בקשות להפעלת פונקציות ב-Gemini API
- אפשר לעיין ברשימת הכלים הנתמכים: