TypeScriptADK-TS
Get Started

Installation

Install ADK TypeScript and set up your development environment

Prerequisites

System Requirements

  • Node.js: v22.0 or higher
  • Package Manager: npm, yarn, or pnpm
  • TypeScript: v5.3 or higher (optional but recommended)

Quick Start with CLI

The fastest way to get started is using our CLI tool to create a new project:

npx create-adk-project
yarn create adk-project
pnpm create adk-project

This will:

  • Create a new project with the ADK Agent Starter template
  • Set up TypeScript configuration
  • Install all necessary dependencies
  • Provide example code to get you started

What's Included

The CLI creates a complete project with:

  • Pre-configured TypeScript setup
  • Example agent implementations
  • Environment configuration template
  • Development scripts and tooling

Manual Installation

If you prefer to add ADK to an existing project or want more control over the setup:

Install the Package

npm install @iqai/adk
yarn add @iqai/adk
pnpm add @iqai/adk

Set Up Environment Variables

Create a .env file in your project root:

# Optional: specify your preferred LLM model
LLM_MODEL=gemini-2.5-flash

# Add any API keys if needed for specific tools
# GOOGLE_API_KEY=your_google_api_key_here

Verify Installation

Create a simple test file to verify everything is working:

import { AgentBuilder } from "@iqai/adk";

async function test() {
  try {
    const response = await AgentBuilder
      .withModel("gemini-2.5-flash")
      .ask("Hello! Can you confirm the installation is working?");

    console.log("✅ Installation successful!");
    console.log("Response:", response);
  } catch (error) {
    console.error("❌ Installation issue:", error);
  }
}

test();

Run the Test

npx tsx test-install.ts
npx ts-node test-install.ts
npx tsc test-install.ts
node test-install.js

Project Setup

For a new TypeScript project, you can set up a complete environment:

Initialize Project

mkdir my-adk-project
cd my-adk-project
npm init -y

Install Dependencies

# Core dependencies
npm install @iqai/adk

# Development dependencies
npm install -D typescript tsx @types/node

# Optional utilities (used in examples)
npm install dedent uuid dotenv
npm install -D @types/uuid

Configure TypeScript

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Create Project Structure

mkdir src
touch src/index.ts
touch .env

Dependencies Overview

ADK TypeScript has minimal dependencies to keep your project lightweight:

Core Dependencies

Required: The ADK package includes everything needed for basic agent functionality.

Optional: Additional packages are only needed for specific features:

  • uuid - For session management
  • dedent - For clean template strings (used in examples)
  • dotenv - For environment variable management

Troubleshooting

Common Installation Issues

Node.js Version

If you encounter installation errors, ensure you're using Node.js v22.0 or higher:

node --version

TypeScript Compatibility

For TypeScript projects, ensure you're using v5.3 or higher:

npx tsc --version

Getting Help

If you encounter issues:

  1. Check the examples: Our examples directory contains working setups
  2. Review error messages: Most installation issues are dependency-related
  3. Open an issue: Report bugs or compatibility issues on GitHub

Next Steps

Now that you have ADK TypeScript installed, you're ready to:

How is this guide?

Get Started

Get up and running with ADK TypeScript in minutes

Quickstart

Build your first AI agent with ADK TypeScript in minutes