Section 4: ADK Execution Methods

Building a powerful agent is only half the battle; running it in the right context is the other half. Whether you need a visual interface for debugging, a REST API for your frontend application, or a raw Python script for custom automation, the Agent Development Kit (ADK) has you covered.

In this tutorial, we will explore the four interaction methods provided by the ADK framework. By the end of this section, you will know exactly which runtime environment suits your specific deployment needs.

Bestseller

Master Google ADK - Agent Development Kit

Build Multi Agent Systems | Mac, Windows, Ubuntu | Deploy to Google Cloud | Free Gemini Key

★ 4.4👥 470+

View on Udemy

Overview

The ADK provides flexibility in how you interact with your agents. Depending on your stage of development, you can choose from the following:

Interaction Method	Best For	Description
ADK Web	Quick Demos & Debugging	Launches a browser-based UI to chat with your agent and visualize traces.
ADK API Server	REST Automation	Exposes your agent via HTTP endpoints, perfect for connecting to custom frontends.
Programmatic Python	Full Control	Allows you to invoke the agent directly via Python code for custom logic and session management.
ADK CLI Run	Fast Testing	Runs the agent directly in your terminal without writing extra wrapper code.

---

Method 1: The Web Playground

The ADK Web interface is the most user-friendly way to interact with your agents. It provides a chat interface, visualizations for agent thoughts, and tools for manual debugging. We used this method extensively in previous sections.

How to Run

Navigate to your project root where your agents folder is located and run:

adk web ./agents

Features

• Visual Interface: Select specific agents from the sidebar.
• Tracing: View the internal thought process, function calls, and state changes of your agent.
• Hot Reloading: Useful for iterating on agent logic and seeing results immediately in the browser.

---

Method 2: The API Server

If you are building a production application, you likely need to connect your agent to a frontend (like React or a mobile app). The ADK API Server spins up a FastAPI-based backend that exposes your agent via REST endpoints.

How to Run

Start the server pointing to your agents directory:

adk api_server ./agents

This starts a server at http://localhost:8000.

Interaction via HTTP

Once running, the server doesn't provide a UI. Instead, you communicate with it via HTTP requests. The endpoints handle user identification, session management, and message passing.

Here is an example of how to invoke the agent using curl:

curl -X POST http://localhost:8000/run \
  -H "Content-Type: application/json" \
  -d '{
    "appName": "root_website_builder",
    "userId": "u_123",
    "sessionId": "s_123",
    "newMessage": {
      "role": "user",
      "text": "Design a login page with Google sign-in"
    }
  }'

Key Parameters

• appName: Matches the directory name of your agent (e.g., root_website_builder).
• sessionId: A unique identifier for the conversation context.
• newMessage: The payload containing the user's input.

---

Method 3: The Command Line Interface (CLI)

For the fastest feedback loop without any setup overhead, use the ADK CLI Run command. This runs the agent directly in your terminal process. It's excellent for "sanity checks" or one-off runs.

How to Run

Simply point the run command to specific agent folder you want to execute:

adk run agents/root_website_builder

Features

• Zero Setup: No need to configure a server or write a runner script.
• Interactive Mode: It automatically provides a standard input prompt (Enter your query:) for you to type messages.
• Direct Logging: You see the raw text output and logs directly in your standard output (stdout).

---

Method 4: Programmatic Python Execution

For advanced use cases—such as building complex workflows, custom session storage (like Redis), or integrating the agent into a larger Python application—you should run the agent programmatically.

This method requires writing a Python script (often called agent_runner.py) that uses the ADK's Runner class.

The Runner Pattern

To run an agent manually, you need to set up three main components:

1. The Agent: Import your agent object.
2. Session Service: A service to store chat history (e.g., InMemorySessionService).
3. The Runner: The engine that executes the agent logic.

Implementation Example

Create a file named agent_runner.py:

agent_runner.py

import asyncio
from google.genai.types import Content, Part
# Import the ADK components
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
# Import your specific agent
from agents.root_website_builder.agent import root_agent

async def chat_loop():
    # 1. Setup Session Service
    session_service = InMemorySessionService()
    
    # 2. Create a Session
    session = await session_service.create_session(
        app_name="website_builder_app",
        user_id="user_123",
        session_id="session_loop_1"
    )

    # 3. Initialize the Runner
    runner = Runner(
        agent=root_agent,
        app_name="website_builder_app",
        session_service=session_service
    )

    print("Agent Chat Started. Type 'quit' to exit.")

    while True:
        user_query = input("Enter your query: ")
        if user_query.lower() in ["quit", "exit"]:
            break

        # 4. Construct the Message
        new_message = Content(role="user", parts=[Part(text=user_query)])

        # 5. Run the Agent (Async)
        # The runner yields events as the agent thinks and acts
        async for event in runner.run_async(
            user_id="user_123",
            session_id="session_loop_1",
            new_message=new_message
        ):
            # Check if this event contains the final text response
            if event.is_final_response():
                print(f"Agent Response: {event.content.parts[0].text}")
                break

if __name__ == "__main__":
    asyncio.run(chat_loop())

Running the Script

Execute this script using uv or standard python:

uv run python3 -m agent_runner

Why use this method?

This method gives you granular control. You can intercept every single event (thought process, function call, tool output) emitted by the agent and decide exactly how to display or log it.

---

What's Next?

Now that you have mastered the four ways to RUN your agents, we will move on to one of the most powerful features of modern AI systems: The Model Context Protocol.

In the next section, we will combine ADK with MCP to create a universal client that can connect to both local tools and remote services seamlessly.

Go to Section 5: Build Universal MCP Client →

Bestseller

Master Google ADK - Agent Development Kit

Build Multi Agent Systems | Mac, Windows, Ubuntu | Deploy to Google Cloud | Free Gemini Key

★ 4.4👥 470+

View on Udemy