adk::rsv0.5.0
Operatesrc/cli.rs ↗

Embedded CLI

Build your own agent binary on adk_rs::cli::App and get run, web, eval, and version subcommands out of the box.

Rust binaries are statically linked — agents cannot be discovered and loaded at runtime — so adk-rs does not ship a single prebuilt adk binary. Instead, the cli feature provides library scaffolding: you write a tiny main.rs that registers agents on adk_rs::cli::App and forwards to App::run, producing a statically linked binary with a full clap-based CLI.

The App type

fn new(name: impl Into<String>) -> App
Construct an empty app. name becomes the app_name of every Runner the CLI builds.
fn register(self, name: impl Into<String>, agent: Arc<dyn BaseAgent>) -> Self
Register an agent under a name. run --agent <name> and the web server address agents by this name.
fn run(self) -> Result<()>
Parse std::env::args, initialise telemetry from the global flags, build a multi-threaded Tokio runtime, and dispatch the subcommand.
async fn run_async(self, cmd: Command) -> Result<()>
Async dispatch with an explicit Command value — useful for tests that drive the CLI without a process boundary.

For each invocation the CLI builds a Runner with an InMemorySessionService and auto_create_session(true). Sessions therefore do not persist across process runs; embed the server directly with a persistent session service when you need durability.

Example main.rs

src/main.rsrust
use std::sync::Arc;

fn main() -> adk_rs::Result<()> {
    adk_rs::cli::App::new("my-app")
        .register("greeter", Arc::new(build_greeter()?))
        .run()
}

Global flags

FlagDefaultPurpose
--log <FILTER>info (env: ADK_LOG)RUST_LOG-style tracing filter, e.g. adk_rs=debug,info.
--log-format <FORMAT>compactLog output format: compact, pretty, or json.

Subcommands

run — one user turn

Flag / argDefaultPurpose
--agent <NAME>requiredWhich registered agent to run.
--user <ID>anonymousUser id for the session.
--session <ID>noneOptional session id (auto-created if missing).
<MESSAGE>requiredPositional: the user message.

run streams the agent’s events and prints the concatenated text of every content-bearing event to stdout.

web — the dev HTTP server

FlagDefaultPurpose
--bind <ADDR>127.0.0.1:8000Listen address.
--auth-token <TOKEN>none (env: ADK_WEB_TOKEN)Require Authorization: Bearer <token> on every request. Recommended whenever --bind is not loopback.
--dangerously-allow-unauthenticated-remoteoffBind a non-loopback address without a token. Refused by default — see Security model.
--allow-origins <ORIGIN>none (repeatable)CORS allow-list, e.g. http://localhost:4200 for the adk-web UI.

web registers a Runner per agent and delegates to adk_rs::server::serve_with — the full adk api_server-compatible endpoint surface including /run, /run_sse, and session CRUD.

eval — replay an eval set

FlagDefaultPurpose
--set <PATH>requiredPath to the JSON eval set (see Evaluation for the format).
--agent <NAME>requiredWhich registered agent to evaluate.

eval loads the set, runs it through an EvalRunner with TrajectoryMatch::new(1.0) and ResponseMatch::new(0.5) as the metric pair and eval-user as the user id, then prints the EvalReport as pretty JSON. See Evaluation for the format and metrics.

version

Prints adk-rs <crate version>. The clap derive also provides the standard --version and --help flags at every level.

Shell session

Using the generated binarybash
my-app run --agent greeter "Hello!"        # single-turn invocation
my-app web --bind 127.0.0.1:8000           # dev server, loopback default
my-app web --bind 0.0.0.0:8000 \
  --auth-token "$ADK_WEB_TOKEN"            # non-loopback bind requires auth
my-app web --allow-origins http://localhost:4200   # for the adk-web UI
my-app eval --agent greeter --set hello.evalset.json
my-app version