Interactions API

Interactions API là nguyên tắc cơ bản tiêu chuẩn mới để xây dựng bằng Gemini, được đề xuất cho tất cả các dự án mới. Nền tảng này được tối ưu hoá cho quy trình công việc dựa trên tác nhân, quản lý trạng thái phía máy chủ và các cuộc trò chuyện phức tạp nhiều lượt, đa phương thức. API generateContent ban đầu vẫn được hỗ trợ đầy đủ.

Tại sao nên sử dụng Interactions API?

  • Quản lý nhật ký phía máy chủ: Đơn giản hoá các quy trình nhiều lượt thông qua previous_interaction_id. Theo mặc định, máy chủ sẽ bật trạng thái (store=true), nhưng bạn có thể chọn hành vi không trạng thái bằng cách đặt store=false.
  • Các bước thực thi có thể quan sát: Các bước được nhập giúp bạn dễ dàng gỡ lỗi các luồng phức tạp và hiển thị giao diện người dùng cho các sự kiện trung gian (chẳng hạn như suy nghĩ hoặc tiện ích tìm kiếm).
  • Được xây dựng cho quy trình công việc có tác nhân: Hỗ trợ nguyên bản cho việc sử dụng công cụ nhiều bước, điều phối và quy trình suy luận phức tạp thông qua các bước thực thi được nhập.
  • Các thao tác dài hạn và thao tác ở chế độ nền: Hỗ trợ giảm tải các thao tác tốn nhiều thời gian như Deep Think và Deep Research sang các quy trình ở chế độ nền bằng cách sử dụng background=true.
  • Quyền truy cập vào các mô hình và chức năng mới: Trong tương lai, các mô hình mới ngoài dòng mô hình chính cốt lõi, cùng với các khả năng của tác nhân AI và công cụ mới, sẽ chỉ ra mắt trên Interactions API.

Sử dụng Interactions API nếu bạn đang bắt đầu một dự án mới, xây dựng các ứng dụng dựa trên tác nhân hoặc cần quản lý cuộc trò chuyện phía máy chủ. Sử dụng generateContent nếu bạn có một quy trình tích hợp hiện có phù hợp với nhu cầu của mình hoặc nếu bạn cần một tính năng chưa có trong Interactions API, chẳng hạn như Batch API hoặc bộ nhớ đệm rõ ràng.

Bắt đầu

  • Thiết lập tác nhân lập trình: Kết nối với MCP của Gemini Docs và cài đặt kỹ năng gemini-interactions-api để trợ lý của bạn có quyền truy cập trực tiếp vào tài liệu mới nhất dành cho nhà phát triển và các phương pháp hay nhất. Thiết lập tác nhân lập trình →
  • Di chuyển từ generateContent: Nếu bạn đã tích hợp, hãy làm theo Hướng dẫn di chuyển để chuyển sang Interactions API.
  • Dùng thử hướng dẫn bắt đầu nhanh: Bắt đầu bằng một ví dụ hoạt động tối thiểu trong hướng dẫn bắt đầu nhanh về Interactions API.

Hướng dẫn về tính năng

Khám phá các chức năng cụ thể của Interactions API thông qua những hướng dẫn này. Bạn có thể dùng nút bật/tắt trên các trang này để chuyển đổi giữa generateContent và Interactions API:

Cách hoạt động của Interactions API

Interactions API tập trung vào một tài nguyên cốt lõi: Interaction. Interaction biểu thị một lượt hoàn thành trong cuộc trò chuyện hoặc việc cần làm. Đây là bản ghi phiên, chứa toàn bộ nhật ký tương tác dưới dạng một chuỗi các bước thực thi theo trình tự thời gian. Các bước này bao gồm suy nghĩ của mô hình, lệnh gọi và kết quả của công cụ phía máy chủ hoặc phía máy khách (chẳng hạn như function_call và function_result) và model_output cuối cùng. Tài nguyên được lưu trữ (truy xuất thông qua interactions.get) cũng bao gồm các bước user_input để có ngữ cảnh đầy đủ, mặc dù phản hồi interactions.create chỉ trả về các bước do mô hình tạo.

