ADK와 새로운 Interactions API를 사용한 에이전트 구축

Source: Google Developers Blog

AI 개발의 풍경은 무상태 요청‑응답 사이클에서 상태를 유지하는 다중 턴 에이전트 워크플로우로 이동하고 있습니다. 베타 버전으로 출시된 Interactions API와 함께 Google은 이 새로운 시대를 위해 설계된 통합 인터페이스를 제공하며, 원시 모델과 완전 관리형 Gemini Deep Research Agent 모두에 대한 단일 진입점을 제공합니다.

이미 **Agent Development Kit (ADK)**와 Agent2Agent (A2A) 프로토콜을 사용하고 있는 개발자에게 핵심 질문은 이 새로운 API가 기존 생태계에 어떻게 들어맞는가 입니다. Interactions API는 generateContent 추론 엔드포인트의 대안이자 기존 에이전트 프레임워크 내부에서 사용할 수 있는 강력한 원시 기능으로 활용될 수 있습니다.

Pattern 1: ADK와 Interactions API로 에이전트 작성하기

ADK (Agent Development Kit)를 사용해 에이전트를 구축할 때, Gemini와 같은 LLM이 사고, 계획, 도구 호출 및 응답을 생성해야 합니다. 이전에는 이것을 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가 “thoughts”(사고)와 최종 응답을 구분해 추론 체인을 보다 효율적으로 처리할 수 있게 합니다.

구현 예시

원시 메시지 리스트를 관리하고 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 샘플 with Interactions API를 참고하세요.

이 패턴을 사용하면 ADK 내부에서 제어 흐름과 라우팅 로직을 유지하면서, 컨텍스트 관리와 추론 상태의 무거운 작업을 Interactions API에 위임할 수 있습니다. API 내부 루프와 에이전트 코드 외부 루프를 구분해 두어 양쪽을 보다 세밀하게 제어할 수 있습니다.

Pattern 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 으로 매핑)

Note: 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)을 프로토콜을 깨지 않고 전달할 수 있습니다.

Conclusion

Gemini Interactions API는 AI 커뮤니케이션 모델링에 있어 큰 도약을 의미합니다. ADK와 같은 프레임워크를 사용해 처음부터 맞춤형 에이전트를 구축하든, A2A를 통해 기존 에이전트를 연결하든, 오늘 바로 탐색할 수 있는 새로운 기능들이 준비되어 있습니다.