Google ADK (Agent Development Kit)

View as Markdown

This guide shows how to integrate the Telcoflow SDK with the Google Agent Development Kit (ADK) for complex AI agent behavior, including multi-agent orchestration, long-term memory, and structured tools.

Overview

The integration bridges Telcoflow’s bidirectional audio stream with ADK’s Runner and LiveRequestQueue:

  • Caller audio -> ADK: Incoming phone audio is sent to the LiveRequestQueue as real-time input
  • ADK audio -> Caller: ADK events containing model audio are forwarded to the caller via send_audio()

Full Example

1import asyncio
2import os
3from google.adk.agents import Agent
4from google.adk.runners import Runner
5from google.adk.sessions import InMemorySessionService
6from google.adk.agents.live_request_queue import LiveRequestQueue
7from google.adk.agents.run_config import RunConfig, StreamingMode
8from google.genai import types
9from telcoflow_sdk import TelcoflowClient, TelcoflowClientConfig, ActiveCall
10import telcoflow_sdk.events as events
11
12agent = Agent(
13 name="telcoflow_agent",
14 model="gemini-2.5-flash-native-audio-preview-12-2025",
15 instruction="You are a helpful AI assistant talking over a phone call.",
16)
17session_service = InMemorySessionService()
18runner = Runner(
19 app_name="telcoflow_app", agent=agent, session_service=session_service
20)
21
22async def start_adk_session(call: ActiveCall):
23 await call.answer()
24
25 live_request_queue = LiveRequestQueue()
26
27 async def stream_to_adk():
28 async for audio_chunk in call.audio_stream():
29 audio_blob = types.Blob(
30 data=audio_chunk, mime_type="audio/pcm;rate=24000"
31 )
32 live_request_queue.send_realtime(audio_blob)
33
34 async def receive_from_adk():
35 run_config = RunConfig(
36 streaming_mode=StreamingMode.BIDI,
37 response_modalities=["AUDIO"],
38 )
39 async for event in runner.run_live(
40 user_id="default_user",
41 session_id=call.call_id,
42 live_request_queue=live_request_queue,
43 run_config=run_config,
44 ):
45 if event.interrupted:
46 await call.clear_send_audio_buffer()
47
48 if event.content and event.content.parts[0].inline_data:
49 await call.send_audio(
50 event.content.parts[0].inline_data.data
51 )
52
53 await asyncio.gather(stream_to_adk(), receive_from_adk())
54
55async def main():
56 config = TelcoflowClientConfig.sandbox(
57 api_key=os.getenv("WSS_API_KEY"),
58 connector_uuid=os.getenv("WSS_CONNECTOR_UUID"),
59 sample_rate=24000,
60 )
61
62 async with TelcoflowClient(config) as client:
63 @client.on(events.INCOMING_CALL)
64 async def handle_call(call: ActiveCall):
65 await start_adk_session(call)
66
67 await client.run_forever()
68
69if __name__ == "__main__":
70 asyncio.run(main())

How It Works

ADK Components

  • Agent - Defines the AI model and system instruction
  • Runner - Orchestrates agent execution and session management
  • InMemorySessionService - Stores session state (swap for a persistent store in production)
  • LiveRequestQueue - Accepts real-time audio input and feeds it to the runner

Stream to ADK

The stream_to_adk() coroutine reads audio chunks from call.audio_stream(), wraps them as types.Blob objects, and sends them to the LiveRequestQueue using send_realtime().

Receive from ADK

The receive_from_adk() coroutine runs runner.run_live() with StreamingMode.BIDI and response_modalities=["AUDIO"]. For each event:

  • Interruption: When event.interrupted is True, clear_send_audio_buffer() is called to stop queued audio
  • Model audio: When event.content contains inline_data, the raw audio is forwarded to the caller

Session Management

Each call gets its own session, keyed by call.call_id. This allows ADK to maintain conversation context within a single call. For cross-call memory, use a persistent session service.

When to Use ADK vs. GenAI SDK

CapabilityGenAI SDKADK
Simple voice AIYesYes
Multi-agent orchestrationNoYes
Structured tool callingLimitedYes
Session/memory managementManualBuilt-in
Complex agent workflowsNoYes

Use the GenAI SDK integration for straightforward voice AI. Use ADK when you need structured agents, tools, or multi-agent coordination.

Environment Variables

VariableDescription
GOOGLE_API_KEYGoogle API key with Gemini API access
WSS_API_KEYTelcoflow API key
WSS_CONNECTOR_UUIDTelcoflow connector UUID

Next Steps