Khi thực hiện lệnh gọi đến interactions.create, bạn sẽ tạo một tài nguyên Interaction mới.

Quản lý trạng thái phía máy chủ

Bạn có thể sử dụng id của một lượt tương tác đã hoàn tất trong một lệnh gọi tiếp theo bằng cách sử dụng tham số previous_interaction_id để tiếp tục cuộc trò chuyện. Máy chủ sử dụng mã nhận dạng này để truy xuất nhật ký trò chuyện, giúp bạn không phải gửi lại toàn bộ nhật ký trò chuyện.

Tham số previous_interaction_id chỉ lưu giữ nhật ký cuộc trò chuyện (thông tin đầu vào và đầu ra) bằng cách sử dụng previous_interaction_id. Các thông số khác là có phạm vi tương tác và chỉ áp dụng cho tương tác cụ thể mà bạn hiện đang tạo:

  • tools
  • system_instruction
  • generation_config (bao gồm thinking_level, temperature, v.v.)

Điều này có nghĩa là bạn phải chỉ định lại các tham số này trong mỗi lượt tương tác mới nếu muốn áp dụng chúng. Bạn không bắt buộc phải quản lý trạng thái phía máy chủ; bạn cũng có thể hoạt động ở chế độ không trạng thái bằng cách gửi toàn bộ nhật ký trò chuyện trong mỗi yêu cầu.

Lưu trữ và giữ lại dữ liệu

Theo mặc định, API sẽ lưu trữ tất cả các đối tượng Tương tác (store=true) để đơn giản hoá việc sử dụng các tính năng quản lý trạng thái phía máy chủ (với previous_interaction_id), thực thi trong nền (bằng background=true) và mục đích quan sát.

  • Gói trả phí: Hệ thống lưu giữ các lượt tương tác trong 55 ngày.
  • Bậc miễn phí: Hệ thống giữ lại các lượt tương tác trong 1 ngày.

Nếu không muốn như vậy, bạn có thể đặt store=false trong yêu cầu của mình. Chế độ kiểm soát này tách biệt với việc quản lý trạng thái; bạn có thể chọn không lưu trữ cho bất kỳ hoạt động tương tác nào. Tuy nhiên, xin lưu ý rằng store=false không tương thích với background=true và ngăn việc sử dụng previous_interaction_id cho các lượt tiếp theo.

Bạn có thể xoá các hoạt động tương tác đã lưu trữ bất cứ lúc nào bằng phương thức xoá trong Tài liệu tham khảo API. Bạn chỉ có thể xoá các hoạt động tương tác nếu biết mã nhận dạng của hoạt động tương tác đó.

Sau khi hết khoảng thời gian lưu giữ, dữ liệu của bạn sẽ tự động bị xoá.

Hệ thống xử lý các đối tượng Tương tác theo các điều khoản.

Các phương pháp hay nhất

  • Tỷ lệ kết quả tìm kiếm trong bộ nhớ cache: Việc sử dụng previous_interaction_id để tiếp tục cuộc trò chuyện cho phép hệ thống dễ dàng sử dụng tính năng lưu vào bộ nhớ đệm ngầm cho nhật ký trò chuyện, giúp cải thiện hiệu suất và giảm chi phí.
  • Kết hợp các lượt tương tác: Bạn có thể linh hoạt kết hợp các lượt tương tác giữa Nhân viên hỗ trợ và Mô hình trong một cuộc trò chuyện. Ví dụ: bạn có thể sử dụng một tác nhân chuyên biệt (chẳng hạn như tác nhân Deep Research) để thu thập dữ liệu ban đầu, sau đó sử dụng một mô hình Gemini tiêu chuẩn cho các tác vụ tiếp theo như tóm tắt hoặc định dạng lại, liên kết các bước này với previous_interaction_id.

