Skip to content

Use API Server

使用 API 服务器

Supported in ADKPython v0.1.0TypeScript v0.2.0Go v0.1.0Java v0.1.0

Before you deploy your agent, you should test it to ensure that it is working as intended. Use the API server in ADK to expose your agents through a REST API for programmatic testing and integration.

在部署智能体之前,您应该测试它以确保其按预期工作。使用 ADK 中的 API 服务器通过 REST API 公开您的智能体,以便进行程序化测试和集成。

ADK API Server

Start API server

启动 API 服务器

Use the following command to run your agent in an ADK API server:

使用以下命令在 ADK API 服务器中运行您的智能体:

adk api_server

npx adk api_server

go run agent.go web api

Make sure to update the port number. 确保更新端口号。

With Maven, compile and run the ADK web server: 使用 Maven,编译并运行 ADK Web 服务器: 

mvn compile exec:java \
 -Dexec.args="--adk.agents.source-dir=src/main/java/agents --server.port=8080"

With Gradle, your build.gradle or build.gradle.kts build file should have the following Java plugin in its plugins section: 使用 Gradle,您的 build.gradle 或 build.gradle.kts 构建文件在其 plugins 部分应包含以下 Java 插件:

plugins {
    id('java')
    // other plugins
    // 其他插件
}
Then, elsewhere in the build file, at the top-level, create a new task: 然后,在构建文件的其他位置,在顶层创建一个新任务:

tasks.register('runADKWebServer', JavaExec) {
    dependsOn classes
    classpath = sourceSets.main.runtimeClasspath
    mainClass = 'com.google.adk.web.AdkWebServer'
    args '--adk.agents.source-dir=src/main/java/agents', '--server.port=8080'
}

Finally, on the command-line, run the following command: 最后,在命令行上,运行以下命令: 

gradle runADKWebServer

In Java, both the Dev UI and API server are bundled together. 在 Java 中,开发 UI 和 API 服务器捆绑在一起。

This command will launch a local web server, where you can run cURL commands or send API requests to test your agent. By default, the server runs on http://localhost:8000.

此命令将启动一个本地 Web 服务器,您可以在其中运行 cURL 命令或发送 API 请求来测试您的智能体。默认情况下,服务器运行在 http://localhost:8000 上。

Advanced Usage and Debugging

For a complete reference on all available endpoints, request/response formats, and tips for debugging (including how to use the interactive API documentation), see the ADK API Server Guide below.

有关所有可用端点、请求/响应格式和调试提示(包括如何使用交互式 API 文档)的完整参考,请参阅下面的 ADK API 服务器指南。

Test locally

本地测试

Testing locally involves launching a local web server, creating a session, and sending queries to your agent. First, ensure you are in the correct working directory.

本地测试包括启动本地 Web 服务器、创建会话以及向智能体发送查询。首先,确保您处于正确的工作目录中。

For TypeScript, you should be inside the agent project directory itself.

对于 TypeScript,您应该位于智能体项目目录本身内部。

parent_folder/
└── my_sample_agent/  <-- For TypeScript, run commands from here
    └── agent.py (or Agent.java or agent.ts)

Launch Local Server 启动本地服务器

Next, launch the local server using the commands listed above.

接下来,使用上面列出的命令启动本地服务器。

The output should appear similar to:

输出应该类似于:

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)

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

2025-05-13T23:32:08.972-06:00  INFO 37864 --- [ebServer.main()] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port 8080 (http) with context path '/'
2025-05-13T23:32:08.980-06:00  INFO 37864 --- [ebServer.main()] com.google.adk.web.AdkWebServer          : Started AdkWebServer in 1.15 seconds (process running for 2.877)
2025-05-13T23:32:08.981-06:00  INFO 37864 --- [ebServer.main()] com.google.adk.web.AdkWebServer          : AdkWebServer application started successfully.

Your server is now running locally. Ensure you use the correct port number in all subsequent commands.

您的服务器现在正在本地运行。确保在所有后续命令中使用正确的端口号。

Create a new session 创建新会话

With the API server still running, open a new terminal window or tab and create a new session with the agent using:

在 API 服务器仍在运行的情况下,打开一个新的终端窗口或选项卡,使用以下命令创建一个新会话:

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}'

Let's break down what's happening:

