使用 ADK API 服务器¶
在部署你的智能体之前,你应该测试它以确保它按预期工作。使用 ADK 中的 API 服务器通过 REST API 暴露你的智能体,以进行编程测试和集成。
启动 API 服务器¶
使用以下命令在 ADK API 服务器中运行你的智能体:
确保更新端口号。
使用 Maven，编译并运行 ADK web 服务器：
使用 Gradle，build.gradle 或 build.gradle.kts 构建文件应在插件部分包含以下 Java 插件：
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'
}
最后，在命令行中，运行以下命令：
在 Java 中，Dev UI 和 API 服务器是捆绑在一起的。
此命令将启动一个本地 Web 服务器，在该服务器上你可以运行 cURL 命令或发送 API 请求以测试你的智能体。默认情况下，服务器运行在 http://localhost:8000。
有关所有可用端点、请求/响应格式和调试技巧的完整参考（包括如何使用交互式 API 文档），请参阅下面的**ADK API 服务器指南**。
本地测试¶
本地测试包括启动本地 web 服务器、创建会话并向你的智能体发送查询。首先，确保你在正确的工作目录下。
对于 TypeScript，你应该在智能体项目目录本身内。
parent_folder/
└── my_sample_agent/ <-- For TypeScript, run commands from here
└── agent.py (or Agent.java or agent.ts)
启动本地服务器
接下来，使用上面列出的命令启动本地服务器。
输出应该类似于：
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.
你的服务器现在已在本地运行。请确保在后续所有命令中使用正确的端口号。
创建新会话
在 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}'
让我们来分析这个命令：
http://localhost:8000/apps/my_sample_agent/users/u_123/sessions/s_123: 这为你的智能体my_sample_agent创建一个新会话，这是智能体文件夹的名称，用于用户 ID（u_123）和会话 ID（s_123）。你可以将my_sample_agent替换为你的智能体文件夹的名称。你可以将u_123替换为特定的用户 ID，将s_123替换为特定的会话 ID。{"key1": "value1", "key2": 42}: 这是可选的。你可使用此选项在创建会话时自定义智能体的预存状态（字典）。
如果创建成功，应该会返回会话信息。输出类似于：
{"id":"s_123","appName":"my_sample_agent","userId":"u_123","state":{"key1":"value1","key2":42},"events":[],"lastUpdateTime":1743711430.022186}
Info
你不能使用完全相同的用户 ID 和会话 ID 创建多个会话。如果你尝试这样做，可能会看到类似这样的响应：
{"detail":"Session already exists: s_123"}。要解决这个问题，你可以删除该会话（例如 s_123），或选择一个不同的会话 ID。
发送查询
有两种方式可以通过 POST 向你的智能体发送查询，分别是 /run 或 /run_sse 路由。
POST http://localhost:8000/run：收集所有事件为列表并一次性返回。适合大多数用户（如果不确定，推荐用这个）。POST http://localhost:8000/run_sse：以 Server-Sent-Events 方式返回，即事件对象流。适合希望事件一有结果就收到通知的用户。使用/run_sse时，你还可以设置streaming为true以启用令牌级流式。
使用 /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"
}]
}
}'
在 TypeScript 中，目前仅支持 camelCase 字段名（例如 appName、userId、sessionId 等）。
如果使用 /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}]
使用 /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
}'
你可以将 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. 纽约的天气晴朗，温度为 25 摄氏度（41 华氏度）。\n"}],"role":"model"},"invocationId":"e-3f6d7765-5287-419e-9991-5fffa1a75565","author":"weather_time_agent","actions":{"stateDelta":{},"artifactDelta":{},"requestedAuthConfigs":{}},"id":"rAnWGSiV","timestamp":1743712257.391317}
使用 /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":"描述这张图片"
},
{
"inlineData":{
"displayName":"my_image.png",
"data":"iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAAsTAAALEwEAmpw...",
"mimeType":"image/png"
}
}
]
},
"streaming":false
}'
Info
如果使用 /run_sse，你应该在每个事件可用时立即看到它。
集成¶
ADK 使用 回调 与第三方可观察性工具集成。这些集成捕获智能体调用和交互的详细跟踪，对于理解行为、调试问题和评估性能至关重要。
- Comet Opik 是一个开源的 LLM 可观察性和评估平台，原生支持 ADK。
部署你的智能体¶
现在你已经验证了智能体的本地运行情况，你已经准备好部署你的智能体了！以下是一些部署智能体的方式：
- 部署到 Agent Engine,这是将你的 ADK 智能体部署到 Google Cloud 上 Vertex AI 托管服务的最简单方法。
- 部署到 Cloud Run,使用 Google Cloud 上的无服务器架构完全控制智能体的扩展和管理方式。
交互式 API 文档¶
API 服务器使用 Swagger UI 自动生成交互式 API 文档。这是探索端点、理解请求格式和直接从浏览器测试你的智能体的宝贵工具。
要访问交互式文档，启动 API 服务器并在你的 web 浏览器中导航到 http://localhost:8000/docs。
你将看到一个完整的、交互式的所有可用 API 端点列表，你可以展开它以查看有关参数、请求体和响应模式的详细信息。你甚至可以点击"Try it out"向正在运行的智能体发送实时请求。
API 端点¶
以下部分详细说明了与你的智能体交互的主要端点。
JSON 命名约定
- 请求和响应体都将对字段名使用
camelCase（例如，"appName"）。
实用端点¶
列出可用智能体¶
返回服务器发现的所有智能体应用程序列表。
- 方法：
GET - 路径：
/list-apps
示例请求
示例响应
会话管理¶
会话存储特定用户与智能体交互的状态和事件历史。
更新会话¶
更新一个现有会话。
- 方法：
PATCH - 路径：
/apps/{app_name}/users/{user_id}/sessions/{session_id}
示例请求
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}}'
示例响应
{"id":"s_abc","appName":"my_sample_agent","userId":"u_123","state":{"visit_count":5},"events":[],"lastUpdateTime":1743711430.022186}
获取会话¶
检索特定会话的详细信息，包括其当前状态和所有关联事件。
- 方法：
GET - 路径：
/apps/{app_name}/users/{user_id}/sessions/{session_id}
示例请求
示例响应
{"id":"s_abc","appName":"my_sample_agent","userId":"u_123","state":{"visit_count":5},"events":[...],"lastUpdateTime":1743711430.022186}
删除会话¶
删除会话及其所有关联数据。
- 方法：
DELETE - 路径：
/apps/{app_name}/users/{user_id}/sessions/{session_id}
示例请求
示例响应
成功的删除将返回一个空响应，状态码为 204 No Content。
智能体执行¶
这些端点用于向智能体发送新消息并获取响应。
运行智能体（单次响应）¶
执行智能体并在运行完成后在单个 JSON 数组中返回所有生成的事件。
- 方法：
POST - 路径：
/run
请求体
{
"appName": "my_sample_agent",
"userId": "u_123",
"sessionId": "s_abc",
"newMessage": {
"role": "user",
"parts": [
{ "text": "法国的首都是什么？" }
]
}
}
在 TypeScript 中，目前仅支持 camelCase 字段名（例如 appName、userId、sessionId 等）。
示例请求
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": "法国的首都是什么?"}]
}
}'
运行智能体（流式）¶
使用 Server-Sent Events (SSE) 执行智能体并将事件流式传输回客户端。
- 方法：
POST - 路径：
/run_sse
请求体
请求体与 /run 相同，但有一个额外的可选 streaming 标志。
{
"appName": "my_sample_agent",
"userId": "u_123",
"sessionId": "s_abc",
"newMessage": {
"role": "user",
"parts": [
{ "text": "纽约的天气怎么样？" }
]
},
"streaming": true
}
streaming：（可选）设置为true以启用模型响应的令牌级流式传输。默认为false。
示例请求