Mengonfigurasi kemampuan Gemini

Dokumen ini menunjukkan cara mengonfigurasi berbagai kemampuan model Gemini saat menggunakan Gemini Live API. Anda dapat mengonfigurasi penggunaan alat seperti pemanggilan fungsi dan grounding, serta kemampuan audio live seperti dialog afektif dan audio proaktif.

Mengonfigurasi penggunaan alat

Beberapa alat kompatibel dengan berbagai versi model yang didukung Gemini Live API, termasuk:

Untuk mengaktifkan alat tertentu agar dapat digunakan dalam respons yang ditampilkan, sertakan nama alat dalam daftar tools saat Anda melakukan inisialisasi model. Bagian berikut memberikan contoh cara menggunakan setiap alat bawaan dalam kode Anda.

Penting: Gemini API tidak mendukung penggabungan alat penelusuran (seperti googleSearch) dengan alat non-penelusuran (seperti panggilan fungsi atau alat retrieval RAG Engine Gemini Enterprise Agent Platform) dalam permintaan penyiapan yang sama. Beberapa alat hanya didukung jika semuanya adalah alat penelusuran.

Panggilan fungsi

Gunakan panggilan fungsi jika Anda ingin model berinteraksi dengan sistem atau API eksternal yang Anda kelola. Gunakan ini untuk tugas seperti memeriksa database, mengirim email, atau berinteraksi dengan API kustom. Gemini Live API mendukung panggilan fungsi asinkron. Untuk mengetahui informasi selengkapnya, lihat Pemanggilan fungsi asinkron dengan Gemini Live API.

Model membuat panggilan fungsi, dan aplikasi Anda mengeksekusi kode serta mengirimkan hasilnya kembali ke model.

Semua fungsi harus dideklarasikan di awal sesi dengan mengirimkan definisi alat sebagai bagian dari pesan LiveConnectConfig.

Untuk mengaktifkan panggilan fungsi, sertakan function_declarations dalam daftar tools di pesan penyiapan:

Python

import asyncio

from google import genai
from google.genai.types import (
    Content,
    LiveConnectConfig,
    Part,
)

# Initialize the client.
client = genai.Client(
    enterprise=True,
    project="GOOGLE_CLOUD_PROJECT",  # Replace with your project ID
    location="LOCATION",  # Replace with your location
)

MODEL_ID = "gemini-3.8-live"


def get_current_weather(location: str) -> str:
    """Example method. Returns the current weather.

    Args:
        location: The city and state, e.g. San Francisco, CA
    """
    weather_map: dict[str, str] = {
        "Boston, MA": "snowing",
        "San Francisco, CA": "foggy",
        "Seattle, WA": "raining",
        "Austin, TX": "hot",
        "Chicago, IL": "windy",
    }
    return weather_map.get(location, "unknown")


async def main():
    config = LiveConnectConfig(
        response_modalities=["AUDIO"],
        tools=[get_current_weather],
    )

    async with client.aio.live.connect(
        model=MODEL_ID,
        config=config,
    ) as session:
        text_input = "Get the current weather in Boston."
        print(f"Input: {text_input}")

        await session.send_realtime_input(text=text_input)
        )

        async for message in session.receive():
            if message.tool_call:
                function_responses = []
                for function_call in message.tool_call.function_calls:
                    print(f"FunctionCall > {function_call}")
                    # Execute the tool and send the response back to the model.
                    result = get_current_weather(**function_call.args)
                    function_responses.append(
                        {
                            "name": function_call.name,
                            "response": {"result": result},
                            "id": function_call.id,
                        }
                    )
                if function_responses:
                    await session.send_tool_response(function_responses=function_responses)


if __name__ == "__main__":
    asyncio.run(main())

Untuk contoh penggunaan pemanggilan fungsi dalam petunjuk sistem, lihat contoh praktik terbaik.

Alat Model Context Protocol (MCP)

Google Gen AI SDK tidak otomatis menjalankan panggilan alat Model Context Protocol (MCP) dalam sesi Gemini Live API. Untuk menggunakan alat MCP dalam sesi Gemini Live API, Anda dapat menggunakan salah satu pendekatan berikut:

  • Mengelola panggilan alat MCP secara langsung: Jika Anda menggunakan Google Gen AI SDK secara langsung, aplikasi Anda harus mengelola sesi klien MCP, mengeksekusi panggilan alat saat diminta oleh model, dan menampilkan hasilnya menggunakan send_tool_response.
  • Gunakan Agent Development Kit (ADK): Gunakan class McpToolset di ADK, yang menyediakan integrasi MCP bawaan untuk Gemini Live API. ADK otomatis menemukan alat dari server MCP Anda, mengonversi skemanya menjadi deklarasi fungsi, menjalankan panggilan alat MCP selama aliran dua arah, dan mengirimkan respons alat kembali ke model.

