cli library

ADK CLI toolchain entrypoints and programmatic runners.

Classes

AdkCliRunner
Programmatic interface for dispatching ADK CLI commands.
AdkLoggerConfig
Active logger configuration for CLI log setup.
AdkSystemInfo
Diagnostics report for the local ADK developer environment.
AdkWebServer
Configurable wrapper that starts and stops the ADK dev web server.
AdkWebServerClient
Minimal ADK web-server API client used by conformance utilities.
AgentChangeEventHandler
Handles agent source file change events for cache invalidation.
AgentGraph
Graph model containing agent, workflow node, and tool relationships.
AgentGraphNode
Node model used by CLI graph output.
AgentLoader
Filesystem-backed loader for ADK agents and apps.
BaseAgentLoader
Loads root agents and app metadata from an agents directory.
CliBaseModel
Base JSON-serializable model contract used by CLI utility types.
ConformanceTestCase
Named conformance test case with ordered turns.
ConformanceTestResult
Aggregate result for one conformance test case.
ConformanceTurn
One conversational turn in a conformance test.
ConformanceTurnResult
Result for one replayed turn.
DemoTimeModel
Lightweight model used by local dev scaffolds before real model setup.
DeployCliOptions
Parsed options for a single adk deploy invocation.
DeployCommand
Resolved deployment configuration used to build gcloud commands.
DevAgentRuntime
Runtime wrapper for local ADK development sessions.
DevProjectConfig
Development project metadata used by local ADK tooling.
DotAdkFolder
Helper for reading and writing files under the .adk folder.
FastApiApp
Thin wrapper around AdkWebServer for web and API server modes.
GcsEvalManagers
Pair of GCS-backed eval managers used by CLI eval commands.
PerAgentDatabaseSessionService
Routes session operations to per-agent local database services.
RecordingsPlugin
In-memory manager for CLI session recordings.
RecordingTurn
One recorded user/assistant turn for CLI replay workflows.
ReplayPlugin
Cursor-based helper for replaying recorded CLI turns.
ServiceRegistry
Registry of URI-scheme factories for session, artifact, and memory services.
SessionRecording
Full session recording used by CLI record/replay plugins.
SharedValue<T>
Shared mutable holder for a single value of type T.

Enums

CreateAgentType
Supported starter agent templates for newly created projects.
CreateBackend
Supported runtime backends for newly created agent projects.
DeployTarget
Deploy targets supported by the CLI.
Level
Supported log levels for CLI logging setup.

Constants

adkDisableLoadDotenvEnvVar → const String
Environment variable key that disables .env loading for CLI runs.
adkPackageVersion → const String
The current version of the adk package.
adkSpecVersion → const String
The target compatibility version of the upstream ADK specification.
adkUsage → const String
Usage text printed for adk --help.
builtInSessionServiceKey → const String
Internal app key used for CLI built-in agents.
cloudRunServiceEnv → const String
Cloud Run environment variable used for runtime detection.
deployUsage → const String
Usage text printed by adk deploy --help.
disableLocalStorageEnv → const String
Environment variable that disables local .adk storage services.
forceLocalStorageEnv → const String
Environment variable that forces local .adk storage services.
getCurrentTimeToolName → const String
The demo tool name used by DemoTimeModel and dev scaffolds.
kubernetesHostEnv → const String
Kubernetes environment variable used for runtime detection.
loggingFormat → const String
Default Python-style logging format string retained for parity.

Properties

activeLoggerConfig → AdkLoggerConfig
The currently active logger configuration.
no setter

Functions

