# 在 Live API 中使用工具

工具的使用使 Live API 能够超越单纯的对话，使其能够在现实世界中执行操作并引入外部上下文，同时保持实时连接。您可以定义工具，例如 [函数调用](/docs/function-calling) 和 [Google 搜索](/docs/google-search)
与 Live API。

## 支持的工具概述  {% #tools-overview %}

{% doc-table %}
{% doc-row header="true" %}
{% doc-cell %}
工具
{% /doc-cell %}

{% doc-cell %}
Gemini 3.8 Live
{% /doc-cell %}

{% doc-cell %}
Gemini 3.8 Live Extended Thinking
{% /doc-cell %}

{% doc-cell %}
Gemini 3.1 Flash Live Preview
{% /doc-cell %}

{% doc-cell %}
Gemini 2.5 Flash Live Preview
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
**搜索**
{% /doc-cell %}

{% doc-cell %}
支持
{% /doc-cell %}

{% doc-cell %}
支持
{% /doc-cell %}

{% doc-cell %}
支持
{% /doc-cell %}

{% doc-cell %}
支持
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
**函数调用**
{% /doc-cell %}

{% doc-cell %}
支持（同步和 [异步](/docs/live-api/tools#async-function-calling))
{% /doc-cell %}

{% doc-cell %}
支持（[仅异步](/docs/live-api/tools#async-function-calling))
{% /doc-cell %}

{% doc-cell %}
支持（仅同步）
{% /doc-cell %}

{% doc-cell %}
支持（同步和 [异步](/docs/live-api/tools#async-function-calling))
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
**Google 地图**
{% /doc-cell %}

{% doc-cell %}
不支持
{% /doc-cell %}

{% doc-cell %}
不支持
{% /doc-cell %}

{% doc-cell %}
不支持
{% /doc-cell %}

{% doc-cell %}
不支持
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
**代码执行**
{% /doc-cell %}

{% doc-cell %}
不支持
{% /doc-cell %}

{% doc-cell %}
不支持
{% /doc-cell %}

{% doc-cell %}
不支持
{% /doc-cell %}

{% doc-cell %}
不支持
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
**URL 上下文**
{% /doc-cell %}

{% doc-cell %}
不支持
{% /doc-cell %}

{% doc-cell %}
不支持
{% /doc-cell %}

{% doc-cell %}
不支持
{% /doc-cell %}

{% doc-cell %}
不支持
{% /doc-cell %}
{% /doc-row %}
{% /doc-table %}

## 函数调用  {% #function-calling %}

Live API 支持函数调用，就像常规内容生成请求一样。 函数调用允许 Live API 与外部数据和程序交互，从而大大增加您的应用程序可以完成的任务。

您可以将函数声明定义为会话配置的一部分。收到工具调用后，客户端应响应一个列表 `FunctionResponse` 对象使用 `session.send_tool_response` 方法。

请参阅 [函数调用教程](/docs/function-calling) 了解更多。

{% callout type="note" %}
与 `generateContent` API、Live API 不支持自动工具响应处理。您必须在客户端代码中手动处理工具响应。
{% /callout %}

{% tabs %}
{% tab label="Python" %}
```python
import asyncio
import wave
from google import genai
from google.genai import types

client = genai.Client(http_options={"api_version": "v1beta"})

model = "gemini-3.8-live"

# Simple function definitions
turn_on_the_lights = {"name": "turn_on_the_lights"}
turn_off_the_lights = {"name": "turn_off_the_lights"}

tools = [{"function_declarations": [turn_on_the_lights, turn_off_the_lights]}]
config = {"response_modalities": ["AUDIO"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "Turn on the lights please"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        wf = wave.open("audio.wav", "wb")
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(24000) # Output is 24kHz

        async for response in session.receive():
            if response.data is not None:
                wf.writeframes(response.data)
            elif response.tool_call:
                print("The tool was called")
                function_responses = []
                for fc in response.tool_call.function_calls:
                    function_response = types.FunctionResponse(
                        id=fc.id,
                        name=fc.name,
                        response={ "result": "ok" } # simple, hard-coded function response
                    )
                    function_responses.append(function_response)

                await session.send_tool_response(function_responses=function_responses)

        wf.close()

if __name__ == "__main__":
    asyncio.run(main())
```
{% /tab %}

{% tab label="JavaScript" %}
```js
import { GoogleGenAI, Modality } from '@google/genai';
import * as fs from "node:fs";
import pkg from 'wavefile'; // npm install wavefile
const { WaveFile } = pkg;

const ai = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });
const model = 'gemini-3.8-live';

// Simple function definitions
const turn_on_the_lights = { name: "turn_on_the_lights" } // , description: '...', parameters: { ... }
const turn_off_the_lights = { name: "turn_off_the_lights" }

const tools = [{ functionDeclarations: [turn_on_the_lights, turn_off_the_lights] }]

const config = {
  responseModalities: [Modality.AUDIO],
  tools: tools
}

async function live() {
  const responseQueue = [];

  async function waitMessage() {
    let done = false;
    let message = undefined;
    while (!done) {
      message = responseQueue.shift();
      if (message) {
        done = true;
      } else {
        await new Promise((resolve) => setTimeout(resolve, 100));
      }
    }
    return message;
  }

  async function handleTurn() {
    const turns = [];
    let done = false;
    while (!done) {
      const message = await waitMessage();
      turns.push(message);
      if (message.serverContent && message.serverContent.turnComplete) {
        done = true;
      } else if (message.toolCall) {
        done = true;
      }
    }
    return turns;
  }

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        responseQueue.push(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  const inputTurns = 'Turn on the lights please';
  session.sendClientContent({ turns: inputTurns });

  let turns = await handleTurn();

  for (const turn of turns) {
    if (turn.toolCall) {
      console.debug('A tool was called');
      const functionResponses = [];
      for (const fc of turn.toolCall.functionCalls) {
        functionResponses.push({
          id: fc.id,
          name: fc.name,
          response: { result: "ok" } // simple, hard-coded function response
        });
      }

      console.debug('Sending tool response...\n');
      session.sendToolResponse({ functionResponses: functionResponses });
    }
  }

  // Check again for new messages
  turns = await handleTurn();

  // Combine audio data strings and save as wave file
  const combinedAudio = turns.reduce((acc, turn) => {
      if (turn.data) {
          const buffer = Buffer.from(turn.data, 'base64');
          const intArray = new Int16Array(buffer.buffer, buffer.byteOffset, buffer.byteLength / Int16Array.BYTES_PER_ELEMENT);
          return acc.concat(Array.from(intArray));
      }
      return acc;
  }, []);

  const audioBuffer = new Int16Array(combinedAudio);

  const wf = new WaveFile();
  wf.fromScratch(1, 24000, '16', audioBuffer); // output is 24kHz
  fs.writeFileSync('audio.wav', wf.toBuffer());

  session.close();
}

async function main() {
  await live().catch((e) => console.error('got error', e));
}

await main();
```
{% /tab %}
{% /tabs %}

通过单个提示，模型可以生成多个函数调用以及链接其输出所需的代码。这段代码在沙盒环境中执行，生成后续的 [Bidi生成内容工具调用](/api-reference/live#BidiGenerateContentToolCall) 消息。

## 异步函数调用  {% #async-function-calling %}

函数调用默认情况下按顺序执行，这意味着执行会暂停，直到每个函数调用的结果可用。这确保了顺序处理，这意味着在函数运行时您将无法继续与模型交互。

{% callout type="note" %}
支持异步函数调用 `gemini-3.8-live` 并要求 `gemini-3.8-live-extended-thinking`。不支持 `gemini-3.1-flash-live-preview`;对于该模型，执行会暂停，直到您发送工具响应。
{% /callout %}

如果您不想阻止对话，可以告诉模型异步运行函数。为此，您首先需要添加一个 `behavior` 到函数定义：

{% tabs %}
{% tab label="Python" %}
```python
# Non-blocking function definitions
turn_on_the_lights = {"name": "turn_on_the_lights", "behavior": "NON_BLOCKING"} # turn_on_the_lights will run asynchronously
turn_off_the_lights = {"name": "turn_off_the_lights"} # turn_off_the_lights will still pause all interactions with the model
```
{% /tab %}

{% tab label="JavaScript" %}
```js
import { GoogleGenAI, Modality, Behavior } from '@google/genai';

// Non-blocking function definitions
const turn_on_the_lights = {name: "turn_on_the_lights", behavior: Behavior.NON_BLOCKING}

// Blocking function definitions
const turn_off_the_lights = {name: "turn_off_the_lights"}

const tools = [{ functionDeclarations: [turn_on_the_lights, turn_off_the_lights] }]
```
{% /tab %}
{% /tabs %}

`NON-BLOCKING` 确保函数异步运行，同时您可以继续与模型交互。

然后你需要告诉模型当它接收到时如何表现 `FunctionResponse` 使用 `scheduling` 参数。它可以：

* 中断它正在做的事情并告诉您它立即得到的响应（`scheduling="INTERRUPT"`),

* 等到它完成当前正在做的事情（`scheduling="WHEN_IDLE"`),

* 或者什么也不做，并在稍后的讨论中使用这些知识（`scheduling="SILENT"`)

{% tabs %}
{% tab label="Python" %}
```python
# for a non-blocking function definition, apply scheduling in the function response:
  function_response = types.FunctionResponse(
      id=fc.id,
      name=fc.name,
      response={
          "result": "ok",
          "scheduling": "INTERRUPT" # Can also be WHEN_IDLE or SILENT
      }
  )
```
{% /tab %}

{% tab label="JavaScript" %}
```js
import { GoogleGenAI, Modality, Behavior, FunctionResponseScheduling } from '@google/genai';

// for a non-blocking function definition, apply scheduling in the function response:
const functionResponse = {
  id: fc.id,
  name: fc.name,
  response: {
    result: "ok",
    scheduling: FunctionResponseScheduling.INTERRUPT // Can also be WHEN_IDLE or SILENT
  }
}
```
{% /tab %}
{% /tabs %}

## 使用 Google 搜索提供事实依据  {% #google-search %}

您可以在会话配置中启用事实依据和 Google 搜索。这提高了 Live API 的准确性并防止产生幻觉。请参阅 [事实依据教程](/docs/google-search) 了解更多。

{% tabs %}
{% tab label="Python" %}
```python
import asyncio
import wave
from google import genai
from google.genai import types

client = genai.Client(http_options={"api_version": "v1beta"})

model = "gemini-3.8-live"

tools = [{'google_search': {}}]
config = {"response_modalities": ["AUDIO"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "When did the last Brazil vs. Argentina soccer match happen?"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        wf = wave.open("audio.wav", "wb")
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(24000) # Output is 24kHz

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.data is not None:
                    wf.writeframes(chunk.data)

                # The model might generate and execute Python code to use Search
                model_turn = chunk.server_content.model_turn
                if model_turn:
                    for part in model_turn.parts:
                        if part.executable_code is not None:
                            print(part.executable_code.code)

                        if part.code_execution_result is not None:
                            print(part.code_execution_result.output)

        wf.close()

if __name__ == "__main__":
    asyncio.run(main())
```
{% /tab %}

{% tab label="JavaScript" %}
```js
import { GoogleGenAI, Modality } from '@google/genai';
import * as fs from "node:fs";
import pkg from 'wavefile'; // npm install wavefile
const { WaveFile } = pkg;

const ai = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });
const model = 'gemini-3.8-live';

const tools = [{ googleSearch: {} }]
const config = {
  responseModalities: [Modality.AUDIO],
  tools: tools
}

async function live() {
  const responseQueue = [];

  async function waitMessage() {
    let done = false;
    let message = undefined;
    while (!done) {
      message = responseQueue.shift();
      if (message) {
        done = true;
      } else {
        await new Promise((resolve) => setTimeout(resolve, 100));
      }
    }
    return message;
  }

  async function handleTurn() {
    const turns = [];
    let done = false;
    while (!done) {
      const message = await waitMessage();
      turns.push(message);
      if (message.serverContent && message.serverContent.turnComplete) {
        done = true;
      } else if (message.toolCall) {
        done = true;
      }
    }
    return turns;
  }

  const session = await ai.live.connect({
    model: model,
    callbacks: {
      onopen: function () {
        console.debug('Opened');
      },
      onmessage: function (message) {
        responseQueue.push(message);
      },
      onerror: function (e) {
        console.debug('Error:', e.message);
      },
      onclose: function (e) {
        console.debug('Close:', e.reason);
      },
    },
    config: config,
  });

  const inputTurns = 'When did the last Brazil vs. Argentina soccer match happen?';
  session.sendClientContent({ turns: inputTurns });

  let turns = await handleTurn();

  let combinedData = '';
  for (const turn of turns) {
    if (turn.serverContent && turn.serverContent.modelTurn && turn.serverContent.modelTurn.parts) {
      for (const part of turn.serverContent.modelTurn.parts) {
        if (part.executableCode) {
          console.debug('executableCode: %s\n', part.executableCode.code);
        }
        else if (part.codeExecutionResult) {
          console.debug('codeExecutionResult: %s\n', part.codeExecutionResult.output);
        }
        else if (part.inlineData && typeof part.inlineData.data === 'string') {
          combinedData += atob(part.inlineData.data);
        }
      }
    }
  }

  // Convert the base64-encoded string of bytes into a Buffer.
  const buffer = Buffer.from(combinedData, 'binary');

  // The buffer contains raw bytes. For 16-bit audio, we need to interpret every 2 bytes as a single sample.
  const intArray = new Int16Array(buffer.buffer, buffer.byteOffset, buffer.byteLength / Int16Array.BYTES_PER_ELEMENT);

  const wf = new WaveFile();
  // The API returns 16-bit PCM audio at a 24kHz sample rate.
  wf.fromScratch(1, 24000, '16', intArray);
  fs.writeFileSync('audio.wav', wf.toBuffer());

  session.close();
}

async function main() {
  await live().catch((e) => console.error('got error', e));
}

await main();
```
{% /tab %}
{% /tabs %}

## 结合多种工具  {% #combine-tools %}

您可以在 Live API 中组合多个工具，进一步增强应用程序的功能：

{% tabs %}
{% tab label="Python" %}
```python
prompt = """
Hey, I need you to do two things for me.

1. Use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024?
2. Then turn on the lights

Thanks!
"""

tools = [
    {"google_search": {}},
    {"function_declarations": [turn_on_the_lights, turn_off_the_lights]},
]

config = {"response_modalities": ["AUDIO"], "tools": tools}

# ... remaining model call
```
{% /tab %}

{% tab label="JavaScript" %}
```js
const prompt = `Hey, I need you to do two things for me.

1. Use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024?
2. Then turn on the lights

Thanks!
`

const tools = [
  { googleSearch: {} },
  { functionDeclarations: [turn_on_the_lights, turn_off_the_lights] }
]

const config = {
  responseModalities: [Modality.AUDIO],
  tools: tools
}

// ... remaining model call
```
{% /tab %}
{% /tabs %}

## 后续步骤  {% #whats-next %}

* 查看使用 Live API 工具的更多示例 [工具使用食谱](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Get_started_LiveAPI_tools.ipynb).

* 从以下位置获取有关功能和配置的完整故事 [Live API 功能指南](/docs/live-api/capabilities).
