使用 ADK 和全新的 Interactions API 构建代理

Source: Google Developers Blog

2025年12月11日

Source:

介绍

AI 开发的格局正从无状态的请求‑响应循环转向有状态的、多轮的代理工作流。随着 Interactions API 的 beta 版发布，Google 提供了一个专为这个新时代设计的统一接口——它既可以作为原始模型的入口，也可以作为完整托管的 Gemini Deep Research Agent 的单一网关。

对于已经在使用 Agent Development Kit (ADK) 和 Agent2Agent (A2A) 协议的开发者来说，关键问题是：

这个新 API 如何融入我现有的生态系统？

答案有两层含义。Interactions API 既可以作为现有 generateContent 推理端点的替代方案 也 可以作为一个强大的原语，在现有代理框架 内部 使用。

在本文中，我们将探讨两种主要的集成模式：

1. 为你的 ADK 代理提供动力 – 将 Interactions API 用作自定义代理的推理引擎。
2. 透明桥接 – 通过 Interactions API 与内置代理（例如 Gemini Deep Research Agent）以标准远程 A2A 代理的方式协作。

---

Source: …

模式 1：使用 ADK 与 Interactions API 编写代理

当您使用 ADK（Agent Development Kit） 构建代理时，需要一个大语言模型（例如 Gemini）来生成思考、计划、工具调用和响应。以前这由 generateContent 处理。

全新的 Interactions API 提供了一个原生接口，用于复杂的状态管理。通过将推理调用升级到此端点，ADK 代理即可获得专为代理循环设计的功能。

为什么要切换？

使用方式

不必再管理原始消息列表并将其发送到 generateContent，您的 ADK 代理可以保留指向服务器端状态的轻量指针。

from google.adk.agents.llm_agent import Agent
from google.adk.models.google_llm import Gemini
from google.adk.tools.google_search_tool import GoogleSearchTool

root_agent = Agent(
    model=Gemini(
        model="gemini-2.5-flash",
        # 启用 Interactions API
        use_interactions_api=True,
    ),
    name="interactions_test_agent",
    tools=[
        # 将 Google Search 转换为函数工具
        GoogleSearchTool(bypass_multi_tools_limit=True),
        get_current_weather,
    ],
)

有关逐步说明，请参阅完整的 ADK 示例（使用 Interactions API）。

此模式让您在 ADK 中保留控制流和路由逻辑，同时将上下文管理和推理状态的繁重工作交给 Interactions API。可以将其视为 内部循环（由 API 处理）和 外部循环（您的代理代码）。新 API 为两者提供了更细粒度的控制。

模式 2：使用 Interactions API 代理作为远程 A2A 代理

这是 Agent‑to‑Agent (A2A) 协议互操作性大放异彩的地方。

如果你已经拥有一套 A2A 客户端或代理的生态系统，可能希望它们能够调用全新的 Gemini Deep Research Agent。过去，集成第三方 API 往往需要编写自定义的包装器或适配器。

借助全新的 InteractionsApiTransport，我们已经将 A2A 协议 的表面直接映射到 Interactions API 表面。它“会说” A2A，因此你可以把 Interactions API 端点当作另一个远程 A2A 代理。你的现有客户端无需知道它们正在与 Google 托管的代理通信；它们只会看到一个 AgentCard，并像往常一样发送消息。

桥接工作原理

InteractionsApiTransport 层将 A2A 概念转换为 Interactions API 概念：

注意： A2A 推送通知、A2A 扩展以及 Interactions API 回调在此映射中 尚未 支持。

代码示例：透明集成

from interactions_api_transport import InteractionsApiTransport
from a2a.client import ClientFactory, ClientConfig

# 1️⃣ 配置工厂以支持 Interactions API
client_config = ClientConfig()
client_factory = ClientFactory(client_config)

# 设置传输层（透明处理 API 密钥和身份验证）
InteractionsApiTransport.setup(client_factory)

# 2️⃣ 为 Deep Research 代理创建 AgentCard
# 此辅助函数会构建包含必要“走私”配置的卡片
card = InteractionsApiTransport.make_card(
    url="https://generativelanguage.googleapis.com",
    agent="deep-research-pro-preview-12-2025"
)

# 2a️⃣ 或直接与 Gemini 模型交互
card = InteractionsApiTransport.make_card(
    url="https://generativelanguage.googleapis.com",
    model="gemini-3-pro-preview",
    request_opts={
        "generation_config": {"thinking_summaries": "auto"}
    },
)

# 3️⃣ 创建普通的 A2A 客户端
client = client_factory.create(card)

# 4️⃣ 像使用任何其他 A2A 代理一样使用它
async for event in client.send_message(
    new_text_message("Research the history of Google TPUs")
):
    # 传输层将 Interactions API 的 “Thoughts” 与 “Content”
    # 转换为标准的 A2A Task 事件。
    print(event)

为什么这很重要

• 零 SDK 变动： 你的 A2A 客户端代码保持不变。
• 流式支持： 传输层映射流式事件，为你提供来自代理的实时更新。
• 配置走私： A2A 扩展让你可以在 AgentCard 中传递特定设置（例如 thinking_summaries），而不会破坏标准协议。

简而言之，Interactions API 对你的开发者体验是透明的，让你无需重构多代理系统即可立即使用 Deep Research 等强大工具。最棒的是？它就是这么好用。

结论

Gemini Interactions API 标志着在建模 AI 通信方面的重大进步。无论您是：

• 使用任何框架（例如 ADK）从头构建自定义代理
• 通过 A2A 将现有代理连接在一起

您现在拥有一套强大的新功能，今天即可探索。

将该 API 同时视为 卓越的推理引擎 以及 合规的远程代理，以最小的摩擦快速扩展您的代理网络的能力。

敬请关注——在接下来的几周内，将发布更多 ADK 和 A2A 资源，帮助开发者采用此 API。

今日开始

• 阅读 Gemini 交互 API 公告 和 文档。
• 阅读 Gemini 深度研究代理公告 和 文档。
• 查看 ADK 发布说明、ADK 文档 以及使用交互 API 的 ADK 示例。
• 探索使用交互 API 的 A2A 示例。