asBaseAgent(AgentOrApp value) → BaseAgent
Converts value to a BaseAgent.
buildGraph(BaseAgent rootAgent) → Future<AgentGraph>
Builds an AgentGraph from rootAgent and its reachable children/tools.
buildSseEventsForRun(Event event, {required bool isResumeRequest}) → List<Event>
Expands one streamed event into content/action events when needed.
clearCliEnvironmentOverrides() → void
Clears all CLI environment overrides.
clearExtraPluginFactoriesForTest() → void
Clears registered extra plugin factories and related test caches.
closeRunners(List<Runner> runners, {Duration timeout = const Duration(seconds: 30)}) → Future<void>
Closes all runners and bounds total wait time by timeout.
convertContentToText(Content? content) → String
Converts content into a readable multi-line text form.
convertSessionToEvalInvocations(Session? session) → List<Invocation>
Converts a session event stream into evaluation invocations.
convertToolCallsToText(List<FunctionCall> calls) → String
Converts tool calls into one line per function invocation.
createArtifactServiceFromOptions({required Object baseDir, String? artifactServiceUri, bool strictUri = false, bool useLocalStorage = true}) → BaseArtifactService
Creates an artifact service from CLI options and environment context.
createDevProject({required String projectDirPath, String? appName}) → Future<void>
Creates a scaffolded ADK development project at projectDirPath.
createEmptyState(BaseAgent agent, {Map<String, Object?>? initializedStates}) → Map<String, Object?>
Creates an empty state map inferred from agent instruction placeholders.
createGcsEvalManagersFromUri(String evalStorageUri) → GcsEvalManagers
Creates GCS eval managers from a gs:// evalStorageUri.
createLocalArtifactService({required Object baseDir}) → BaseArtifactService
Creates a file-backed artifact service rooted at baseDir.
createLocalDatabaseSessionService({required Object baseDir}) → BaseSessionService
Creates a SQLite-backed session service rooted at baseDir.
createLocalSessionService({required Object baseDir, bool perAgent = false, Map<String, String>? appNameToDir}) → BaseSessionService
Creates a local session service for CLI usage.
createMemoryServiceFromOptions({required Object baseDir, String? memoryServiceUri}) → BaseMemoryService
Creates a memory service from CLI options and environment context.
createSessionServiceFromOptions({required Object baseDir, String? sessionServiceUri, Map<String, Object?>? sessionDbKwargs, Map<String, String>? appNameToDir, bool useLocalStorage = true}) → BaseSessionService
Creates a session service from CLI options and environment context.
Creates or replaces a symbolic link from symlinkPath to targetPath.
directoryFromArg(Object value, {required String parameterName}) → Directory
Coerces value to an absolute Directory.
dotAdkFolderForAgent({required Object agentsRoot, required String appName}) → DotAdkFolder
Returns a DotAdkFolder resolved from agentsRoot and appName.
getAgentGraph(BaseAgent rootAgent, {Set<(String, String)> highlightPairs = const <(String, String)>{}}) → Future<String>
Returns Mermaid flowchart text for the graph rooted at rootAgent.
getAgentGraphDot(BaseAgent rootAgent, {Set<(String, String)> highlightPairs = const <(String, String)>{}, Map<String, NodeStatus> nodeStatuses = const <String, NodeStatus>{}, bool darkMode = true}) → Future<String>
Returns Graphviz DOT text for the graph rooted at rootAgent.
getCliEnvironment() → UnmodifiableMapView<String, String>
Returns an immutable view of effective CLI environment values.
getCliEnvironmentValue(String key) → String?
Looks up one environment key from CLI overrides and process environment.
getCurrentTime({required String city}) → Map<String, Object>
Returns a serialized current-time payload for city.
getDefaultMetricInfo({bool addTrajectoryMetrics = false}) → List<EvalMetric>
Default metrics used by CLI evaluation runs.
getFastApiApp({required String agentsDir, String appName = '', int port = 8000, String host = '127.0.0.1', List<String> allowOrigins = const <String>[], String? sessionServiceUri, String? artifactServiceUri, String? memoryServiceUri, bool useLocalStorage = true, String? urlPrefix, bool autoCreateSession = false, bool enableWebUi = true, String? logoText, String? logoImageUrl}) → FastApiApp
Creates a FastApiApp with the provided server options.
getRootAgentFromModule(Agent rootAgent) → Agent
Returns rootAgent for CLI module compatibility.
getServiceRegistry() → ServiceRegistry
Returns the global ServiceRegistry instance with built-ins registered.
instantiateRegisteredClassFactory(String classPath, {String? uri, Map<String, Object?>? kwargs}) → Object?
Instantiates a previously registered class factory for classPath.
isCloudRun([Map<String, String>? environment]) → bool
Whether the current process appears to be running on Cloud Run.
isDirWritable(Directory dir) → bool
Whether dir is writable by creating and deleting a probe file.
isFunctionResumeRequest({required String? invocationId, required Content? newMessage}) → bool
Returns true when this /run_sse request is resuming a paused tool call.
isKubernetes([Map<String, String>? environment]) → bool
Whether the current process appears to be running on Kubernetes.
loadDevProjectConfig(String projectDirPath, {bool validateProjectDir = false, bool requireConfigFile = false}) → Future<DevProjectConfig>
Loads DevProjectConfig from projectDirPath.
loadDotenvForAgent(String agentName, String agentParentFolder, {String filename = '.env', void log(String message)?}) → void
Loads dotenv variables for agentName from agentParentFolder.
loadServicesModule(String agentsDir) → void
Loads service registrations from services.yaml files under agentsDir.
logToTmpFolder({Level level = Level.info, String subFolder = 'agents_log', String logFilePrefix = 'agent', String? logFileTimestamp, void echo(String message)?}) → String
Initializes a temporary log file and returns its path.
main(List<String> args, {IOSink? outSink, IOSink? errSink, Map<String, String>? environment}) → Future<int>
Dispatches Click-style command invocations.
normalizeJsonObject(Map<Object?, Object?> input) → Map<String, Object?>
Normalizes map keys into lower camel case and preserves values.
parseAdkCliArgs(List<String> args) → ParsedAdkCommand
Parses CLI args into a typed ParsedAdkCommand.
parseAndGetEvalsToRun({required String? evalIds, required List<String> availableEvalIds}) → List<String>
Resolves which eval IDs to run from evalIds and availableEvalIds.
prettyPrintEvalResult(EvalCaseResult result) → String
Formats result into a stable human-readable summary block.
projectDirName(String path) → String
The normalized terminal folder name for path.
promptStr(String prompt, {String? defaultValue, String? value}) → String
Returns the resolved prompt value from value or defaultValue.
promptToChooseBackend({String? value}) → CreateBackend
Parses value into a CreateBackend choice.
promptToChooseType({String? value}) → CreateAgentType
Parses value into a CreateAgentType choice.
recordConformanceSession({required AdkWebServerClient client, required String appName, required String userId, required String sessionId, required List<ConformanceTurn> turns}) → Future<SessionRecording>
Replays turns and records resulting replies into a session recording.
redactUriForLog(String uri) → String
Redacts sensitive URI components before writing logs.
registerExtraPluginFactory(String pluginSpec, ExtraPluginFactory factory) → void
Registers a plugin factory for a CLI --extra_plugins pluginSpec.
registerServiceClassFactory(String classPath, ServiceFactory<Object> factory) → void
Registers a custom YAML-instantiable class factory for classPath.
resetServiceRegistryForTest() → void
Resets global registry state for isolated tests.
resolveProject(String? projectInOption, {Map<String, String>? env}) → String
The resolved Google Cloud project ID for deployment.
resolveUseLocalStorage({required Directory basePath, required bool requested, Map<String, String>? environment}) → (bool, String?)
Resolves whether local storage should be used for CLI services.
runAdkCli(List<String> args, {IOSink? outSink, IOSink? errSink}) → Future<int>
Runs the ADK CLI command handler and returns an exit code.
runConformanceSuite({required AdkWebServerClient client, required List<ConformanceTestCase> testCases, required String userId, required String sessionId}) → Future<List<ConformanceTestResult>>
Runs a full conformance suite and returns all case results.
runConformanceTestCase({required AdkWebServerClient client, required ConformanceTestCase testCase, required String userId, required String sessionId}) → Future<ConformanceTestResult>
Runs one conformance testCase against an existing sessionId.
runCreateCommand({required String projectDir, String? appName}) → Future<int>
Creates a new ADK project at projectDir.
runDeployCommand(List<String> args, {IOSink? outSink, IOSink? errSink, Map<String, String>? environment, DeployCommandRunner? commandRunner}) → Future<int>
Runs the deploy CLI command and returns a process-compatible exit code.
serializeAgent(BaseAgent agent) → GraphJson
Recursively serializes agent into JSON-safe fields.
serializeAppInfo(App app, {String? readme}) → GraphJson
Serializes an app for graph-oriented web UI endpoints.
serializeEdge(Edge edge) → GraphJson
Serializes one workflow edge.
serializeNode(BaseNode node) → GraphJson
Serializes a workflow node.
setCliEnvironmentValue(String key, String value) → void
Sets one CLI environment override key to value.
setCliEnvironmentValues(Map<String, String> values) → void
Adds multiple CLI environment overrides from values.
setupAdkLogger({Level level = Level.info}) → void
Sets the process-wide ADK logger configuration.
startAdkDevWebServer({required DevAgentRuntime runtime, required DevProjectConfig project, String agentsDir = '.', int port = 8000, InternetAddress? host, List<String> allowOrigins = const <String>[], String? sessionServiceUri, String? artifactServiceUri, String? memoryServiceUri, String? evalStorageUri, bool useLocalStorage = true, String? urlPrefix, bool autoCreateSession = false, bool enableWebUi = true, String? logoText, String? logoImageUrl, bool reload = true, bool reloadAgents = false, bool traceToCloud = false, bool otelToCloud = false, bool a2a = false, List<String> extraPlugins = const <String>[], Map<String, String>? environment}) → Future<HttpServer>
Starts the ADK development web server and returns the bound HttpServer.
startAdkWebServer({required String agentsDir, String appName = '', int port = 8000, String host = '127.0.0.1', List<String> allowOrigins = const <String>[], String? sessionServiceUri, String? artifactServiceUri, String? memoryServiceUri, bool useLocalStorage = true, String? urlPrefix, bool autoCreateSession = false, bool enableWebUi = true, String? logoText, String? logoImageUrl}) → Future<HttpServer>
Starts an AdkWebServer with one call.
toAgentEngine(DeployCommand command) → List<String>
The gcloud alpha ai reasoning-engines deploy command from command.
toCamelCase(String value) → String
Converts an underscore-separated value to lower camel case.
toCloudRun(DeployCommand command) → List<String>
The gcloud run deploy command built from command.
toGke(DeployCommand command) → List<String>
The gcloud container clusters get-credentials command from command.
Creates a stable latest symlink for a log file when possible.
tryGetResetFunc(Object? moduleLike) → Object?
Returns a reset callback from moduleLike when one is provided.
validateGcloudExtraArgs(List<String> args) → void
Validates raw gcloud passthrough args.
walkToRootUntilFound(String folder, String filename) → File?
Walks upward from folder until filename is found.

Typedefs

AgentFactory = AgentOrApp Function(String agentName, String agentsDir)
Factory signature used to resolve an agent at runtime.
AgentOrApp = Object
Union type used by loaders that can return either an App or BaseAgent.
DeployCommandRunner = Future<int> Function(List<String> command, {required Map<String, String> environment, required IOSink err, required IOSink out})
Signature for pluggable command execution in deploy workflows.
ExtraPluginFactory = BasePlugin Function(String pluginSpec, {required String baseDir})
Factory signature for dynamically added web-server plugins.
GraphJson = Map<String, Object?>
JSON-compatible object map.
ServiceFactory<T> = T Function(String uri, {Map<String, Object?>? kwargs})
Factory signature used to build services from URI-based configuration.

Exceptions / Errors

SpecialAgentAccessDeniedException
Thrown when an internal special agent (an app name starting with __) is requested while the server is not configured to allow it.