การเรียกใช้ฟังก์ชันด้วย Gemini API
การเรียกใช้ฟังก์ชันช่วยให้คุณเชื่อมต่อโมเดลกับเครื่องมือและ API ภายนอกได้ โมเดลจะพิจารณาเวลาที่จะเรียกฟังก์ชันที่เฉพาะเจาะจงและระบุพารามิเตอร์ที่จำเป็นเพื่อดำเนินการในโลกแห่งความเป็นจริงแทนที่จะสร้างคำตอบเป็นข้อความ ซึ่งช่วยให้โมเดลทำหน้าที่เป็นตัวเชื่อมระหว่างภาษาธรรมชาติกับ การดำเนินการและข้อมูลในโลกแห่งความเป็นจริงได้ การเรียกใช้ฟังก์ชันมีกรณีการใช้งานหลัก 3 กรณีดังนี้
- เพิ่มพูนความรู้: เข้าถึงข้อมูลจากแหล่งที่มาภายนอก เช่น ฐานข้อมูล, API และฐานความรู้
- ขยายขีดความสามารถ: ใช้เครื่องมือภายนอกเพื่อทำการคำนวณและ ขยายข้อจำกัดของโมเดล เช่น ใช้เครื่องคิดเลขหรือสร้าง แผนภูมิ
- ดำเนินการ: โต้ตอบกับระบบภายนอกโดยใช้ API เช่น กำหนดเวลานัดหมาย สร้างใบแจ้งหนี้ ส่งอีเมล หรือควบคุม อุปกรณ์สมาร์ทโฮม
Python
# This will only work for SDK newer than 2.0.0
from google import genai
schedule_meeting_function = {
"type": "function",
"name": "schedule_meeting",
"description": "Schedules a meeting with specified attendees at a given time and date.",
"parameters": {
"type": "object",
"properties": {
"attendees": {"type": "array", "items": {"type": "string"}},
"date": {"type": "string", "description": "Date (e.g., '2024-07-29')"},
"time": {"type": "string", "description": "Time (e.g., '15:00')"},
"topic": {"type": "string", "description": "The meeting topic."},
},
"required": ["attendees", "date", "time", "topic"],
},
}
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="Schedule a meeting with Bob and Alice for 03/14/2025 at 10:00 AM about Q3 planning.",
tools=[{"type": "function", **schedule_meeting_function}],
)
for step in interaction.steps:
if step.type == "function_call":
print(f"Function to call: {step.name}")
print(f"Arguments: {step.arguments}")
JavaScript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const scheduleMeetingFunction = {
type: 'function',
name: 'schedule_meeting',
description: 'Schedules a meeting with specified attendees at a given time and date.',
parameters: {
type: 'object',
properties: {
attendees: { type: 'array', items: { type: 'string' } },
date: { type: 'string', description: 'Date (e.g., "2024-07-29")' },
time: { type: 'string', description: 'Time (e.g., "15:00")' },
topic: { type: 'string', description: 'The meeting topic.' },
},
required: ['attendees', 'date', 'time', 'topic'],
},
};
const interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: 'Schedule a meeting with Bob and Alice for 03/27/2025 at 10:00 AM about Q3 planning.',
tools: [scheduleMeetingFunction],
});
for (const step of interaction.steps) {
if (step.type === 'function_call') {
console.log(`Function to call: ${step.name}`);
console.log(`Arguments: ${JSON.stringify(step.arguments)}`);
}
}
REST
# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-H "Api-Revision: 2026-05-20" \
-d '{
"model": "gemini-3-flash-preview",
"input": "Schedule a meeting with Bob and Alice for 03/27/2025 at 10:00 AM about Q3 planning.",
"tools": [{
"type": "function",
"name": "schedule_meeting",
"description": "Schedules a meeting with specified attendees at a given time and date.",
"parameters": {
"type": "object",
"properties": {
"attendees": {"type": "array", "items": {"type": "string"}},
"date": {"type": "string"},
"time": {"type": "string"},
"topic": {"type": "string"}
},
"required": ["attendees", "date", "time", "topic"]
}
}]
}'
วิธีการทำงานของการเรียกใช้ฟังก์ชัน

