Interactions API là một giao diện thống nhất để xây dựng các ứng dụng với các mô hình Gemini và tác nhân (agents). Nó đơn giản hóa việc phát triển các ứng dụng có tính tác nhân (agentic) bằng cách xử lý việc quản lý trạng thái phía máy chủ (server-side), điều phối công cụ (tool orchestration) và các tác vụ chạy dài.
Chỉ với một điểm cuối (endpoint) duy nhất, bạn có thể:
  • Tương tác với các mô hình Gemini để tạo văn bản, hình ảnh và âm thanh.
  • Xây dựng các cuộc hội thoại nhiều lượt mà không cần tự quản lý lịch sử ở phía máy khách (client-side).
  • Gọi các hàm tùy chỉnh và các công cụ tích hợp sẵn như Google Search.
  • Chạy các tác nhân chuyên biệt như Deep Research cho các nhiệm vụ phức tạp.

Điều kiện tiên quyết

Lấy một Gemini API key và cài đặt Google GenAI SDK:
pip install google-genai
Thiết lập mã khóa API của bạn:
export GEMINI_API_KEY="your-api-key"

Tạo một tương tác (Interaction)

Ở mức độ đơn giản nhất, Interactions API hoạt động tương tự như một lệnh hoàn thiện trò chuyện (chat completion) tiêu chuẩn. Bạn cung cấp một mô hình và một chuỗi đầu vào. Theo mặc định, các tương tác sẽ được lưu trữ (store=True), cho phép bạn tham chiếu lại chúng sau này.
from google import genai
 
client = genai.Client()
 
interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    system_instruction="Bạn là một trợ lý hữu ích.",
    input="Giải thích về rối lượng tử trong một câu."
)
 
print(interaction.outputs[-1].text)
# Kết quả: Rối lượng tử là một hiện tượng trong đó các hạt trở nên liên kết với nhau

Hội thoại nhiều lượt có trạng thái (Stateful Multi-turn)

Một trong những tính năng mạnh mẽ nhất của API này là quản lý trạng thái phía máy chủ. Bạn không cần phải nối thêm tin nhắn vào một danh sách và gửi toàn bộ lịch sử quay lại máy chủ mỗi lần.
Hãy sử dụng previous_interaction_id để tiếp tục một cuộc hội thoại.
Lưu ý: Chỉ có lịch sử hội thoại được bảo tồn. Các tham số như tools hoặc generation_config chỉ có phạm vi trong một tương tác (interaction-scoped) và phải được khai báo lại nếu cần thiết.
from google import genai
 
client = genai.Client()
 
turn_1 = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Tên tôi là Alice và tôi là một kỹ sư phần mềm."
)
print(f"Turn 1 ID: {turn_1.id}")
 
turn_2 = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Công việc của tôi là gì?",
    previous_interaction_id=turn_1.id
)
 
print(turn_2.outputs[-1].text)
# Kết quả: Bạn là một kỹ sư phần mềm.
Để tìm hiểu về lịch sử do phía máy khách quản lý, hãy xem phần Hội thoại không trạng thái (Stateless conversations).

Rẽ nhánh hội thoại (Forking Conversations)

Vì trạng thái được quản lý theo ID, bạn có thể "rẽ nhánh" một cuộc hội thoại bằng cách tham chiếu đến một ID tương tác cũ hơn với một câu lệnh (prompt) khác.
# Rẽ nhánh từ Lượt 1 với một chủ đề khác
turn_2_fork = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Tên tôi là gì?",
    previous_interaction_id=turn_1.id
)
 
print(turn_2_fork.outputs[-1].text)
# Kết quả: Tên của bạn là Alice.

Tương tác đa phương thức (Multimodal Interactions)

Các mô hình Gemini hiểu và tạo ra nhiều loại nội dung một cách tự nhiên. Bạn có thể truyền văn bản, hình ảnh, âm thanh hoặc tài liệu PDF trong một tương tác duy nhất. Ví dụ này sử dụng một URL hình ảnh từ xa.

Khả năng hiểu đa phương thức:

from google import genai
 
client = genai.Client()
 
interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=[
        {"type": "text", "text": "Hãy tạo công thức nấu ăn cho món bánh scones trong hình."},
        {
            "type": "image", 
            "uri": "https://storage.googleapis.com/generativeai-downloads/images/scones.jpg"
        }
    ],
)
 
print(interaction.outputs[-1].text)
Để tìm hiểu về khả năng hiểu âm thanh, video và tài liệu (PDF), hãy xem phần Multimodal understanding.

Khả năng tạo đa phương thức:

import base64
from google import genai
 
client = genai.Client()
 
interaction = client.interactions.create(
    model="gemini-3-pro-image-preview",
    input="Tạo một hình ảnh về thành phố tương lai lúc hoàng hôn."
)
 
for output in interaction.outputs:
    if output.type == "image":
        with open("city.png", "wb") as f:
            f.write(base64.b64decode(output.data))
Để tìm hiểu về khả năng tạo âm thanh, hãy xem phần Multimodal generations.