让我们分解一下发生了什么:

  • http://localhost:8000/apps/my_sample_agent/users/u_123/sessions/s_123: This creates a new session for your agent my_sample_agent, which is the name of the agent folder, for a user ID (u_123) and for a session ID (s_123). You can replace my_sample_agent with the name of your agent folder. You can replace u_123 with a specific user ID, and s_123 with a specific session ID. 这会为您的智能体 my_sample_agent(即智能体文件夹的名称)创建一个新会话,用于用户 ID(u_123)和会话 ID(s_123)。您可以将 my_sample_agent 替换为智能体文件夹的名称。您可以将 u_123 替换为特定的用户 ID,将 s_123 替换为特定的会话 ID。
  • {"key1": "value1", "key2": 42}: This is optional. You can use this to customize the agent's pre-existing state (dict) when creating the session. 这是可选的。您可以使用它在创建会话时自定义智能体的预先存在的状态(dict)。

This should return the session information if it was created successfully. The output should appear similar to:

如果创建成功,这应该返回会话信息。输出应该类似于:

{"id":"s_123","appName":"my_sample_agent","userId":"u_123","state":{"key1":"value1","key2":42},"events":[],"lastUpdateTime":1743711430.022186}

Info

You cannot create multiple sessions with exactly the same user ID and session ID. If you try to, you may see a response, like: {"detail":"Session already exists: s_123"}. To fix this, you can either delete that session (e.g.,s_123`), or choose a different session ID.

您不能创建具有完全相同的用户 ID 和会话 ID 的多个会话。如果您尝试这样做,您可能会看到响应,如:{"detail":"Session already exists: s_123"}。要解决此问题,您可以删除该会话(例如,s_123),或选择不同的会话 ID。

Send a query 发送查询

There are two ways to send queries via POST to your agent, via /run or /run_sse routes.

有两种方式通过 POST 向您的智能体发送查询,通过 /run 或 /run_sse 路由。

  • POST http://localhost:8000/run: collects all events as a list and returns the list all at once. Suitable for most users (if you are unsure, we recommend using this one). 将所有事件收集为列表并一次性返回列表。适合大多数用户(如果您不确定,我们建议使用此选项)。
  • POST http://localhost:8000/run_sse: returns as Server-Sent-Events, which is a stream of event objects. Suitable for those who want to be notified as soon as an event is available. With /run_sse, you can also set streaming to true to enable token-level streaming. 作为服务器发送事件返回,这是事件对象的流。适合那些希望在事件可用时立即收到通知的人。使用 /run_sse,您还可以将 streaming 设置为 true 以启用令牌级流式传输。

Using /run 使用 /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"
    }]
}'
}'

In TypeScript, currently only camelCase field names are supported (e.g. appName, userId, sessionId, etc.).

在 TypeScript 中,目前仅支持 camelCase 字段名(例如 appName、userId、sessionId 等)。

If using /run, you will see the full output of events at the same time, as a list, which should appear similar to:

如果使用 /run,您将同时看到事件的完整输出作为列表,应该类似于:

[{"content":{"parts":[{"functionCall":{"id":"af-e75e946d-c02a-4aad-931e-49e4ab859838","args":{"city":"new york"},"name":"get_weather"}}],"role":"model"},"invocationId":"e-71353f1e-aea1-4821-aa4b-46874a766853","author":"weather_time_agent","actions":{"stateDelta":{},"artifactDelta":{},"requestedAuthConfigs":{}},"longRunningToolIds":[],"id":"2Btee6zW","timestamp":1743712220.385936},{"content":{"parts":[{"functionResponse":{"id":"af-e75e946d-c02a-4aad-931e-49e4ab859838","name":"get_weather","response":{"status":"success","report":"The weather in New York is sunny with a temperature of 25 degrees Celsius (41 degrees Fahrenheit)."}}}],"role":"user"},"invocationId":"e-71353f1e-aea1-4821-aa4b-46874a766853","author":"weather_time_agent","actions":{"stateDelta":{},"artifactDelta":{},"requestedAuthConfigs":{}},"id":"PmWibL2m","timestamp":1743712221.895042},{"content":{"parts":[{"text":"OK. The weather in New York is sunny with a temperature of 25 degrees Celsius (41 degrees Fahrenheit).\n"}],"role":"model"},"invocationId":"e-71353f1e-aea1-4821-aa4b-46874a766853","author":"weather_time_agent","actions":{"stateDelta":{},"artifactDelta":{},"requestedAuthConfigs":{}},"id":"sYT42eVC","timestamp":1743712221.899018}]

Using /run_sse 使用 /run_sse

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": false
}'

You can set streaming to true to enable token-level streaming, which means the response will be returned to you in multiple chunks and the output should appear similar to:

您可以将 streaming 设置为 true 以启用令牌级流式传输,这意味着响应将以多个块的形式返回给您,输出应该类似于:

data: {"content":{"parts":[{"functionCall":{"id":"af-f83f8af9-f732-46b6-8cb5-7b5b73bbf13d","args":{"city":"new york"},"name":"get_weather"}}],"role":"model"},"invocationId":"e-3f6d7765-5287-419e-9991-5fffa1a75565","author":"weather_time_agent","actions":{"stateDelta":{},"artifactDelta":{},"requestedAuthConfigs":{}},"longRunningToolIds":[],"id":"ptcjaZBa","timestamp":1743712255.313043}

data: {"content":{"parts":[{"functionResponse":{"id":"af-f83f8af9-f732-46b6-8cb5-7b5b73bbf13d","name":"get_weather","response":{"status":"success","report":"The weather in New York is sunny with a temperature of 25 degrees Celsius (41 degrees Fahrenheit)."}}}],"role":"user"},"invocationId":"e-3f6d7765-5287-419e-9991-5fffa1a75565","author":"weather_time_agent","actions":{"stateDelta":{},"artifactDelta":{},"requestedAuthConfigs":{}},"id":"5aocxjaq","timestamp":1743712257.387306}

data: {"content":{"parts":[{"text":"OK. The weather in New York is sunny with a temperature of 25 degrees Celsius (41 degrees Fahrenheit).\n"}],"role":"model"},"invocationId":"e-3f6d7765-5287-419e-9991-5fffa1a75565","author":"weather_time_agent","actions":{"stateDelta":{},"artifactDelta":{},"requestedAuthConfigs":{}},"id":"rAnWGSiV","timestamp":1743712257.391317}

Send a query with a base64 encoded file using /run or /run_sse 使用 /run 或 /run_sse 发送带有 base64 编码文件的查询

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":"Describe this image"
         },
         {
            "inlineData":{
               "displayName":"my_image.png",
               "data":"iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAAsTAAALEwEAmpw...",
               "mimeType":"image/png"
            }
         }
      ]
   },
   "streaming":false
}'

Info

If you are using /run_sse, you should see each event as soon as it becomes available.

如果您正在使用 /run_sse,您应该在每个事件可用时立即看到它。

Integrations

集成

ADK uses Callbacks to integrate with third-party observability tools. These integrations capture detailed traces of agent calls and interactions, which are crucial for understanding behavior, debugging issues, and evaluating performance.

ADK 使用回调与第三方可观察性工具集成。这些集成捕获智能体调用和交互的详细跟踪,这对于理解行为、调试问题和评估性能至关重要。

Comet Opik是一个开源 LLM 可观察性和评估平台,它原生支持 ADK。

Deploy your agent

部署您的智能体

Now that you've verified the local operation of your agent, you're ready to move on to deploying your agent! Here are some ways you can deploy your agent:

现在您已经验证了智能体的本地运行,您准备好部署您的智能体了!以下是您可以部署智能体的一些方式:

  • Deploy to Agent Engine, a simple way to deploy your ADK agents to a managed service in Vertex AI on Google Cloud.

部署到 Agent Engine,这是一种将 ADK 智能体部署到 Google Cloud 上的 Vertex AI 中的托管服务的简单方法。 * Deploy to Cloud Run and have full control over how you scale and manage your agents using serverless architecture on Google Cloud.

部署到 Cloud Run,并使用 Google Cloud 上的无服务器架构完全控制如何扩展和管理您的智能体。

Interactive API docs

交互式 API 文档

The API server automatically generates interactive API documentation using Swagger UI. This is an invaluable tool for exploring endpoints, understanding request formats, and testing your agent directly from your browser.

API 服务器会自动使用 Swagger UI 生成交互式 API 文档。这是探索端点、理解请求格式以及直接从浏览器测试智能体的宝贵工具。

To access the interactive docs, start the API server and navigate to http://localhost:8000/docs in your web browser.

要访问交互式文档,请启动 API 服务器并在 Web 浏览器中导航到 http://localhost:8000/docs。

You will see a complete, interactive list of all available API endpoints, which you can expand to see detailed information about parameters, request bodies, and response schemas. You can even click "Try it out" to send live requests to your running agents.

您将看到所有可用 API 端点的完整交互式列表,您可以展开以查看有关参数、请求体和响应模式的详细信息。您甚至可以点击"试一试"向运行中的智能体发送实时请求。

API endpoints

API 端点

The following sections detail the primary endpoints for interacting with your agents.

以下部分详细说明了与智能体交互的主要端点。

JSON Naming Convention

JSON 命名约定

  • Both Request and Response bodies will use camelCase for field names (e.g., "appName").

  • 请求和响应主体都将使用 camelCase 作为字段名(例如 "appName")。

Utility endpoints

实用工具端点

List available agents

列出可用的智能体

Returns a list of all agent applications discovered by the server.

返回服务器发现的所有智能体应用程序的列表。

  • Method: GET
  • Path: /list-apps

Example Request 示例请求 

curl -X GET http://localhost:8000/list-apps

Example Response 示例响应 

["my_sample_agent", "another_agent"]

Session management

会话管理

Sessions store the state and event history for a specific user's interaction with an agent.

会话存储特定用户与智能体交互的状态和事件历史。

Update a session

更新会话

Updates an existing session.

更新现有会话。

  • Method: PATCH
  • Path: /apps/{app_name}/users/{user_id}/sessions/{session_id}

Request Body 请求主体 

{
  "stateDelta": {
    "key1": "value1",
    "key2": 42
  }
}

Example Request 示例请求 

curl -X PATCH http://localhost:8000/apps/my_sample_agent/users/u_123/sessions/s_abc \
  -H "Content-Type: application/json" \
  -d '{"stateDelta":{"visit_count": 5}}'

Example Response 示例响应 

{"id":"s_abc","appName":"my_sample_agent","userId":"u_123","state":{"visit_count":5},"events":[],"lastUpdateTime":1743711430.022186}

Get a session

获取会话

Retrieves the details of a specific session, including its current state and all associated events.

检索特定会话的详细信息,包括其当前状态和所有关联事件。

  • Method: GET
  • Path: /apps/{app_name}/users/{user_id}/sessions/{session_id}

Example Request 示例请求 

curl -X GET http://localhost:8000/apps/my_sample_agent/users/u_123/sessions/s_abc

Example Response 示例响应 

{"id":"s_abc","appName":"my_sample_agent","userId":"u_123","state":{"visit_count":5},"events":[...],"lastUpdateTime":1743711430.022186}

Delete a session

删除会话

Deletes a session and all of its associated data.

删除会话及其所有关联数据。

  • Method: DELETE
  • Path: /apps/{app_name}/users/{user_id}/sessions/{session_id}

Example Request 示例请求 

curl -X DELETE http://localhost:8000/apps/my_sample_agent/users/u_123/sessions/s_abc

Example Response 示例响应 A successful deletion returns an empty response with a 204 No Content status code. 成功的删除返回一个空响应,状态代码为 204 No Content。

Agent execution

智能体执行

These endpoints are used to send a new message to an agent and get a response.

这些端点用于向智能体发送新消息并获取响应。

Run agent (single response)

运行智能体(单个响应)

Executes the agent and returns all generated events in a single JSON array after the run is complete.

执行智能体并在运行完成后在单个 JSON 数组中返回所有生成的事件。

  • Method: POST
  • Path: /run

Request Body 请求主体 

{
  "appName": "my_sample_agent",
  "userId": "u_123",
  "sessionId": "s_abc",
  "newMessage": {
    "role": "user",
    "parts": [
      { "text": "What is the capital of France?" }
    ]
  }
}

In TypeScript, currently only camelCase field names are supported (e.g. appName, userId, sessionId, etc.).

在 TypeScript 中,目前仅支持 camelCase 字段名(例如 appName、userId、sessionId 等)。

Example Request 示例请求 

curl -X POST http://localhost:8000/run \
  -H "Content-Type: application/json" \
  -d '{
    "appName": "my_sample_agent",
    "userId": "u_123",
    "sessionId": "s_abc",
    "newMessage": {
      "role": "user",
      "parts": [{"text": "What is the capital of France?"}]
    }
  }'

Run agent (streaming)

运行智能体(流式传输)

Executes the agent and streams events back to the client as they are generated using Server-Sent Events (SSE).

执行智能体,并在生成事件时使用服务器发送事件(SSE)将事件流式传输回客户端。

  • Method: POST
  • Path: /run_sse

Request Body 请求主体 The request body is the same as for /run, with an additional optional streaming flag. 请求主体与 /run 相同,带有一个额外的可选 streaming 标志。 

{
  "appName": "my_sample_agent",
  "userId": "u_123",
  "sessionId": "s_abc",
  "newMessage": {
    "role": "user",
    "parts": [
      { "text": "What is the weather in New York?" }
    ]
  },
  "streaming": true
}
- streaming: (Optional) Set to true to enable token-level streaming for model responses. Defaults to false. - streaming: (可选)设置为 true 以启用模型响应的令牌级流式传输。默认值为 false。

Example Request 示例请求 

curl -X POST http://localhost:8000/run_sse \
  -H "Content-Type: application/json" \
  -d '{
    "appName": "my_sample_agent",
    "userId": "u_123",
    "sessionId": "s_abc",
    "newMessage": {
      "role": "user",
      "parts": [{"text": "What is the weather in New York?"}]
    },
    "streaming": false
  }'