Interactions API

Interactions API là tiêu chuẩn mới được đề xuất để xây dựng bằng Gemini. API này được tối ưu hoá cho quy trình công việc theo 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 phương thức, nhiều lượt. 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 luồng nhiều lượt thông qua previous_interaction_id. Máy chủ bật trạng thái theo mặc định (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á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à kết xuất giao diện người dùng cho các sự kiện trung gian (như ý tưởng hoặc tiện ích tìm kiếm).
  • Được xây dựng cho quy trình công việc theo tác nhân: Hỗ trợ gốc cho việc sử dụng công cụ nhiều bước, điều phối và các luồng suy luận phức tạp thông qua các bước thực thi được nhập.
  • Tác vụ dài hạn và tác vụ ở chế độ nền: Hỗ trợ chuyển 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à khả năng mới: Trong tương lai, các mô hình mới ngoài họ mô hình chính, cùng với các công cụ và khả năng của tác nhân AI 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 theo 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 chức năng 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 Gemini Docs MCP và cài đặt kỹ năng gemini-interactions-api để cấp cho trợ lý của bạn 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 có một chức năng tích hợp hiện có, 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 với 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 tính năng cụ thể của Interactions API thông qua các hướng dẫn này. Bạn có thể sử 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 đại diện cho một lượt hoàn chỉnh trong một cuộc trò chuyện hoặc tác vụ. Đây là bản ghi phiên, chứa toàn bộ nhật ký của một lượt 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 ý tưởng 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 (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 cho toàn bộ bối cảnh, mặc dù phản hồi interactions.create chỉ trả về các bước do mô hình tạo.

Khi bạn gọi interactions.create, bạn đang tạo một tài nguyên Interaction mới.

Truy cập vào đầu ra bằng các thuộc tính tiện lợi của SDK

Mặc dù Interactions API trả về một dòng thời gian có cấu trúc của các bước thực thi (chẳng hạn như ý tưởng, truy vấn tìm kiếm và lệnh gọi hàm), nhưng bạn không cần phải duyệt qua các bước theo cách thủ công để nhận được phản hồi cuối cùng của mô hình.

SDK Google GenAI cung cấp các thuộc tính tiện lợi trực tiếp trên đối tượng Interaction được trả về để truy cập vào đầu ra cho các phương thức khác nhau:

Thuộc tính tiện lợi của SDK Loại trả về Mô tả
interaction.output_text Chuỗi Trả về các khối văn bản cuối cùng trong phản hồi của mô hình. Nếu phản hồi được chia thành nhiều khối TextContent liên tiếp, thì phản hồi sẽ tự động kết hợp các khối đó. Phản hồi này không bao gồm các khối văn bản trước đó được phân tách bằng nội dung không phải văn bản (chẳng hạn như ý tưởng, hình ảnh, âm thanh hoặc lệnh gọi công cụ). Đối với các phản hồi phức tạp hoặc xen kẽ nhiều phương thức, bạn phải lặp lại steps theo cách thủ công.
interaction.output_image ImageContent hoặc None Trả về khối hình ảnh cuối cùng do mô hình tạo trong yêu cầu hiện tại.
interaction.output_audio AudioContent hoặc None Trả về khối âm thanh cuối cùng do mô hình tạo trong yêu cầu hiện tại.

Đối với các trường hợp sử dụng nâng cao (chẳng hạn như kết xuất các quy trình tư duy trung gian, kiểm tra lệnh gọi công cụ từng bước hoặc gỡ lỗi), bạn vẫn có thể kiểm tra và duyệt qua dòng thời gian interaction.steps thô theo cách thủ công.

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 previous_interaction_id tham số để 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ỉ giữ lại nhật ký cuộc trò chuyện (dữ liệu đầu vào và đầu ra) bằng cách sử dụng previous_interaction_id. Các tham số khác là theo phạm vi tương tác và chỉ áp dụng cho lượt 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 bạn muốn áp dụng các tham số đó. Bạn có thể chọn 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 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 ở chế độ nền (sử dụng background=true) và mục đích quan sát.

  • Cấp trả phí: Hệ thống giữ lại các lượt tương tác trong 55 ngày.
  • Cấp 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ỳ lượt 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 lượt tương tác đã lưu trữ bất cứ lúc nào bằng phương thức xoá có trong Tài liệu tham khảo về API. Bạn chỉ có thể xoá các lượt tương tác nếu biết mã lượt 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ệ truy cập bộ nhớ đệm: 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 bộ nhớ đệm ngầm ẩn 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 của Tác nhân 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ô 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.5 Flash Mô hình gemini-3.5-flash
Gemini 3.1 Flash-Lite Mô hình gemini-3.1-flash-lite
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 Lyria 3 Clip Mô hình lyria-3-clip-preview
Bản xem trước Lyria 3 Pro Mô hình lyria-3-pro-preview
Bản xem trước Deep Research Tác nhân deep-research-pro-preview-12-2025
Bản xem trước Deep Research Tác nhân deep-research-preview-04-2026
Bản xem trước Deep Research Tác nhân deep-research-max-preview-04-2026

SDK

Bạn có thể sử dụng phiên bản mới nhất của SDK Google GenAI để 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ở lên.
  • 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 Beta: Interactions API đang ở giai đoạn 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.

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

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

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

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

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

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

Các bản cập nhật tiềm năng khác có thể bao gồm các thay đổi đối với lược đồ 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ụ thể của tính năng.

Đối với khối lượng công việc sản xuất, bạn nên tiếp tục sử dụng API tiêu chuẩn generateContent. Đâ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 và duy trì đường dẫn này.

Phản hồi

Ý kiến phản hồi của bạn rất quan trọng đối với việc phát triển Interactions API. Hãy chia sẻ ý tưởng, 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