# How to Implement Tool Use with the Gemini Interactions API

> Learn to implement tool use with the Gemini Interactions API. Pass local functions, execute them securely, and enhance your AI applications. Get started today.

- Repository: [Google/skills](https://github.com/google/skills)
- Tags: how-to-guide
- Published: 2026-06-11

---

**Use the unified Gen AI SDK (`google-genai >= 2.0.0` for Python or `@google/genai >= 2.0.0` for TypeScript) to pass local functions via the `tools` parameter, inspect the response for `tool_calls`, execute the requested functions locally, and continue the conversation by referencing the previous interaction's ID via `previous_interaction_id` or `previousInteractionId`.**

The Gemini Interactions API, part of the Gemini Enterprise Agent Platform, supports **tool use** (also known as function calling) to enable models to request execution of user-defined functions during stateful conversations. As documented in the `google/skills` repository, this capability requires strict adherence to the unified Gen AI SDK and turn-scoped parameter patterns defined in [`skills/cloud/gemini-interactions-api/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/gemini-interactions-api/SKILL.md).

## Prerequisites and SDK Requirements

The Gemini Interactions API only supports the unified Gen AI SDK. Legacy packages are explicitly prohibited.

- **Python**: Install `google-genai >= 2.0.0`
- **TypeScript/JavaScript**: Install `@google/genai >= 2.0.0`

Initialize the client with enterprise configuration:

```python
from google import genai
import google.auth

_, project_id = google.auth.default()
client = genai.Client(enterprise=True, project=project_id, location="global")

```

```typescript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI();

```

## Understanding Turn-Scoped Parameters

According to the source documentation in [`skills/cloud/gemini-interactions-api/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/gemini-interactions-api/SKILL.md), **turn-scoped parameters** must be supplied with every interaction request. These parameters are not persisted across turns.

Critical turn-scoped parameters include:

- `tools` – The list of callable functions or function declarations
- `system_instruction` – System-level directives for the model
- `generation_config` – Sampling parameters and output constraints

Failing to pass these parameters on subsequent turns results in the model losing access to previously defined tools or configurations.

## The Tool Use Implementation Pattern

Implementing tool use requires a four-step workflow: defining tools, passing them to the model, executing requested functions locally, and continuing the conversation with results.

### 1. Define Local Tools

Create standard Python functions or TypeScript functions that perform the desired operations. The unified SDK automatically serializes Python function signatures into the required schema. For TypeScript, you must explicitly define `functionDeclarations` with parameter schemas.

```python
def get_stock_price(ticker: str) -> float:
    """Return a mock price for a given ticker."""
    return {"GOOG": 175.50}.get(ticker.upper(), 100.0)

```

```typescript
function getStockPrice({ ticker }: { ticker: string }): number {
  return ticker.toUpperCase() === "GOOG" ? 175.5 : 100.0;
}

```

### 2. Pass Tools to the First Interaction

Include the tools in the initial `interactions.create` call using the `tools` parameter. In Python, pass the raw callable; in TypeScript, pass the structured declaration.

```python
first = client.interactions.create(
    model="gemini-3-flash-preview",
    input="What is the stock price of GOOG?",
    tools=[get_stock_price]          # Pass the callable directly

)

```

```typescript
const interaction = await ai.interactions.create({
  model: "gemini-3-flash-preview",
  input: "What is the stock price of GOOG?",
  tools: [
    {
      functionDeclarations: [
        {
          name: "getStockPrice",
          description: "Gets the stock price for a given ticker symbol.",
          parameters: {
            type: Type.OBJECT,
            properties: {
              ticker: { type: Type.STRING, description: "The ticker symbol" }
            },
            required: ["ticker"]
          }
        }
      ]
    }
  ]
});

```

### 3. Detect and Execute Tool Calls

Inspect the last step of the response for the `tool_calls` (Python) or `toolCalls` (TypeScript) array. If present, extract the function name and arguments, then execute the corresponding local function.

```python
last_step = first.steps[-1]
if last_step.tool_calls:
    for call in last_step.tool_calls:
        if call.name == "get_stock_price":
            ticker = call.args.get("ticker")
            price = get_stock_price(ticker)

```

```typescript
const lastStep = interaction.steps[interaction.steps.length - 1];
if (lastStep.toolCalls) {
  for (const call of lastStep.toolCalls) {
    if (call.name === "getStockPrice") {
      const ticker = call.args.ticker as string;
      const price = getStockPrice({ ticker });
    }
  }
}

```

### 4. Continue the Conversation with Results

Create a new interaction that references the original interaction's `id` via `previous_interaction_id` (Python) or `previousInteractionId` (TypeScript). Include the tool execution result in the new input to provide context for the model's final response.

```python
final = client.interactions.create(
    model="gemini-3-flash-preview",
    input=f"The stock price for {ticker} is ${price}.",
    previous_interaction_id=first.id   # Maintain state

)

```

```typescript
const finalTurn = await ai.interactions.create({
  model: "gemini-3-flash-preview",
  input: `The stock price for ${ticker} is $${price}.`,
  previousInteractionId: interaction.id   // Preserve state
});

```

## Complete Code Examples

### Python Implementation

```python
from google import genai
import google.auth

# Initialize client

_, project_id = google.auth.default()
client = genai.Client(enterprise=True, project=project_id, location="global")

# Define tool

def get_stock_price(ticker: str) -> float:
    """Return a mock price for a given ticker."""
    return {"GOOG": 175.50}.get(ticker.upper(), 100.0)

# First interaction

first = client.interactions.create(
    model="gemini-3-flash-preview",
    input="What is the stock price of GOOG?",
    tools=[get_stock_price]
)

# Execute tool calls

last_step = first.steps[-1]
if last_step.tool_calls:
    for call in last_step.tool_calls:
        if call.name == "get_stock_price":
            ticker = call.args.get("ticker")
            price = get_stock_price(ticker)
            
            # Continue with result

            final = client.interactions.create(
                model="gemini-3-flash-preview",
                input=f"The stock price for {ticker} is ${price}.",
                previous_interaction_id=first.id
            )
            print(final.steps[-1].content[0].text)

```

### TypeScript Implementation

```typescript
import { GoogleGenAI, Type } from "@google/genai";

const ai = new GoogleGenAI();

function getStockPrice({ ticker }: { ticker: string }): number {
  return ticker.toUpperCase() === "GOOG" ? 175.5 : 100.0;
}

const interaction = await ai.interactions.create({
  model: "gemini-3-flash-preview",
  input: "What is the stock price of GOOG?",
  tools: [
    {
      functionDeclarations: [
        {
          name: "getStockPrice",
          description: "Gets the stock price for a given ticker symbol.",
          parameters: {
            type: Type.OBJECT,
            properties: {
              ticker: { type: Type.STRING, description: "The ticker symbol" }
            },
            required: ["ticker"]
          }
        }
      ]
    }
  ]
});

const lastStep = interaction.steps[interaction.steps.length - 1];
if (lastStep.toolCalls) {
  for (const call of lastStep.toolCalls) {
    if (call.name === "getStockPrice") {
      const ticker = call.args.ticker as string;
      const price = getStockPrice({ ticker });

      const finalTurn = await ai.interactions.create({
        model: "gemini-3-flash-preview",
        input: `The stock price for ${ticker} is $${price}.`,
        previousInteractionId: interaction.id
      });
      console.log(finalTurn.steps[finalTurn.steps.length - 1].content[0].text);
    }
  }
}

```

## Streaming Tool Use Responses

To receive incremental chunks during the interaction, pass `stream=True` (Python) or `stream: true` (TypeScript) to the `interactions.create` method. This works for both the initial tool-calling turn and subsequent continuation turns.

```python
response = client.interactions.create(
    model="gemini-3-flash-preview",
    input="What is the stock price of GOOG?",
    tools=[get_stock_price],
    stream=True
)

```

## Summary

- **Use the unified SDK**: Only `google-genai >= 2.0.0` (Python) or `@google/genai >= 2.0.0` (TypeScript) support the Interactions API.
- **Pass tools every turn**: The `tools` parameter is turn-scoped and must be included in every request requiring function access.
- **Python vs. TypeScript**: Python accepts raw callables; TypeScript requires explicit `functionDeclarations` with JSON Schema parameter definitions.
- **Maintain state**: Use `previous_interaction_id` (Python) or `previousInteractionId` (TypeScript) to link multi-turn conversations after executing tool calls.
- **Check `tool_calls`**: Inspect the last step of the response for the `tool_calls` array to determine when local execution is required.

## Frequently Asked Questions

### What SDK versions are required to implement tool use with the Gemini Interactions API?

You must use the unified Gen AI SDK version 2.0.0 or higher. For Python, install `google-genai >= 2.0.0`. For TypeScript or JavaScript, install `@google/genai >= 2.0.0`. Legacy packages such as the older Vertex AI SDK or Google AI SDK are not compatible with the Interactions API.

### Do I need to pass the `tools` parameter on every interaction turn?

Yes. Parameters like `tools`, `system_instruction`, and `generation_config` are **turn-scoped**. According to the documentation in [`skills/cloud/gemini-interactions-api/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/gemini-interactions-api/SKILL.md), you must pass these parameters with each interaction request. If you omit `tools` on a subsequent turn, the model loses access to those functions.

### How do I maintain conversation state between the tool call and the result?

Create a new interaction that references the previous turn's ID using `previous_interaction_id` (Python) or `previousInteractionId` (TypeScript). This parameter links the turns into a single stateful conversation, allowing the model to see the original query, the tool execution result, and generate a final response with full context.

### Can I use streaming responses when implementing tool use?

Yes. Pass `stream=True` (Python) or `stream: true` (TypeScript) to `interactions.create()`. The streaming chunks will include the `tool_calls` data when the model decides to invoke a function, allowing you to process tool requests in real-time before continuing the conversation with the results.