This page documents the user-facing interfaces for interacting with ADK agents, including the command-line interface (adk CLI), the development web UI, the FastAPI server architecture, and programmatic API endpoints. For information about deploying agents to production environments, see Deployment.
The ADK provides three primary interaction modes:
adk run, adk web, etc.)The ADK CLI is implemented as a Click command-line application with the main entry point at src/google/adk/cli/cli_tools_click.py124-128 All commands follow the pattern adk <command> [options] [arguments].
The following diagram maps CLI commands to their implementation functions:
Sources: src/google/adk/cli/cli_tools_click.py124-141 src/google/adk/cli/cli_tools_click.py424-516
All CLI commands that interact with agents support service URI flags for customizing backend services. These options are defined by the @adk_services_options() decorator:
| Option | Purpose | Default | Example Values |
|---|---|---|---|
--session_service_uri | Session storage backend | Per-agent .adk/session.db | memory://, sqlite:///path/to/db, agentengine://123 |
--artifact_service_uri | Artifact storage backend | .adk/artifacts/ | gs://bucket-name, file:///path, memory:// |
--memory_service_uri | Long-term memory backend | None (disabled) | rag://corpus-id, agentengine://123 |
Service URI Resolution Flow:
Sources: src/google/adk/cli/cli_tools_click.py370-421 src/google/adk/cli/utils/service_factory.py31-77
adk run CommandThe adk run command provides an interactive CLI for testing agents locally. It supports three execution modes:
1. Interactive Mode (default):
Creates a new session and enters an interactive loop where users type queries and receive responses. Type exit to quit.
2. Replay Mode:
Executes a sequence of queries from a JSON file with the structure:
3. Resume Mode:
Restores a previously saved session and allows continued interaction.
Session Persistence:
The --save_session flag saves the session state on exit:
Implementation Details:
The run_cli() function orchestrates the execution flow:
Sources: src/google/adk/cli/cli_tools_click.py424-516 src/google/adk/cli/cli.py130-264
adk web)The adk web command launches a FastAPI server with an embedded Angular-based development UI for visual agent interaction and debugging.
Common Options:
| Option | Description | Default |
|---|---|---|
--port | Server port | 8000 |
--host | Binding address | 127.0.0.1 |
--reload | Auto-reload on file changes | True |
--reload_agents | Live reload agents on code changes | False |
--trace_to_cloud | Enable Cloud Trace | False |
--otel_to_cloud | Export to GCP Observability | False |
--allow_origins | CORS origins | None |
--a2a | Enable A2A protocol | False |
--logo-text | Custom logo text | None |
--logo-image-url | Custom logo image | None |
--url_prefix | URL path prefix for reverse proxy | None |
Warning: The web UI has access to all agent data and should only be used in development environments (src/google/adk/cli/cli_tools_click.py112-115).
The development UI provides:
Static Assets Location:
The Angular application is served from the browser directory within the CLI package (src/google/adk/cli/fast_api.py201-205).
Sources: src/google/adk/cli/cli_tools_click.py1112-1162 src/google/adk/cli/fast_api.py72-391
The AdkWebServer class encapsulates all server functionality and service dependencies:
Key Responsibilities:
Runner instances per app name (src/google/adk/cli/adk_web_server.py509)Sources: src/google/adk/cli/adk_web_server.py444-511
The get_fast_api_app() function coordinates the initialization of all server components:
Sources: src/google/adk/cli/fast_api.py72-391 src/google/adk/cli/adk_web_server.py596-643
CORS origins can be specified using literal origins or regex patterns:
The _parse_cors_origins() function separates literal and regex patterns (src/google/adk/cli/adk_web_server.py110-136):
Sources: src/google/adk/cli/adk_web_server.py110-136 tests/unittests/cli/test_cors_regex.py
The FastAPI server exposes the following endpoint groups:
| Method | Path | Purpose | Request Body | Response |
|---|---|---|---|---|
| GET | /app/{app_name}/users/{user_id}/sessions | List sessions | - | ListSessionsResponse |
| POST | /app/{app_name}/users/{user_id}/sessions | Create session | CreateSessionRequest | Session |
| GET | /app/{app_name}/users/{user_id}/sessions/{session_id} | Get session | - | Session |
| DELETE | /app/{app_name}/users/{user_id}/sessions/{session_id} | Delete session | - | bool |
| PUT | /app/{app_name}/users/{user_id}/sessions/{session_id} | Update session state | UpdateSessionRequest | Session |
| POST | /app/{app_name}/users/{user_id}/sessions/{session_id}/rewind | Rewind session | {"rewind_before_invocation_id": str} | bool |
Sources: src/google/adk/cli/adk_web_server.py667-803
HTTP Streaming:
POST /app/{app_name}/users/{user_id}/run
Content-Type: application/json
{
"session_id": "session-123",
"new_message": {
"role": "user",
"parts": [{"text": "Hello"}]
},
"streaming": true
}
WebSocket Streaming:
WS /app/{app_name}/users/{user_id}/run_ws?session_id=session-123
The WebSocket endpoint supports bidirectional communication with the following message types:
Sources: src/google/adk/cli/adk_web_server.py805-882 src/google/adk/cli/adk_web_server.py884-975
For real-time audio/video streaming with Gemini Live:
WS /app/{app_name}/users/{user_id}/run_live?session_id=session-123
The client can send:
The server streams back:
Sources: src/google/adk/cli/adk_web_server.py977-1107
| Method | Path | Purpose |
|---|---|---|
| GET | /app/{app_name}/users/{user_id}/sessions/{session_id}/artifacts | List artifacts |
| GET | /app/{app_name}/users/{user_id}/sessions/{session_id}/artifacts/{filename} | Get artifact |
| POST | /app/{app_name}/users/{user_id}/sessions/{session_id}/artifacts/{filename} | Save artifact |
| GET | /app/{app_name}/users/{user_id}/sessions/{session_id}/artifacts/{filename}/versions | List versions |
| GET | /app/{app_name}/users/{user_id}/sessions/{session_id}/artifacts/{filename}/versions/{version} | Get specific version |
| DELETE | /app/{app_name}/users/{user_id}/sessions/{session_id}/artifacts/{filename} | Delete artifact |
User-scoped artifacts (not tied to a session) use the path pattern:
/app/{app_name}/users/{user_id}/artifacts/{filename}
Sources: src/google/adk/cli/adk_web_server.py1109-1278
| Method | Path | Purpose |
|---|---|---|
| GET | /app/{app_name}/eval_sets | List eval sets |
| POST | /app/{app_name}/eval_sets | Create eval set |
| GET | /app/{app_name}/eval_sets/{eval_set_id} | Get eval set |
| POST | /app/{app_name}/eval_sets/{eval_set_id}/eval_cases | Add eval case |
| POST | /app/{app_name}/eval_sets/{eval_set_id}/sessions | Add session to eval set |
| POST | /app/{app_name}/eval_sets/{eval_set_id}/run | Run evaluation |
| GET | /app/{app_name}/eval_results | List eval results |
| GET | /app/{app_name}/eval_results/{eval_result_id} | Get eval result |
Evaluation Execution Flow:
Sources: src/google/adk/cli/adk_web_server.py1280-1545
| Method | Path | Purpose | Response |
|---|---|---|---|
| GET | /apps | List available agents | ListAppsResponse with app metadata |
| GET | /apps/{app_name}/graph | Get agent hierarchy graph | DOT format graph |
The graph endpoint generates a GraphViz diagram of the agent's sub-agent structure using src/google/adk/cli/agent_graph.py
Sources: src/google/adk/cli/adk_web_server.py1547-1582
When the --a2a flag is enabled, the server automatically discovers and exposes agents with an agent.json file via the A2A (Agent-to-Agent) protocol.
The server scans the agents directory for folders containing agent.json:
For each A2A-enabled agent, the following routes are created:
| Path | Method | Purpose |
|---|---|---|
/a2a/{app_name}/.well-known/agent.json | GET | Agent Card (capabilities) |
/a2a/{app_name} | POST | Execute agent (task creation) |
/a2a/{app_name} | SSE | Stream task events |
Agent Card Format:
Implementation:
The A2A integration uses the a2a-sdk library and A2aAgentExecutor to convert between ADK events and A2A protocol messages:
Sources: src/google/adk/cli/fast_api.py323-390
The server supports exporting telemetry data to Google Cloud Observability services:
OTEL Environment Variables:
The server also respects standard OpenTelemetry environment variables:
OTEL_EXPORTER_OTLP_ENDPOINTOTEL_EXPORTER_OTLP_TRACES_ENDPOINTOTEL_EXPORTER_OTLP_METRICS_ENDPOINTOTEL_EXPORTER_OTLP_LOGS_ENDPOINTTelemetry Setup Flow:
Custom Span Exporters:
The server registers internal span exporters for the web UI:
ApiServerSpanExporter - Captures tool execution spans by event ID (src/google/adk/cli/adk_web_server.py138-161)InMemoryExporter - Stores spans for session-based retrieval (src/google/adk/cli/adk_web_server.py163-199)Sources: src/google/adk/cli/adk_web_server.py339-442 src/google/adk/telemetry/google_cloud.py44-94 src/google/adk/telemetry/setup.py48-151
All CLI commands support logging configuration:
Available log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
Sources: src/google/adk/cli/cli_tools_click.py1014-1025 src/google/adk/cli/cli_tools_click.py1096-1103
When deploying behind a reverse proxy or API gateway, use --url_prefix:
This ensures generated URLs and redirects work correctly. The prefix must start with / if provided.
Runtime Config Update:
The web UI's runtime config is automatically updated with the backendUrl (src/google/adk/cli/adk_web_server.py597-643).
Sources: src/google/adk/cli/cli_tools_click.py1084-1093 src/google/adk/cli/adk_web_server.py618
Enable automatic agent reloading on file changes:
The AgentChangeEventHandler watches the agents directory using watchdog and triggers runner cleanup when changes are detected (src/google/adk/cli/fast_api.py180-198).
Sources: src/google/adk/cli/cli_tools_click.py1059-1064 src/google/adk/cli/fast_api.py180-198
Brand the web UI with custom logos:
Both options must be provided together. The configuration is written to runtime-config.json in the web assets directory.
Sources: src/google/adk/cli/cli_tools_click.py921-946 src/google/adk/cli/adk_web_server.py620-632
Refresh this wiki
This wiki was recently refreshed. Please wait 5 days to refresh again.