ADK CLI Reference

The ADK CLI (@iqai/adk-cli) is a powerful toolkit for creating, running, and managing AI agent projects. It provides commands for project scaffolding, running agents, launching a web interface, and starting an API server.

npm install -g @iqai/adk-cli

Commands Overview

• adk new – Create a new ADK project from templates
• adk run – Run agents with interactive chat or server mode
• adk web – Launch a web interface for agent testing and management
• adk serve – Start a standalone API server for agent management

adk new

Create a new ADK project from professional templates.

adk new
# or with a specific template
adk new my-agent --template simple-agent

Available Templates:

• simple-agent – Basic agent with chat
• discord-bot – Discord bot integration
• telegram-bot – Telegram bot integration
• hono-server – RESTful web server
• mcp-starter – Model Context Protocol server

How Agent Discovery Works

The ADK CLI and web UI will automatically discover all agents in your project that are exported in a supported format. This enables you to quickly iterate and chat with any agent, whether via the CLI or the web interface.

Supported Agent Exports

Each agent.ts file should export one of the following:

• An LlmAgent instance (default or named export)
• A BuiltAgent object (the result of await AgentBuilder.build(), recommended for root/supervisor agents that need to be run directly)
• A function (sync or async) returning an LlmAgent or BuiltAgent

Example:

// For sub-agents or workflow agents (most agents):
import { LlmAgent } from "@iqai/adk";

export default new LlmAgent({
	name: "my_sub_agent",
	model: "gemini-2.5-flash",
	instruction: "You are a helpful assistant."
});

// For root/supervisor agents (the entry point for CLI/web UI):
import { AgentBuilder } from "@iqai/adk";

export async function agent() {
	return await AgentBuilder
		.create("my_root_agent")
		.withModel("gemini-2.5-flash")
		.withInstruction("You are a helpful supervisor agent.")
		.build();
}

Tip: Use AgentBuilder and export the result of .build() (or a function returning it) for your root/supervisor agent that will be run directly by the CLI or web UI. For sub-agents or workflow components, export an LlmAgent or similar agent class directly.

You can organize your agents in folders, e.g.:

agents/
├── main_agent/
│   ├── agent.ts         # Exports your main/root agent (see below)
│   ├── tools.ts         # (optional) Tools for this agent
│   └── sub_agents/
│       ├── sub_agent1/
│       │   ├── agent.ts     # Exports a sub-agent
│       │   └── tools.ts
│       └── sub_agent2/
│           ├── agent.ts
│           └── tools/
│               └── customTool.ts

All such agents will be listed for selection in adk run and available in the web UI via adk web.

adk run

Run agents with intelligent discovery and interactive chat interface.

adk run
# Run a specific agent file
adk run path/to/agent.ts
# Server-only mode
adk run --server

• Auto-discovers agents in the current directory
• Interactive selector if multiple agents are found
• Supports server mode for API-only usage

adk web

Launch a React-based web interface for visual agent testing and management.

adk web
# Use a specific port
adk web --port 8080
# Scan a custom directory
adk web --dir ./my-agents

• Visual agent browser and chat
• Live status monitoring
• Responsive design for desktop and mobile

adk serve

Start a standalone API server for agent management (no chat UI).

adk serve
# Custom host and port
adk serve --host 0.0.0.0 --port 9000
# Scan a specific directory
adk serve --dir ./production-agents

API Endpoints:

• GET /api/agents – List all discovered agents
• POST /api/agents/:id/message – Send message to agent
• GET /api/agents/:id/messages – Get conversation history
• GET /health – Health check

Example Workflow

# 1. Create a new project
adk new my-ai-assistant --template simple-agent
cd my-ai-assistant

# 2. Install dependencies
npm install

# 3. Start development
adk run

# 4. Launch the web interface (in another terminal)
adk web --local