Các mô hình và tác nhân được hỗ trợ

Tên mô hình Loại Mã kiểu máy
Gemini 3.1 Flash-Lite Mô hình gemini-3.1-flash-lite
Bản xem trước Gemini 3.1 Flash-Lite Mô hình gemini-3.1-flash-lite-preview
Bản xem trước Gemini 3.1 Pro Mô hình gemini-3.1-pro-preview
Bản xem trước Gemini 3 Flash Mô hình gemini-3-flash-preview
Gemini 2.5 Pro Mô hình gemini-2.5-pro
Gemini 2.5 Flash Mô hình gemini-2.5-flash
Gemini 2.5 Flash-lite Mô hình gemini-2.5-flash-lite
Bản xem trước đoạn video do Lyria 3 tạo Mô hình lyria-3-clip-preview
Lyria 3 Pro (Bản xem trước) Mô hình lyria-3-pro-preview
Bản dùng thử Deep Research Nhân viên hỗ trợ deep-research-pro-preview-12-2025
Bản dùng thử Deep Research Nhân viên hỗ trợ deep-research-preview-04-2026
Bản dùng thử Deep Research Nhân viên hỗ trợ deep-research-max-preview-04-2026

SDK

Bạn có thể sử dụng phiên bản mới nhất của Google GenAI SDK để truy cập vào Interactions API.

  • Trên Python, đây là gói google-genai từ phiên bản 1.55.0 trở đi.
  • Trên JavaScript, đây là gói @google/genai từ phiên bản 1.33.0 trở lên.

Bạn có thể tìm hiểu thêm về cách cài đặt SDK trên trang Thư viện.

Các điểm hạn chế

  • Trạng thái thử nghiệm: Interactions API đang ở giai đoạn thử nghiệm beta/xem trước. Các tính năng và lược đồ có thể thay đổi.
  • MCP từ xa: Gemini 3 không hỗ trợ MCP từ xa, tính năng này sẽ sớm ra mắt.

API generateContent hỗ trợ các tính năng sau nhưng chưa có sẵn trong Interactions API:

Thay đổi có thể gây lỗi

Interactions API hiện đang ở giai đoạn thử nghiệm beta ban đầu. Chúng tôi đang tích cực phát triển và tinh chỉnh các chức năng API, lược đồ tài nguyên và giao diện SDK dựa trên việc sử dụng trong thực tế và ý kiến phản hồi của nhà phát triển. Do đó, có thể xảy ra các thay đổi có thể gây lỗi.

Các thay đổi có thể gây lỗi hiện có:

  • Giản đồ các bước: Một mảng các bước mới sẽ thay thế mảng đầu ra, cung cấp một dòng thời gian có cấu trúc của từng lượt tương tác.

Để tìm hiểu về thay đổi có thể gây lỗi gần đây nhất và biết cách di chuyển, hãy xem Hướng dẫn di chuyển đối với các thay đổi có thể gây lỗi (tháng 5 năm 2026).

Các nội dung cập nhật tiềm năng khác có thể bao gồm những thay đổi đối với giản đồ cho dữ liệu đầu vào và đầu ra, chữ ký phương thức SDK và cấu trúc đối tượng, hành vi của một số tính năng cụ thể.

Đối với các khối lượng công việc sản xuất, bạn nên tiếp tục sử dụng API generateContent tiêu chuẩn. Đây vẫn là đường dẫn được đề xuất cho các hoạt động triển khai ổn định và chúng tôi sẽ tiếp tục tích cực phát triển cũng như duy trì đường dẫn này.

Phản hồi

Ý kiến phản hồi của bạn đóng vai trò quan trọng trong quá trình phát triển Interactions API. Chia sẻ ý kiến, báo cáo lỗi hoặc yêu cầu tính năng trên Diễn đàn cộng đồng nhà phát triển AI của Google.

Bước tiếp theo