ai

使用 ADK 与全新 Interactions API 构建代理

发布: (2025年12月12日 GMT+8 01:17)
6 min read
原文: Google Developers Blog

Source: Google Developers Blog

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

对于已经在使用 Agent Development Kit (ADK) 和 Agent2Agent (A2A) 协议的开发者来说，关键问题是这个新 API 如何融入现有生态系统。Interactions API 既可以作为 generateContent 推理端点的替代方案，也可以作为一种强大的原语，在现有代理框架内部使用。

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

当你使用 ADK (Agent Development Kit) 构建代理时，需要一个 LLM（如 Gemini）来生成思考、计划、工具调用和响应。过去这通过 generateContent 完成。新的 Interactions API 为复杂的状态管理提供了原生接口，使 ADK 代理能够将对话历史和推理循环卸载到服务器端。

为什么要切换？

  • 统一模型与代理访问 – 同一端点既可用于标准模型（model="gemini-3-pro-preview"）也可用于内置 Gemini 代理（agent="deep-research-pro-preview-12-2025"）。
  • 简化状态管理 – 可选地使用 previous_interaction_id 卸载对话历史，减少 ADK 代理中的样板代码。
  • 后台执行 – 设置 background=True 可立即收到交互 ID，让服务器异步运行长时间任务。
  • 原生思考处理 – API 将“思考”与最终响应分离，便于更高效地处理推理链。

使用方式

与其管理原始消息列表并发送到 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",
        # Enable Interactions API
        use_interactions_api=True,
    ),
    name="interactions_test_agent",
    tools=[
        # Converted Google Search to a function tool
        GoogleSearchTool(bypass_multi_tools_limit=True),
        get_current_weather,
    ],
)

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

这种模式让你在 ADK 中保持控制流和路由逻辑，同时将上下文管理和推理状态的重活交给 Interactions API。可以把 API 内部的循环视为 内层循环，把代理代码中的循环视为 外层循环，从而对两者都有更好的控制。

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

Agent2Agent (A2A) 协议的互操作性在你希望让已有的 A2A 客户端或代理调用全新的 Gemini Deep Research Agent 时尤为突出。过去，集成第三方 API 需要自定义包装器。使用新的 InteractionsApiTransport，A2A 接口直接映射到 Interactions API，使你能够把 Interactions 端点当作普通的远程 A2A 代理。

桥接工作原理

InteractionsApiTransport 层将 A2A 调用转换为 Interactions API 调用：

  • A2A SendMessage → Interactions create
  • A2A Task → Interaction ID
  • A2A TaskStatus → Interaction Status（例如，IN_PROGRESS 映射为 TASK_STATE_WORKING）

注意： 目前尚不支持 A2A 推送通知、扩展以及 Interactions API 回调。

代码示例：透明集成

配置你的 A2A 客户端工厂以使用新传输层，并创建指向目标模型或代理的 AgentCard。

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

# 1. Configure the factory to support Interactions API
client_config = ClientConfig()
client_factory = ClientFactory(client_config)

# Setup the transport (handles API keys and auth transparently)
InteractionsApiTransport.setup(client_factory)

# 2. Create an AgentCard for the Deep Research agent
card = InteractionsApiTransport.make_card(
    url="https://generativelanguage.googleapis.com",
    agent="deep-research-pro-preview-12-2025"
)

# 2a. Or interact directly with a Gemini model
card = InteractionsApiTransport.make_card(
    url="https://generativelanguage.googleapis.com",
    model="gemini-3-pro-preview",
    request_opts={
        "generation_config": {"thinking_summaries": "auto"}
    }
)

# 3. Create a regular A2A client
client = client_factory.create(card)

# 4. Use it exactly like any other A2A agent
async for event in client.send_message(
    new_text_message("Research the history of Google TPUs")
):
    # The transport converts Interactions API 'Thoughts' and 'Content'
    # into standard A2A Task events.
    print(event)

为什么重要

  • 无需学习新 SDK – 你的 A2A 客户端代码保持不变。
  • 流式支持 – 传输层映射流式事件，提供代理的实时更新。
  • 配置携带 – A2A 扩展让你可以在 AgentCard 中传入特定设置（如 thinking_summaries），而不会破坏协议。

结论

Gemini Interactions API 在 AI 通信模型上迈出了重要一步。无论是使用 ADK 从零构建自定义代理，还是通过 A2A 将现有代理互联，这些新能力已经可以今天就开始探索。

Back to Blog

相关文章

阅读更多 »