Using the API Server in Google ADK

Learn how to start and use the API server in Google ADK to expose your agents through a REST API for programmatic testing and integration.

Posted on: 2026-03-04 by AI Assistant

Before deploying an AI agent built with the Google Agent Development Kit (ADK), it is crucial to thoroughly test it to ensure it behaves as intended. The ADK provides a built-in API server that allows you to expose your agents through a REST API. This makes it incredibly easy to perform programmatic testing and seamless integration with other systems.

The API server is supported across multiple languages in the ADK, including Python, TypeScript, Go, and Java.

Starting the API Server

Launching the API server varies slightly depending on your language of choice. Below are the commands to get the server running locally.

Python

adk api_server

Running these commands will launch a local web server (by default on http://localhost:8000 for Python. Once started, you can run curl commands or send API requests directly to your agent.

Testing Locally

Local testing involves three main steps: launching the local web server, creating a session, and sending queries to your agent.

1. Check Your Directory

Ensure you are in the correct working directory. For TypeScript projects, for example, you should be inside the specific agent project directory:

parent_folder/
└── my_sample_agent/  <-- Run commands from here
    └── agent.ts

2. Launch the Server

Run the language-specific command provided above. Once successful, you will see output indicating the server is running. For instance, in Python, you might see:

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://localhost:8000 (Press CTRL+C to quit)

In TypeScript, you’ll see a formatted block:

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+

3. Send Requests

With the server running, your agent is now accessible via a REST API. You can begin sending HTTP requests to test its capabilities.

Create a New Session

First, create a session for your interaction. Replace my_sample_agent with your agent folder name:

curl -X POST http://localhost:8000/apps/my_sample_agent/users/u_123/sessions/s_123 \
  -H "Content-Type: application/json" \
  -d '{"key1": "value1", "key2": 42}'

Send a Query

You can send queries via the /run route (returns all events at once) or /run_sse (streams events).

Using /run:

curl -X POST http://localhost:8000/run \
-H "Content-Type: application/json" \
-d '{
"appName": "my_sample_agent",
"userId": "u_123",
"sessionId": "s_123",
"newMessage": {
    "role": "user",
    "parts": [{
    "text": "Hey whats the weather in new york today"
    }]
}
}'

Using /run_sse (Streaming): To receive updates as they happen, use the streaming endpoint:

curl -X POST http://localhost:8000/run_sse \
-H "Content-Type: application/json" \
-d '{
"appName": "my_sample_agent",
"userId": "u_123",
"sessionId": "s_123",
"newMessage": {
    "role": "user",
    "parts": [{
    "text": "Hey whats the weather in new york today"
    }]
},
"streaming": true
}'

For more advanced usage, debugging, and interactive API documentation, you can refer to the full ADK API Server Guide provided in the official documentation.