Menggunakan alat MCP dengan ADK

Anda dapat menggunakan ADK untuk menghubungkan alat MCP ke Gemini Live API menggunakan langkah-langkah berikut:

  1. Instal paket google-adk dengan ekstra mcp:

    pip install "google-adk[mcp]"

  2. Buat skrip bernama live_mcp_example.py yang menghubungkan McpToolset ke layanan MCP Anda menggunakan StreamableHTTPConnectionParams dan menstreaming peristiwa menggunakan runner.run_live().

    Ganti kode berikut:

    • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.
    • MCP_SERVER_URL: URL server MCP HTTP Streamable Anda (misalnya, http://127.0.0.1:8765/mcp).
    import asyncio
import contextlib
import os

from google.adk.agents import Agent, LiveRequestQueue, RunConfig
from google.adk.agents.run_config import StreamingMode
from google.adk.runners import InMemoryRunner
from google.adk.tools.mcp_tool import McpToolset, StreamableHTTPConnectionParams
from google.genai import types

os.environ.setdefault("GOOGLE_GENAI_USE_ENTERPRISE", "TRUE")
os.environ.setdefault("GOOGLE_CLOUD_PROJECT", "PROJECT_ID")
os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "us-central1")

async def main() -> None:
  # 1. Connect to the Streamable HTTP MCP service
  mcp_toolset = McpToolset(
      connection_params=StreamableHTTPConnectionParams(
          url="MCP_SERVER_URL",
      )
  )

  # 2. Create the ADK Agent with a Gemini Live model and the MCP toolset
  agent = Agent(
      name="mcp_live_agent",
      model="gemini-3.8-live",
      instruction="You are a helpful assistant. Use the provided MCP tools when needed.",
      tools=[mcp_toolset],
  )

  runner = InMemoryRunner(agent=agent, app_name="mcp_live_demo")
  session = await runner.session_service.create_session(
      app_name="mcp_live_demo",
      user_id="user_1",
  )

  # 3. Configure bidirectional streaming and send a prompt
  live_request_queue = LiveRequestQueue()
  run_config = RunConfig(
      streaming_mode=StreamingMode.BIDI,
      response_modalities=[types.Modality.AUDIO],
      output_audio_transcription=types.AudioTranscriptionConfig(),
  )

  live_request_queue.send_content(
      types.Content(
          role="user",
          parts=[types.Part.from_text(text="What is the weather in Paris?")],
      )
  )

  # 4. Stream Live events (ADK automatically executes MCP tools)
  awaiting_post_tool_response = False
  saw_function_response = False
  has_model_output = False

  try:
    async with contextlib.aclosing(
        runner.run_live(
            user_id="user_1",
            session_id=session.id,
            live_request_queue=live_request_queue,
            run_config=run_config,
        )
    ) as live_events:
      async for event in live_events:
        for call in event.get_function_calls():
          print(f"[MCP Tool Call] {call.name}({call.args})")
          awaiting_post_tool_response = True
          saw_function_response = False
          has_model_output = False

        for resp in event.get_function_responses():
          print(f"[MCP Tool Response] {resp.name} -> {resp.response}")
          saw_function_response = True

        if event.output_transcription and event.output_transcription.text:
          if not awaiting_post_tool_response or saw_function_response:
            has_model_output = True
            awaiting_post_tool_response = False
          if event.output_transcription.finished:
            print(f"[Transcript] {event.output_transcription.text}")

        # Wait for the final response turn after tool execution completes
        if event.turn_complete:
          if awaiting_post_tool_response or not has_model_output:
            continue
          live_request_queue.close()
          break
  finally:
    await mcp_toolset.close()
    await runner.close()

if __name__ == "__main__":
  asyncio.run(main())

Gunakan Grounding with Google Search jika Anda ingin model memberikan respons yang lebih akurat dan faktual dengan mengaitkannya ke sumber informasi yang dapat diverifikasi. Gunakan ini untuk tugas seperti menelusuri web.

Tidak seperti pemanggilan fungsi, integrasi sisi server menangani pengambilan informasi secara otomatis.

Untuk mengaktifkan Grounding with Google Search, sertakan google_search dalam daftar tools di pesan penyiapan:

Python

import asyncio

from google import genai
from google.genai.types import (
    Content,
    LiveConnectConfig,
    Part,
)

# Initialize the client.
client = genai.Client(
    enterprise=True,
    project="GOOGLE_CLOUD_PROJECT",  # Replace with your project ID
    location="LOCATION",  # Replace with your location
)

MODEL_ID = "gemini-3.8-live"


async def main():
    config = LiveConnectConfig(
        response_modalities=["AUDIO"],
        tools=[{"google_search": {}}],
    )

    async with client.aio.live.connect(
        model=MODEL_ID,
        config=config,
    ) as session:
        text_input = "What is the current weather in Toronto, Canada?"
        print(f"Input: {text_input}")

        await session.send_realtime_input(text=text_input)

        async for message in session.receive():
            # Consume the messages from the model.
            # In native audio, the model response is in audio format.
            pass


if __name__ == "__main__":
    asyncio.run(main())

Mengonfigurasi Dialog Afektif

Konfigurasi dialog afektif hanya diperlukan untuk gemini-live-2.5-flash-native-audio. Bagian ini tidak berlaku untuk gemini-3.8-live.

Jika Dialog Afektif diaktifkan, model akan mencoba memahami dan merespons berdasarkan nada suara dan ekspresi emosional pengguna.

Untuk mengaktifkan Dialog Afektif, tetapkan enable_affective_dialog ke true dalam pesan penyiapan:

Python

config = LiveConnectConfig(
    response_modalities=["AUDIO"],
    enable_affective_dialog=True,
)

Mengonfigurasi Audio Proaktif

Konfigurasi audio proaktif hanya diperlukan untuk gemini-live-2.5-flash-native-audio. Audio proaktif disertakan dalam gemini-3.8-live.

Audio Proaktif memungkinkan Anda mengontrol kapan model merespons. Misalnya, Anda dapat meminta Gemini untuk hanya merespons saat diminta atau saat topik tertentu dibahas. Untuk melihat demonstrasi video Audio Proaktif, lihat Pratinjau Audio Native Gemini Live API.

Untuk mengaktifkan Audio Proaktif, konfigurasikan kolom proactivity dalam pesan penyiapan dan tetapkan proactive_audio ke true:

Python

config = LiveConnectConfig(
    response_modalities=["AUDIO"],
    proactivity=ProactivityConfig(proactive_audio=True),
)

Contoh percakapan

Berikut adalah contoh percakapan dengan Gemini tentang memasak:

Prompt: "You are an AI assistant in Italian cooking; only chime in when the topic is about Italian cooking."

Speaker A: "I really love cooking!" (No response from Gemini.)

Speaker B: "Oh yes, me too! My favorite is French cuisine." (No response from
Gemini.)

Speaker A: "I really like Italian food; do you know how to make a pizza?"

(Italian cooking topic triggers response from Gemini.)
Gemini Live API: "I'd be happy to help! Here's a recipe for a pizza."

Kasus penggunaan umum

Saat menggunakan Audio Proaktif, Gemini akan berfungsi sebagai berikut:

  • Merespons dengan latensi minimal: Gemini merespons setelah pengguna selesai berbicara, sehingga mengurangi gangguan dan membantu Gemini tidak kehilangan konteks jika terjadi gangguan.
  • Menghindari gangguan: Audio Proaktif membantu Gemini menghindari gangguan dari kebisingan latar belakang atau percakapan eksternal, dan mencegah Gemini merespons jika percakapan eksternal terjadi selama percakapan.
  • Menangani interupsi: Jika pengguna perlu menginterupsi respons dari Gemini, Audio Proaktif akan mempermudah Gemini untuk melakukan back-channel dengan tepat (artinya interupsi yang tepat akan ditangani), daripada jika pengguna menggunakan kata pengisi seperti mmm atau eh.
  • Mendengarkan audio bersama: Gemini dapat mendengarkan bersama file audio yang bukan suara pembicara, lalu menjawab pertanyaan tentang file audio tersebut nanti dalam percakapan.

Penagihan

Saat Gemini mendengarkan percakapan, token audio input akan dikenai biaya.

Untuk token audio output, Anda hanya dikenai biaya saat Gemini merespons. Jika Gemini tidak merespons atau tetap diam, tidak ada biaya untuk token audio output Anda.

Untuk mengetahui informasi selengkapnya, lihat Harga Agent Platform.

Langkah berikutnya

Untuk mengetahui informasi selengkapnya tentang cara menggunakan Gemini Live API, lihat: