使用命令行¶

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

ADK 提供了一个交互式终端界面，用于测试你的智能体。这对于快速测试、脚本化交互和 CI/CD 流水线非常有用。

ADK Run

运行智能体¶

使用以下命令在 ADK 命令行界面中运行你的智能体：

PythonTypeScriptGoJava

adk run my_agent

npx @google/adk-devtools run agent.ts

在 Go 中，命令行界面不是一个独立的 adk 工具。相反，你需要将启动器直接嵌入到智能体的 main.go 中。 full.NewLauncher() 辅助函数将控制台、Web 服务器和其他模式打包到单个二进制文件中，当未提供子命令关键字时，默认使用控制台模式：

main.go

import (
    "google.golang.org/adk/v2/cmd/launcher"
    "google.golang.org/adk/v2/cmd/launcher/full"
)

func main() {
    // ... 构建你的智能体和配置 ...
    l := full.NewLauncher()
    if err := l.Execute(ctx, config, os.Args[1:]); err != nil {
        log.Fatalf("Run failed: %v\n\n%s", err, l.CommandLineSyntax())
    }
}

使用以下任一命令在控制台模式下运行智能体：

go run agent.go           # 控制台是默认的子启动器
go run agent.go console   # 或显式指定控制台子命令

创建一个 AgentCliRunner 类（参见 Java 快速入门）并运行：

mvn compile exec:java -Dexec.mainClass="com.example.agent.AgentCliRunner"

这将启动一个交互式会话，你可以在终端中直接输入查询并查看智能体的响应。

PythonTypeScriptGoJava

Running agent my_agent, type exit to exit.
[user]: What's the weather in New York?
[my_agent]: The weather in New York is sunny with a temperature of 25°C.
[user]: exit

Running agent my_agent, type exit to exit.
[user]: What's the weather in New York?
[my_agent]: The weather in New York is sunny with a temperature of 25°C.
[user]: exit

User -> What's the weather in New York?

Agent -> The weather in New York is sunny with a temperature of 25°C.

User ->

要退出，请按 Ctrl+C 或发送 EOF（Ctrl+D）。

Running agent my_agent, type exit to exit.
[user]: What's the weather in New York?
[my_agent]: The weather in New York is sunny with a temperature of 25°C.
[user]: exit

会话选项¶

Python only

--save_session、--resume、--replay 和 --session_id 选项仅在 Python ADK CLI 中可用。Go 的控制台启动器不支持通过命令行标志进行会话保存/恢复/回放。在 Go 中，会话持久化是通过在代码中向 launcher.Config 提供持久化的 session.Service 实现（如 session/database）来配置的。

adk run 命令包含用于保存、恢复和回放会话的选项。

保存会话¶

要在退出时保存会话：

adk run --save_session path/to/my_agent

系统会提示你输入会话 ID，会话将保存到 path/to/my_agent/<session_id>.session.json。

你也可以预先指定会话 ID：

adk run --save_session --session_id my_session path/to/my_agent

恢复会话¶

要继续之前保存的会话：

adk run --resume path/to/my_agent/my_session.session.json path/to/my_agent

这将加载之前的会话状态和事件历史记录，显示出来，并允许你继续对话。

回放会话¶

要在没有交互式输入的情况下回放会话文件：

adk run --replay path/to/input.json path/to/my_agent

输入文件应包含初始状态和查询：

{
  "state": {"key": "value"},
  "queries": ["What is 2 + 2?", "What is the capital of France?"]
}

存储选项¶

Python only

--session_service_uri 和 --artifact_service_uri 命令行标志仅在 Python ADK CLI 中可用。在 Go 中，会话和制品服务是在构建 launcher.Config 时在代码中配置的——例如，使用 session/database 作为持久化的数据库支持的会话存储，或使用 artifact/gcsartifact 作为 Cloud Storage 支持的制品存储。

选项	描述	默认值
`--session_service_uri`	自定义会话存储 URI	SQLite，位于 `.adk/session.db`
`--artifact_service_uri`	自定义制品存储 URI	本地 `.adk/artifacts`
`--memory_service_uri`	自定义记忆服务 URI	内存中

存储选项示例¶

adk run --session_service_uri "sqlite:///my_sessions.db" path/to/my_agent

所有选项¶

PythonGo

选项	描述
`--save_session`	退出时将会话保存到 JSON 文件
`--session_id`	保存时使用的会话 ID
`--resume`	要恢复的已保存会话文件路径
`--replay`	用于非交互式回放的输入文件路径
`--session_service_uri`	自定义会话存储 URI
`--artifact_service_uri`	自定义制品存储 URI
`--memory_service_uri`	自定义记忆服务 URI

Go flags differ from Python

Go 的控制台启动器不支持 --save_session、--resume、 --replay、--session_id、--session_service_uri 或 --artifact_service_uri。这些是 Python CLI 的功能。在 Go 中，会话和制品服务通过 launcher.Config 在代码中配置。

标志在 console 关键字之后传递（如果 console 是默认的，则直接传递）：

标志	描述	默认值
`-streaming_mode`	智能体响应的流式模式（`none`\|`sse`）	自动检测（TTY → `sse`，管道 → `none`）
`-shutdown-timeout`	优雅关闭等待时间	`2s`
`-otel_to_cloud`	将 OpenTelemetry 数据导出到 GCP	`false`

例如，要强制非流式输出：

go run agent.go console -streaming_mode none

或者强制 SSE 流式输出（逐 token 输出）：

go run agent.go -streaming_mode sse