Explain the runtime architecture of Google ADK (Runner, Session, Events, InvocationContext) with flow diagrams.

Google ADK Runtime Architecture

The ADK runtime is the execution engine that manages the event loop, sessions, and agent invocations.

Core Runtime Components

Component Details

Event Loop Flow

Invocation Context

The

InvocationContext

pythonCopy
# InvocationContext provides:
# - session: current Session object
# - agent: the executing agent
# - run_config: runtime configuration
# - invocation_id: unique ID for this invocation

class InvocationContext:
    session: Session           # current session
    agent: BaseAgent           # executing agent
    run_config: RunConfig      # runtime config
    invocation_id: str         # unique invocation ID
    branch: str               # branch identifier (for parallel)

Creating a Runner

pythonCopy
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService

runner = Runner(
    agent=root_agent,
    app_name="my_app",
    session_service=InMemorySessionService(),
)

# Run the agent
async def main():
    session = await runner.session_service.create_session(
        app_name="my_app",
        user_id="user-123",
    )

    async for event in runner.run_async(
        user_id="user-123",
        session_id=session.id,
        new_message="What is RAG?",
    ):
        if event.content and event.content.parts:
            print(event.content.parts[0].text)

Events

Events are the chronological record of everything that happens:

pythonCopy
# Event types
# - Content: user/agent messages
# - FunctionCall: tool invocations
# - FunctionResponse: tool results
# - EventActions: control flow signals

# Each event contains:
event.author      # "user" or agent name
event.content     # message content (Parts)
event.actions     # EventActions (escalate, transfer, etc.)
event.invocation_id  # which invocation produced this

RunConfig

pythonCopy
from google.adk.runners import RunConfig

config = RunConfig(
    max_llm_calls=20,          # prevent infinite loops
    speech_config=None,         # audio config
    response_modalities=None,   # text, audio, video
    save_input_blobs_as_artifacts=False,
    support_cfc=False,          # client-side function calling
    streaming_mode="SSE",       # or "NONE"
    output_audio_transcription=False,
)

async for event in runner.run_async(
    user_id="user-1",
    session_id=session.id,
    new_message="Hello",
    run_config=config,
):
    print(event)

Learn more at Runtime and Sessions.