Use the Command Line¶

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

ADK provides an interactive terminal interface for testing your agents. This is useful for quick testing, scripted interactions, and CI/CD pipelines.

ADK Run

Run an agent¶

Use the following command to run your agent in the ADK command line interface:

PythonTypeScriptGoJava

adk run my_agent

npx @google/adk-devtools run agent.ts

go run agent.go

Create an AgentCliRunner class (see Java Quickstart) and run:

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

This starts an interactive session where you can type queries and see agent responses directly in your terminal:

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

Session options¶

The adk run command includes options for saving, resuming, and replaying sessions.

Save sessions¶

To save the session when you exit:

adk run --save_session path/to/my_agent

You'll be prompted to enter a session ID, and the session will be saved to path/to/my_agent/<session_id>.session.json.

You can also specify the session ID upfront:

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

Resume sessions¶

To continue a previously saved session:

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

This loads the previous session state and event history, displays it, and allows you to continue the conversation.

Replay sessions¶

To replay a session file without interactive input:

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

The input file should contain initial state and queries:

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

Storage options¶

Option	Description	Default
`--session_service_uri`	Custom session storage URI	SQLite under `.adk/session.db`
`--artifact_service_uri`	Custom artifact storage URI	Local `.adk/artifacts`

Example with storage options¶

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

All options¶

Option	Description
`--save_session`	Save the session to a JSON file on exit
`--session_id`	Session ID to use when saving
`--resume`	Path to a saved session file to resume
`--replay`	Path to an input file for non-interactive replay
`--session_service_uri`	Custom session storage URI
`--artifact_service_uri`	Custom artifact storage URI

Conformance Testing¶

Use adk conformance to run conformance tests and verify that your agent's behavior is consistent and correct.

Run tests¶

To run all conformance tests in the tests/ directory, use the following command:

adk conformance test

You can also specify paths to specific test directories:

adk conformance test tests/core tests/tools

Generate reports¶

To generate a Markdown report of the test results, use the --generate_report flag:

adk conformance test --generate_report

By default, the report is saved in the current directory. To specify a different directory, use the --report_dir option:

adk conformance test --generate_report --report_dir=reports

API Server¶

Use adk api_server to start a local server that exposes your agent's endpoints. This is useful for testing integrations and interacting with your agent programmatically.

Start the server¶

To start the API server for the agents in the current directory, use the following command:

adk api_server

You can also specify the directory containing your agents:

adk api_server path/to/my_agents

Automatic session creation¶

When you interact with the /run endpoint, you typically need to create a session first. To simplify this process during development, use the --auto_create_session flag. This flag automatically creates a session if one doesn't exist.

adk api_server --auto_create_session