การเรียกใช้ฟังก์ชันเกี่ยวข้องกับการโต้ตอบที่มีโครงสร้างระหว่างแอปพลิเคชัน โมเดล และฟังก์ชันภายนอก ดังนี้
- กำหนดการประกาศฟังก์ชัน: กำหนดชื่อ พารามิเตอร์ และ วัตถุประสงค์ของฟังก์ชันให้กับโมเดล
- เรียกใช้ LLM ด้วยการประกาศฟังก์ชัน: ส่งพรอมต์ของผู้ใช้พร้อมกับการประกาศฟังก์ชันไปยังโมเดล
- เรียกใช้โค้ดฟังก์ชัน (ความรับผิดชอบของคุณ): โมเดลไม่ เรียกใช้ฟังก์ชันด้วยตัวเอง แยกชื่อและอาร์กิวเมนต์ แล้วเรียกใช้ใน แอปพลิเคชันของคุณ
- สร้างคำตอบที่ใช้งานง่าย: ส่งผลลัพธ์กลับไปยังโมเดลเพื่อรับ คำตอบสุดท้ายที่ใช้งานง่าย
กระบวนการนี้สามารถทำซ้ำได้หลายรอบ โมเดลรองรับการเรียกใช้ฟังก์ชันหลายรายการในเทิร์นเดียว (การเรียกใช้ฟังก์ชันแบบขนาน) และแบบลำดับ (การเรียกใช้ฟังก์ชันแบบประกอบ)
ขั้นตอนที่ 1: กำหนดการประกาศฟังก์ชัน
Python
# This will only work for SDK newer than 2.0.0
set_light_values_declaration = {
"type": "function",
"name": "set_light_values",
"description": "Sets the brightness and color temperature of a light.",
"parameters": {
"type": "object",
"properties": {
"brightness": {
"type": "integer",
"description": "Light level from 0 to 100",
},
"color_temp": {
"type": "string",
"enum": ["daylight", "cool", "warm"],
"description": "Color temperature",
},
},
"required": ["brightness", "color_temp"],
},
}
def set_light_values(brightness: int, color_temp: str) -> dict:
"""Set the brightness and color temperature of a room light."""
return {"brightness": brightness, "colorTemperature": color_temp}
JavaScript
// This will only work for SDK newer than 2.0.0
const setLightValuesTool = {
type: 'function',
name: 'set_light_values',
description: 'Sets the brightness and color temperature of a light.',
parameters: {
type: 'object',
properties: {
brightness: { type: 'number', description: 'Light level from 0 to 100' },
color_temp: { type: 'string', enum: ['daylight', 'cool', 'warm'] },
},
required: ['brightness', 'color_temp'],
},
};
function setLightValues(brightness, color_temp) {
return { brightness: brightness, colorTemperature: color_temp };
}
ขั้นตอนที่ 2: เรียกใช้โมเดลด้วยการประกาศฟังก์ชัน
Python
# This will only work for SDK newer than 2.0.0
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="Turn the lights down to a romantic level",
tools=[set_light_values_declaration],
)
# Find the function call step
fc_step = next(s for s in interaction.steps if s.type == "function_call")
print(fc_step)
JavaScript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: 'Turn the lights down to a romantic level',
tools: [setLightValuesTool],
});
// Find the function call step
const fcStep = interaction.steps.find(s => s.type === 'function_call');
console.log(fcStep);
โมเดลจะแสดงขั้นตอน function_call พร้อมด้วย type, name และ arguments
type='function_call'
name='set_light_values'
arguments={'color_temp': 'warm', 'brightness': 25}
ขั้นตอนที่ 3: เรียกใช้ฟังก์ชัน
Python
# This will only work for SDK newer than 2.0.0
fc_step = next(s for s in interaction.steps if s.type == "function_call")
if fc_step.name == "set_light_values":
result = set_light_values(**fc_step.arguments)
print(f"Function execution result: {result}")
JavaScript
// This will only work for SDK newer than 2.0.0
const fcStep = interaction.steps.find(s => s.type === 'function_call');
let result;
if (fcStep.name === 'set_light_values') {
result = setLightValues(fcStep.arguments.brightness, fcStep.arguments.color_temp);
console.log(`Function execution result: ${JSON.stringify(result)}`);
}
ขั้นตอนที่ 4: ส่งผลลัพธ์กลับไปยังโมเดล
Python
# This will only work for SDK newer than 2.0.0
final_interaction = client.interactions.create(
model="gemini-3-flash-preview",
input=[
{
"type": "function_result",
"name": fc_step.name,
"call_id": fc_step.id,
"result": [{"type": "text", "text": json.dumps(result)}],
}
],
tools=[set_light_values_declaration],
previous_interaction_id=interaction.id,
)
print(final_interaction.steps[-1].content[0].text)
JavaScript
// This will only work for SDK newer than 2.0.0
const finalInteraction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: [{
type: 'function_result',
name: fcStep.name,
call_id: fcStep.id,
result: [{ type: 'text', text: JSON.stringify(result) }]
}],
tools: [setLightValuesTool],
previous_interaction_id: interaction.id,
});
console.log(finalInteraction.steps.at(-1).content[0].text);
การเรียกใช้ฟังก์ชันแบบไม่เก็บสถานะ
นอกจากนี้ คุณยังใช้การเรียกใช้ฟังก์ชันในโหมดแบบไม่เก็บสถานะได้โดยจัดการประวัติการสนทนาฝั่งไคลเอ็นต์และตั้งค่า store=false
ในโหมดแบบไม่เก็บสถานะ คุณต้องส่งประวัติการสนทนาทั้งหมดในฟิลด์ input ของคำขอที่ตามมาแต่ละรายการ ประวัติการเข้าชมต้องมีข้อมูลต่อไปนี้
1. user_inputขั้นตอนแรก
2. ขั้นตอนทั้งหมดที่โมเดลสร้างขึ้นจะแสดงในเทิร์นที่ 1 (รวมถึงขั้นตอน thought และ function_call) ตามที่ได้รับ
3. function_result ขั้นตอนที่มีเอาต์พุตของฟังก์ชันที่เรียกใช้
Python
# This will only work for SDK newer than 2.0.0
from google import genai
import json
client = genai.Client()
# Initialize history with Turn 1 input
history = [
{
"type": "user_input",
"content": [{"type": "text", "text": "Turn the lights down to a romantic level"}]
}
]
# Turn 1: Call model with tools and store=False
interaction = client.interactions.create(
model="gemini-3-flash-preview",
store=False,
input=history,
tools=[set_light_values_declaration],
)
# Append all model-generated steps (including thoughts and function_calls)
for step in interaction.steps:
history.append(step.model_dump())
# Find the function call step to execute it
fc_step = next(s for s in interaction.steps if s.type == "function_call")
if fc_step.name == "set_light_values":
result = set_light_values(**fc_step.arguments)
# Append the function result as a step
history.append({
"type": "function_result",
"name": fc_step.name,
"call_id": fc_step.id,
"result": [{"type": "text", "text": json.dumps(result)}],
})
# Turn 2: Send the full history to get the final response
final_interaction = client.interactions.create(
model="gemini-3-flash-preview",
store=False,
input=history,
tools=[set_light_values_declaration],
)
print(final_interaction.steps[-1].content[0].text)
JavaScript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
async function main() {
// Initialize history with Turn 1 input
const history = [
{
type: "user_input",
content: [{ type: "text", text: "Turn the lights down to a romantic level" }]
}
];
// Turn 1: Call model with tools and store: false
const interaction = await client.interactions.create({
model: "gemini-3-flash-preview",
store: false,
input: history,
tools: [setLightValuesTool],
});
// Append all model-generated steps
history.push(...interaction.steps);
// Find and execute function
const fcStep = interaction.steps.find(s => s.type === 'function_call');
let result;
if (fcStep.name === 'set_light_values') {
result = setLightValues(fcStep.arguments.brightness, fcStep.arguments.color_temp);
}
// Append function result step
history.push({
type: 'function_result',
name: fcStep.name,
call_id: fcStep.id,
result: [{ type: 'text', text: JSON.stringify(result) }]
});
// Turn 2: Send full history
const finalInteraction = await client.interactions.create({
model: 'gemini-3-flash-preview',
store: false,
input: history,
tools: [setLightValuesTool],
});
console.log(finalInteraction.steps.at(-1).content[0].text);
}
await main();
REST
# Turn 1: Send request with tools and store: false
# Specifies the API revision to avoid breaking changes when they become default
RESPONSE1=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-H "Api-Revision: 2026-05-20" \
-d '{
"model": "gemini-3-flash-preview",
"store": false,
"input": [
{
"type": "user_input",
"content": [{"type": "text", "text": "Turn the lights down to a romantic level"}]
}
],
"tools": [{
"type": "function",
"name": "set_light_values",
"description": "Sets the brightness and color temperature of a light.",
"parameters": {
"type": "object",
"properties": {
"brightness": {"type": "integer", "description": "Light level from 0 to 100"},
"color_temp": {"type": "string", "enum": ["daylight", "cool", "warm"]}
},
"required": ["brightness", "color_temp"]
}
}]
}')
# Extract model steps (thought, function_call)
MODEL_STEPS=$(echo "$RESPONSE1" | jq '.steps')
# Extract function call details to execute
FC_NAME=$(echo "$RESPONSE1" | jq -r '.steps[] | select(.type=="function_call") | .name')
FC_ID=$(echo "$RESPONSE1" | jq -r '.steps[] | select(.type=="function_call") | .id')
# Assume local execution returns: {"brightness": 25, "colorTemperature": "warm"}
RESULT="{\"brightness\": 25, \"colorTemperature\": \"warm\"}"
# Reconstruct history for Turn 2
HISTORY=$(jq -n \
--argjson first_input '[{"type": "user_input", "content": [{"type": "text", "text": "Turn the lights down to a romantic level"}]}]' \
--argjson model_steps "$MODEL_STEPS" \
--arg fc_name "$FC_NAME" \
--arg fc_id "$FC_ID" \
--arg result "$RESULT" \
'$first_input + $model_steps + [{"type": "function_result", "name": $fc_name, "call_id": $fc_id, "result": [{"type": "text", "text": $result}]}]')
# Turn 2: Send the full history
# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-H "Api-Revision: 2026-05-20" \
-d "{
\"model\": \"gemini-3-flash-preview\",
\"store\": false,
\"input\": $HISTORY,
\"tools\": [{
\"type\": \"function\",
\"name\": \"set_light_values\",
\"description\": \"Sets the brightness and color temperature of a light.\",
\"parameters\": {
\"type\": \"object\",
\"properties\": {
\"brightness\": {\"type\": \"integer\"},
\"color_temp\": {\"type\": \"string\"}
},
\"required\": [\"brightness\", \"color_temp\"]
}
}]
}"
การประกาศฟังก์ชัน
ระบบจะส่งการประกาศฟังก์ชันเป็นเครื่องมือและมีข้อมูลต่อไปนี้
type(สตริง): ต้องเป็น"function"สำหรับฟังก์ชันที่กำหนดเองname(สตริง): ชื่อฟังก์ชันที่ไม่ซ้ำกัน (ใช้ขีดล่างหรือ CamelCase)description(สตริง): คำอธิบายที่ชัดเจนเกี่ยวกับวัตถุประสงค์ของฟังก์ชันparameters(ออบเจ็กต์): พารามิเตอร์อินพุตที่ฟังก์ชันคาดหวังtype(สตริง): ประเภทข้อมูลโดยรวม เช่นobjectproperties(ออบเจ็กต์): พารามิเตอร์แต่ละรายการที่มีประเภทและคำอธิบายrequired(อาร์เรย์): ชื่อพารามิเตอร์ที่ต้องระบุ
การเรียกใช้ฟังก์ชันด้วยโมเดลการคิด
โมเดล Gemini 3 และ 2.5 ใช้กระบวนการ"การคิด" ภายในที่ช่วยปรับปรุงการเรียกใช้ฟังก์ชัน SDK จะจัดการลายเซ็นความคิดให้คุณโดยอัตโนมัติ
การเรียกใช้ฟังก์ชันแบบคู่ขนาน
เรียกใช้ฟังก์ชันหลายรายการพร้อมกันเมื่อฟังก์ชันเหล่านั้นไม่ขึ้นต่อกัน
Python
# This will only work for SDK newer than 2.0.0
power_disco_ball = {"type": "function", "name": "power_disco_ball", "description": "Powers the disco ball.",
"parameters": {"type": "object", "properties": {"power": {"type": "boolean"}}, "required": ["power"]}}
start_music = {"type": "function", "name": "start_music", "description": "Play music.",
"parameters": {"type": "object", "properties": {"energetic": {"type": "boolean"}, "loud": {"type": "boolean"}}, "required": ["energetic", "loud"]}}
dim_lights = {"type": "function", "name": "dim_lights", "description": "Dim the lights.",
"parameters": {"type": "object", "properties": {"brightness": {"type": "number"}}, "required": ["brightness"]}}
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="Turn this place into a party!",
tools=[power_disco_ball, start_music, dim_lights],
generation_config={"tool_choice": "any"},
)
for step in interaction.steps:
if step.type == "function_call":
args = ", ".join(f"{key}={val}" for key, val in step.arguments.items())
print(f"{step.name}({args})")
JavaScript
// This will only work for SDK newer than 2.0.0
const powerDiscoBall = { type: 'function', name: 'power_disco_ball', description: 'Powers the disco ball.',
parameters: { type: 'object', properties: { power: { type: 'boolean' } }, required: ['power'] } };
const startMusic = { type: 'function', name: 'start_music', description: 'Play music.',
parameters: { type: 'object', properties: { energetic: { type: 'boolean' }, loud: { type: 'boolean' } }, required: ['energetic', 'loud'] } };
const dimLights = { type: 'function', name: 'dim_lights', description: 'Dim the lights.',
parameters: { type: 'object', properties: { brightness: { type: 'number' } }, required: ['brightness'] } };
const interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: 'Turn this place into a party!',
tools: [powerDiscoBall, startMusic, dimLights],
generation_config: { tool_choice: 'any' },
});
for (const step of interaction.steps) {
if (step.type === 'function_call') {
console.log(`${step.name}(${JSON.stringify(step.arguments)})`);
}
}
การเรียกใช้ฟังก์ชันแบบคอมโพสิต
เชื่อมโยงการเรียกใช้ฟังก์ชันหลายรายการเข้าด้วยกันสำหรับคำขอที่ซับซ้อน (เช่น รับตำแหน่ง ก่อน แล้วรับสภาพอากาศสำหรับตำแหน่งนั้น)
Python
# This will only work for SDK newer than 2.0.0
get_weather_forecast_declaration = {
"type": "function",
"name": "get_weather_forecast",
"description": "Gets the current weather temperature for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "The location"},
},
"required": ["location"],
},
}
set_thermostat_temperature_declaration = {
"type": "function",
"name": "set_thermostat_temperature",
"description": "Sets the thermostat to a desired temperature.",
"parameters": {
"type": "object",
"properties": {
"temperature": {
"type": "integer",
"description": "The temperature in Celsius",
},
},
"required": ["temperature"],
},
}
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="If it's warmer than 20°C in London, set the thermostat to 20°C, otherwise 18°C.",
tools=[
get_weather_forecast_declaration,
set_thermostat_temperature_declaration,
],
)
for step in interaction.steps:
if step.type == "function_call":
print(f"Function to call: {step.name}")
print(f"Arguments: {step.arguments}")
elif hasattr(step, "content") and step.content:
for part in step.content:
if hasattr(part, "text"):
print(part.text)
โหมดการเรียกใช้ฟังก์ชัน
ควบคุมวิธีที่โมเดลใช้เครื่องมือโดยใช้ tool_choice ใน generation_config ดังนี้
auto(ค่าเริ่มต้น): โมเดลจะตัดสินใจว่าจะเรียกใช้ฟังก์ชันหรือตอบกลับโดยตรงany: โมเดลถูกจำกัดให้คาดการณ์การเรียกใช้ฟังก์ชันเสมอnone: โมเดลถูกห้ามไม่ให้ทำการเรียกฟังก์ชันvalidated(ตัวอย่าง): โมเดลช่วยให้มั่นใจว่าสคีมาฟังก์ชันเป็นไปตามข้อกำหนด
Python
# This will only work for SDK newer than 2.0.0
generation_config = {
"tool_choice": {
"allowed_tools": {
"mode": "any",
"tools": ["get_current_temperature"]
}
}
}
JavaScript
// This will only work for SDK newer than 2.0.0
const generation_config = {
tool_choice: {
allowed_tools: {
mode: 'any',
tools: ['get_current_temperature']
}
}
};
REST
# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-H "Api-Revision: 2026-05-20" \
-d '{
"model": "gemini-3-flash-preview",
"input": "What is the temperature in Boston?",
"tools": [{
"type": "function",
"name": "get_current_temperature",
"description": "Gets the current temperature for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string"}
},
"required": ["location"]
}
}],
"generation_config": {
"tool_choice": {
"allowed_tools": {
"mode": "any",
"tools": ["get_current_temperature"]
}
}
}
}'
การใช้เครื่องมืออเนกประสงค์
คุณเปิดใช้เครื่องมือหลายอย่างได้โดยการรวมเครื่องมือในตัวเข้ากับการเรียกใช้ฟังก์ชันในคำขอเดียวกัน
โมเดล Gemini 3 สามารถรวมเครื่องมือในตัวเข้ากับการเรียกใช้ฟังก์ชัน
ได้ทันทีในการโต้ตอบ การส่ง previous_interaction_id
จะหมุนเวียนบริบทของเครื่องมือในตัวโดยอัตโนมัติ
Python
# This will only work for SDK newer than 2.0.0
from google import genai
import json
client = genai.Client()
get_weather = {
"type": "function",
"name": "get_weather",
"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"],
},
}
tools = [
{"type": "google_search"}, # Built-in tool
get_weather # Custom tool
]
# Turn 1: Initial request with both tools enabled
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input="What is the northernmost city in the United States? What's the weather like there today?",
tools=tools
)
for step in interaction.steps:
if step.type == "function_call":
print(f"Function call: {step.name} (ID: {step.id})")
# Execute your custom function locally
result = {"response": "Very cold. 22 degrees Fahrenheit."}
# Turn 2: Provide the function result back to the model.
# Passing `previous_interaction_id` automatically circulates the
# built-in Google Search context from Turn 1
interaction_2 = client.interactions.create(
model="gemini-3-flash-preview",
previous_interaction_id=interaction.id,
tools=tools,
input=[{
"type": "function_result",
"name": step.name,
"call_id": step.id,
"result": [{"type": "text", "text": json.dumps(result)}]
}]
)
print(interaction_2.steps[-1].content[0].text)
JavaScript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const weatherTool = {
type: 'function',
name: 'get_weather',
description: 'Gets the weather for a given location.',
parameters: {
type: 'object',
properties: {
location: { type: 'string', description: 'The city and state, e.g. San Francisco, CA' }
},
required: ['location']
}
};
const tools = [
{type: 'google_search'}, // Built-in tool
weatherTool // Custom tool
];
// Turn 1: Initial request with both tools enabled
let interaction = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: "What is the northernmost city in the United States? What's the weather like there today?",
tools: tools
});
for (const step of interaction.steps) {
if (step.type === 'function_call') {
console.log(`Function call: ${step.name} (ID: ${step.id})`);
// Execute your custom function locally
const result = {response: "Very cold. 22 degrees Fahrenheit."};
// Turn 2: Provide the function result back to the model.
const interaction_2 = await client.interactions.create({
model: 'gemini-3-flash-preview',
previous_interaction_id: interaction.id,
tools: tools,
input: [{
type: 'function_result',
name: step.name,
call_id: step.id,
result: [{ type: 'text', text: JSON.stringify(result) }]
}]
});
console.log(interaction_2.steps.at(-1).content[0].text);
}
}
การตอบกลับฟังก์ชันหลายรูปแบบ
สำหรับโมเดลซีรีส์ Gemini 3 คุณสามารถรวมเนื้อหาหลายรูปแบบไว้ในส่วนการตอบกลับฟังก์ชันที่ส่งไปยังโมเดลได้ โมเดลสามารถประมวลผล เนื้อหามัลติโมดอลนี้ในรอบถัดไปเพื่อสร้างคำตอบที่อิงตามข้อมูลมากขึ้น
หากต้องการรวมข้อมูลหลายรูปแบบไว้ในการตอบกลับของฟังก์ชัน ให้รวมข้อมูลดังกล่าวเป็นบล็อกเนื้อหาอย่างน้อย 1 รายการในช่อง result ของขั้นตอน function_result การบล็อกเนื้อหาแต่ละรายการต้องระบุ type (เช่น "text", "image")
ตัวอย่างต่อไปนี้แสดงวิธีส่งการตอบกลับฟังก์ชันที่มีข้อมูลรูปภาพกลับไปยังโมเดลในการโต้ตอบ
Python
# This will only work for SDK newer than 2.0.0
import base64
from google import genai
import requests
client = genai.Client()
# Find the function call step
tool_call = next(s for s in interaction.steps if s.type == "function_call")
# Execute your tool to get image bytes
image_path = "https://goo.gle/instrument-img"
image_bytes = requests.get(image_path).content
base64_image_data = base64.b64encode(image_bytes).decode("utf-8")
final_interaction = client.interactions.create(
model="gemini-3-flash-preview",
previous_interaction_id=interaction.id,
input=[
{
"type": "function_result",
"name": tool_call.name,
"call_id": tool_call.id,
"result": [
{"type": "text", "text": "instrument.jpg"},
{
"type": "image",
"mime_type": "image/jpeg",
"data": base64_image_data,
},
],
}
],
)
print(final_interaction.steps[-1].content[0].text)
JavaScript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
// Find the function call step
const toolCall = interaction.steps.find(s => s.type === 'function_call');
// Execute your tool to get image bytes and convert to base64
// (Implementation depends on your environment)
const base64ImageData = "BASE64_IMAGE_DATA";
const finalInteraction = await ai.interactions.create({
model: 'gemini-3-flash-preview',
previous_interaction_id: interaction.id,
input: [{
type: 'function_result',
name: toolCall.name,
call_id: toolCall.id,
result: [
{ type: 'text', text: 'instrument.jpg' },
{
type: 'image',
mime_type: 'image/jpeg',
data: base64ImageData,
}
]
}]
});
console.log(finalInteraction.steps.at(-1).content[0].text);
REST
# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-H "Api-Revision: 2026-05-20" \
-d '{
"model": "gemini-3-flash-preview",
"previous_interaction_id": "INTERACTION_ID",
"input": [
{
"type": "function_result",
"name": "get_image",
"call_id": "call_123",
"result": [
{"type": "text", "text": "instrument.jpg"},
{
"type": "image",
"mime_type": "image/jpeg",
"data": "BASE64_IMAGE_DATA"
}
]
}
]
}'
การเรียกใช้ฟังก์ชันที่มีเอาต์พุตที่มีโครงสร้าง
สำหรับโมเดลซีรีส์ Gemini 3 ให้รวมการเรียกใช้ฟังก์ชันกับเอาต์พุตที่มีโครงสร้างเพื่อรับคำตอบที่มีรูปแบบสอดคล้องกัน
MCP (Model Context Protocol) ระยะไกล
Interactions API รองรับการเชื่อมต่อกับเซิร์ฟเวอร์ MCP ระยะไกลเพื่อให้โมเดลเข้าถึงเครื่องมือและบริการภายนอกได้ คุณระบุเซิร์ฟเวอร์ name และ url ในการกำหนดค่าเครื่องมือ
เมื่อใช้ MCP ระยะไกล โปรดทราบข้อจำกัดต่อไปนี้
- ประเภทเซิร์ฟเวอร์: MCP ระยะไกลใช้ได้กับเซิร์ฟเวอร์ HTTP ที่สตรีมได้เท่านั้น ระบบไม่รองรับเซิร์ฟเวอร์ SSE (เหตุการณ์ที่เซิร์ฟเวอร์ส่ง)
- การรองรับโมเดล: ขณะนี้ MCP ระยะไกลยังไม่ทำงานกับโมเดล Gemini 3 โดยจะรองรับ Gemini 3 ในเร็วๆ นี้
- การตั้งชื่อ: ชื่อเซิร์ฟเวอร์ MCP ไม่ควรมีอักขระ
-ให้ใช้ชื่อเซิร์ฟเวอร์snake_caseแทน
| ช่อง | ประเภท | ต้องระบุ | คำอธิบาย |
|---|---|---|---|
type |
string |
ใช่ | ต้องเป็น "mcp_server" |
name |
string |
ไม่ | ชื่อที่แสดงสำหรับเซิร์ฟเวอร์ MCP |
url |
string |
ไม่ | URL แบบเต็มสำหรับอุปกรณ์ปลายทางของเซิร์ฟเวอร์ MCP |
headers |
object |
ไม่ | คู่คีย์-ค่าที่ส่งเป็นส่วนหัว HTTP พร้อมกับคำขอทุกรายการไปยังเซิร์ฟเวอร์ (เช่น โทเค็นการตรวจสอบสิทธิ์) |
allowed_tools |
array |
ไม่ | จำกัดเครื่องมือจากเซิร์ฟเวอร์ที่ตัวแทนอาจเรียกใช้ |
ตัวอย่าง
Python
# This will only work for SDK newer than 2.0.0
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-2.5-flash",
input="Check the status of my last server deployment.",
tools=[
{
"type": "mcp_server",
"name": "Deployment Tracker",
"url": "https://mcp.example.com/mcp",
"headers": {"Authorization": "Bearer my-token"},
}
]
)
JavaScript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: 'gemini-2.5-flash',
input: 'Check the status of my last server deployment.',
tools: [
{
type: 'mcp_server',
name: 'Deployment Tracker',
url: 'https://mcp.example.com/mcp',
headers: { Authorization: 'Bearer my-token' }
}
]
});
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" \
-H "Api-Revision: 2026-05-20" \
-d '{
"model": "gemini-2.5-flash",
"input": "Check the status of my last server deployment.",
"tools": [
{
"type": "mcp_server",
"name": "Deployment Tracker",
"url": "https://mcp.example.com/mcp",
"headers": {"Authorization": "Bearer my-token"}
}
]
}'
การเรียกใช้เครื่องมือสตรีม
เมื่อใช้เครื่องมือที่มีการสตรีม โมเดลจะสร้างการเรียกใช้ฟังก์ชันเป็นลำดับของstep.deltaเหตุการณ์ในสตรีม คุณสามารถสตรีมอาร์กิวเมนต์เครื่องมือเป็นอาร์กิวเมนต์บางส่วนได้โดยใช้ arguments คุณต้องรวบรวมเดลต้าเหล่านี้เพื่อสร้างการเรียกใช้เครื่องมือที่สมบูรณ์ใหม่ก่อนที่จะดำเนินการ
Python
# This will only work for SDK newer than 2.0.0
import json
from google import genai
client = genai.Client()
weather_tool = {
"type": "function",
"name": "get_weather",
"description": "Gets the weather for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "The city and state"}
},
"required": ["location"]
}
}
stream = client.interactions.create(
model="gemini-3-flash-preview",
input="What is the weather in Paris?",
tools=[weather_tool],
stream=True
)
current_calls = {}
tool_calls = []
for event in stream:
if event.event_type == "step.start":
if event.step.type == "function_call":
current_calls[event.index] = {
"id": event.step.id,
"name": event.step.name,
"arguments": ""
}
# Handle arguments provided in step.start
if hasattr(event.step, "arguments") and event.step.arguments:
if isinstance(event.step.arguments, dict):
current_calls[event.index]["arguments"] = json.dumps(event.step.arguments)
else:
current_calls[event.index]["arguments"] = event.step.arguments
elif event.event_type == "step.delta":
if event.delta.type == "arguments":
if event.index in current_calls:
current_calls[event.index]["arguments"] += event.delta.partial_arguments
elif event.delta.type == "text":
print(event.delta.text, end="", flush=True)
elif event.event_type == "interaction.completed":
for index, call in current_calls.items():
args = call["arguments"]
if args:
args = json.loads(args)
else:
args = {}
tool_calls.append({
"type": "function_call",
"id": call["id"],
"name": call["name"],
"arguments": args
})
print(f"\nFinal tool calls ready to execute:")
print(json.dumps(tool_calls, indent=2))
JavaScript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({});
const weatherTool = {
type: 'function',
name: 'get_weather',
description: 'Gets the weather for a given location.',
parameters: {
type: 'object',
properties: {
location: { type: 'string', description: 'The city and state' }
},
required: ['location']
}
};
const stream = await client.interactions.create({
model: 'gemini-3-flash-preview',
input: 'What is the weather in Paris?',
tools: [weatherTool],
stream: true,
});
const currentCalls = new Map();
let toolCalls = [];
for await (const event of stream) {
const evType = event.event_type;
if (evType === 'step.start') {
if (event.step.type === 'function_call') {
currentCalls.set(event.index, {
id: event.step.id,
name: event.step.name,
arguments: ''
});
// Handle arguments provided in step.start
if (event.step.arguments) {
if (typeof event.step.arguments === 'object') {
currentCalls.get(event.index).arguments = JSON.stringify(event.step.arguments);
} else {
currentCalls.get(event.index).arguments = event.step.arguments;
}
}
}
} else if (evType === 'step.delta') {
if (event.delta.type === 'arguments') {
if (currentCalls.has(event.index)) {
currentCalls.get(event.index).arguments += event.delta.partial_arguments;
}
} else if (event.delta.type === 'text') {
process.stdout.write(event.delta.text);
}
} else if (evType === 'interaction.completed' || evType === 'interaction.complete') {
toolCalls = Array.from(currentCalls.values()).map(call => ({
type: 'function_call',
id: call.id,
name: call.name,
arguments: call.arguments ? JSON.parse(call.arguments) : {}
}));
console.log('\nFinal tool calls ready to execute:');
console.log(JSON.stringify(toolCalls, null, 2));
}
}
REST
# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Api-Revision: 2026-05-20" \
-d '{
"model": "gemini-3-flash-preview",
"input": "What is the weather in Paris?",
"tools": [{
"type": "function",
"name": "get_weather",
"description": "Gets the weather for a given location.",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "The city and state"}
},
"required": ["location"]
}
}],
"stream": true
}'
แนวทางปฏิบัติแนะนำ
- คำอธิบายฟังก์ชันและพารามิเตอร์: ชัดเจนและเฉพาะเจาะจง
- การตั้งชื่อ: ใช้ชื่อที่สื่อความหมายโดยไม่มีการเว้นวรรคหรือสัญลักษณ์พิเศษ
- การพิมพ์ที่รัดกุม: ใช้ประเภทที่เฉพาะเจาะจง (จำนวนเต็ม สตริง Enum)
- การเลือกเครื่องมือ: ตั้งค่าเครื่องมือที่ใช้งานอยู่ให้มีจำนวนสูงสุด 10-20 รายการ
- การเขียนพรอมต์: ระบุบริบทและคำสั่ง
- การตรวจสอบ: ตรวจสอบการเรียกใช้ฟังก์ชันก่อนดำเนินการ
- การจัดการข้อผิดพลาด: ใช้การจัดการข้อผิดพลาดที่มีประสิทธิภาพ
- ความปลอดภัย: ใช้การตรวจสอบสิทธิ์ที่เหมาะสมสำหรับ API ภายนอก
หมายเหตุและข้อจำกัด
- ระบบรองรับเฉพาะชุดย่อยของสคีมา OpenAPI
- สำหรับโหมด
anyAPI อาจปฏิเสธสคีมาที่มีขนาดใหญ่มากหรือซ้อนกันลึก - ประเภทพารามิเตอร์ที่รองรับใน Python มีจำกัด