测试你的智能体¶

在你部署智能体之前，你应该先进行测试以确保其按预期工作。在开发环境中测试智能体最简单的方法是使用 ADK web UI 并运行如下命令。

PythonJava

adk api_server

请确保更新端口号。

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

在 Java 中，Dev UI 和 API 服务器是打包在一起的。

该命令会启动一个本地 web 服务器，你可以通过 cURL 命令或发送 API 请求来测试你的智能体。

本地测试¶

本地测试包括启动本地 web 服务器、创建会话并向你的智能体发送查询。首先，确保你在正确的工作目录下：

parent_folder/
└── my_sample_agent/
    └── agent.py (或 Agent.java)

启动本地服务器

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

输出应该类似于：

PythonJava

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)

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 '{"state": {"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。
{"state": {"key1": "value1", "key2": 42}}：可选。用于在创建会话时自定义智能体的预设状态（字典）。

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

{"id":"s_123","appName":"my_sample_agent","userId":"u_123","state":{"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"
    }]
}
}'

如果使用 /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. 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}

Info

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

集成¶

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

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

部署你的智能体¶

现在你已经验证了智能体的本地运行情况，你已经准备好部署你的智能体了！以下是一些部署智能体的方式：

部署到 Agent Engine，这是将你的 ADK 智能体部署到 Google Cloud 的 Vertex AI 上的托管服务的最简单方式。
部署到 Cloud Run，你可以完全控制如何使用 Google Cloud 上的无服务器架构扩展和管理你的智能体。