Sử dụng Công cụ (Tool use)

Các công cụ mở rộng khả năng của mô hình bằng cách cho phép nó gọi các hàm hoặc dịch vụ bên ngoài. API bao gồm các công cụ sẵn có như Google Search, và cho phép bạn định nghĩa các công cụ tùy chỉnh dưới dạng JSON schema. Mô hình sẽ tự quyết định thời điểm gọi chúng dựa trên nội dung hội thoại:

Công cụ tích hợp sẵn:

from google import genai
 
client = genai.Client()
 
interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Ai đã giành giải Nobel Vật lý năm 2024?",
    tools=[{"type": "google_search"}]
)
 
text_output = next((o for o in interaction.outputs if o.type == "text"), None)
if text_output:
    print(text_output.text)
Các công cụ tích hợp sẵn khác bao gồm Thực thi mã (Code Execution) và Sử dụng máy tính (Computer Use).

Gọi hàm (Function calling):

from google import genai
 
client = genai.Client()
 
# Định nghĩa một công cụ
weather_tool = {
    "type": "function",
    "name": "get_weather",
    "description": "Lấy thời tiết hiện tại của một địa điểm",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {"type": "string", "description": "Tên thành phố"}
        },
        "required": ["location"]
    }
}
 
# Gửi yêu cầu kèm theo công cụ
interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Thời tiết ở Tokyo thế nào?",
    tools=[weather_tool]
)
 
# Xử lý phản hồi gọi hàm
for output in interaction.outputs:
    if output.type == "function_call":
        # Thực thi hàm của bạn (giả lập ở đây)
        # result = get_weather(output.arguments)
        result = {"temperature": "22°C", "condition": "nắng"}
 
        # Trả kết quả về cho mô hình
        interaction = client.interactions.create(
            model="gemini-3-flash-preview",
            previous_interaction_id=interaction.id,
            input={
                "type": "function_result",
                "name": output.name,
                "call_id": output.id,
                "result": result
            }
        )
        print(interaction.outputs[-1].text)
Để tìm hiểu về thực thi mã, ngữ cảnh URL và máy chủ MCP, hãy xem phần Agentic capabilities.

Tác nhân & Các tác vụ chạy dài (Agents & Long-Running Tasks)

Ngoài các mô hình, Interactions API còn cung cấp quyền truy cập vào các tác nhân chuyên biệt. Deep Research thực hiện các nhiệm vụ nghiên cứu đa bước, tổng hợp thông tin từ nhiều nguồn thành các báo cáo toàn diện.
Các tác nhân chạy bất đồng bộ với tham số background=True. Bạn cần kiểm tra (poll) trạng thái tương tác để lấy kết quả:
import time
from google import genai
 
client = genai.Client()
 
agent_interaction = client.interactions.create(
    agent="deep-research-pro-preview-12-2025", # Lưu ý: dùng 'agent', không phải 'model'
    input="Nghiên cứu lịch sử của Google TPU, tập trung vào thông số kỹ thuật năm 2025.",
    background=True
)
 
# Kiểm tra định kỳ để đợi hoàn thành
while True:
    status_check = client.interactions.get(agent_interaction.id)
    print(f"Trạng thái: {status_check.status}")
    
    if status_check.status == "completed":
        print("n--- Báo cáo cuối cùng ---n")
        print(status_check.outputs[-1].text)
        break
    elif status_check.status in ["failed", "cancelled"]:
        print("Tác nhân thất bại.")
        break
        
    time.sleep(10)
Để biết thêm chi tiết, hãy xem phần Deep Research.

Các bước tiếp theo

Interactions API hỗ trợ nhiều luồng công việc phức tạp hơn. Hãy kiểm tra API Reference để biết chi tiết về:
  • Đầu ra có cấu trúc (Structured Outputs): Ép buộc mô hình trả về JSON hợp lệ theo một schema cụ thể.
  • Truyền dữ liệu (Streaming): Truyền các phản hồi dưới dạng token theo thời gian thực.
  • Mô hình tư duy (Thinking Models): Cấu hình thinking_level cho các mô hình Gemini 2.5 và 3.0 để xử lý suy luận phức tạp.
  • MCP từ xa: Kết nối Gemini với các máy chủ MCP riêng của bạn.
  • Kết hợp công cụ và đầu ra có cấu trúc: Tạo ra các quy trình làm việc phức tạp hơn.
  • Tải tệp lên: Tải tệp lên mô hình để xử lý.
  • Mô hình dữ liệu: Tổng quan cấp cao về các đầu vào và đầu ra chính của API.

Phản hồi

API này đang ở giai đoạn Beta và chúng tôi rất mong nhận được phản hồi từ bạn! Chúng tôi đang tích cực lắng nghe các nhà phát triển để định hình tương lai của API này. Tính năng nào sẽ giúp ích cho quy trình làm việc của bạn? Bạn đang gặp phải những khó khăn gì? Vui lòng cho tôi biết qua Twitter hoặc LinkedIn.
Nguồn bài viết từ Tác giả Phil Schmid