ADK와 새로운 Interactions API로 에이전트 구축

Source: Google Developers Blog

2025년 12월 11일

Source: https://example.com/your-original-article

소개

AI 개발 환경은 무상태 요청‑응답 사이클에서 상태를 유지하는 다중‑턴 에이전트 워크플로우로 전환하고 있습니다. **Interactions API**가 베타 출시되면서, 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) 로 에이전트를 구축할 때는 생각, 계획, 도구 호출 및 응답을 생성하기 위해 LLM(예: 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 샘플 with the Interactions API 를 참고하세요.

이 패턴을 사용하면 컨트롤 흐름과 라우팅 로직은 ADK 내부에 유지하면서, 컨텍스트 관리와 추론 상태의 무거운 작업은 Interactions API에 위임할 수 있습니다. 이를 내부 루프(API가 처리)와 외부 루프(에이전트 코드가 처리)로 생각하면 됩니다. 새로운 API는 두 루프 모두에 대해 더 세밀한 제어를 제공합니다.

Pattern 2: Using Interactions API Agents as Remote A2A Agents

이것은 Agent‑to‑Agent (A2A) 프로토콜의 상호 운용성이 빛을 발하는 부분입니다.

이미 A2A 클라이언트 또는 에이전트 생태계를 보유하고 있다면, 새로운 Gemini Deep Research Agent에 상담하도록 하고 싶을 수 있습니다. 과거에는 서드파티 API를 통합하려면 맞춤형 래퍼나 어댑터를 작성해야 했습니다.

새로운 **InteractionsApiTransport**를 사용하면 A2A 프로토콜 인터페이스를 Interactions API 인터페이스에 직접 매핑했습니다. 이것은 A2A를 “구사”하므로 Interactions API 엔드포인트를 또 다른 원격 A2A 에이전트처럼 취급할 수 있습니다. 기존 클라이언트는 Google이 호스팅하는 에이전트와 통신하고 있다는 사실을 알 필요가 없으며, 단지 AgentCard를 보고 평소처럼 메시지를 전송하면 됩니다.

How the Bridge Works

InteractionsApiTransport 레이어는 A2A 개념을 Interactions API 개념으로 변환합니다:

Note: A2A 푸시 알림, A2A 확장, 그리고 Interactions API 콜백은 현재 이 매핑에서 지원되지 않습니다.

Code Example: Transparent Integration

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)

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

# 2️⃣ Create an AgentCard for the Deep Research agent
# This helper builds the card with the necessary “smuggled” config
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)

Why This Matters

• Zero SDK churn: A2A 클라이언트 코드를 그대로 유지할 수 있습니다.
• Streaming support: 전송 계층이 스트리밍 이벤트를 매핑해 에이전트로부터 실시간 업데이트를 받을 수 있습니다.
• Configuration smuggling: A2A 확장을 활용해 AgentCard 안에 thinking_summaries와 같은 특정 설정을 표준 프로토콜을 깨뜨리지 않고 전달할 수 있습니다.

요약하면, Interactions API가 개발자 경험에 투명하게 작용하여 다중 에이전트 시스템을 리팩터링하지 않고도 Deep Research와 같은 강력한 도구에 즉시 접근할 수 있게 해 줍니다. 그리고 가장 좋은 점은? 그냥 작동한다는 것입니다.

결론

Gemini Interactions API는 AI 커뮤니케이션 모델링에서 큰 도약을 의미합니다. 다음 중 어느 경우이든:

• 어떤 프레임워크든 (예: ADK) 사용하여 처음부터 맞춤형 에이전트를 구축하기
• 기존 에이전트를 A2A를 통해 연결하기

이제 오늘 바로 탐색할 수 있는 강력한 새로운 기능 세트를 갖게되었습니다.

API를 우수한 추론 엔진 이자 준수하는 원격 에이전트 로 활용하여 최소한의 마찰로 에이전시 메쉬의 기능을 빠르게 확장하십시오.

계속 지켜보세요—다음 몇 주 안에 개발자들이 이 API를 채택할 수 있도록 돕는 더 많은 ADK 및 A2A 리소스가 공개될 예정입니다.

오늘 시작하기

• Gemini Interactions API에 대한 발표와 문서를 읽어보세요.
• Gemini Deep Research Agent에 대한 발표와 문서를 확인해 보세요.
• ADK 릴리스 노트, ADK 문서, 그리고 Interactions API를 활용한 ADK 샘플을 살펴보세요.
• Interactions API를 사용하는 A2A 샘플을 탐색해 보세요.