Installation

Requirements

Before installing ADK-TS, ensure your environment meets these requirements:

Node.js

Version 22.0 or higher required

Package manager

npm, yarn, or pnpm

Check your Node.js version with node --version

Installation methods

Choose the installation method that best fits your workflow:

CLI (Recommended)
NPM
Yarn
PNPM

The ADK CLI provides the fastest way to create a new project with all dependencies configured:

Install the CLI globally

npm install -g @iqai/adk-cli

Create a new project

adk

The interactive CLI will guide you through:

Project name and location
LLM provider selection
Template selection
Dependency installation

Navigate to your project

cd your-project-name

Set up environment variables

Create a .env file with your API keys:

.env

GOOGLE_API_KEY=your_key_here
# or
OPENAI_API_KEY=your_key_here
# or
ANTHROPIC_API_KEY=your_key_here

The CLI automatically sets up TypeScript configuration, installs dependencies, and creates example code to get you started.

Install ADK-TS in an existing project using npm:

npm install @iqai/adk

For TypeScript projects, ensure you have TypeScript installed:

npm install -D typescript @types/node

Create a tsconfig.json if you don’t have one:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "lib": ["ES2022"],
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "resolveJsonModule": true
  }
}

Install ADK-TS using Yarn:

yarn add @iqai/adk

For TypeScript support:

yarn add -D typescript @types/node

Install ADK-TS using pnpm (recommended for monorepos):

pnpm add @iqai/adk

For TypeScript support:

pnpm add -D typescript @types/node

ADK-TS itself is built with pnpm and uses it extensively in the monorepo structure.

LLM provider setup

ADK-TS supports multiple LLM providers. Configure the ones you plan to use:

Google Gemini

Get your API key from Google AI Studio.

.env

GOOGLE_API_KEY=your_google_api_key_here

Available models:

gemini-2.5-flash (recommended for development)
gemini-2.5-pro
gemini-3-flash-preview
gemini-1.5-pro
gemini-1.5-flash

Example usage:

const response = await AgentBuilder
  .withModel("gemini-2.5-flash")
  .ask("Hello!");

OpenAI

Get your API key from OpenAI Platform.

.env

OPENAI_API_KEY=your_openai_api_key_here

Available models:

gpt-4
gpt-4-turbo
gpt-3.5-turbo
o1-preview
o1-mini

Example usage:

const response = await AgentBuilder
  .withModel("gpt-4")
  .ask("Hello!");

Anthropic Claude

Get your API key from Anthropic Console.

.env

ANTHROPIC_API_KEY=your_anthropic_api_key_here

Available models:

claude-4-opus
claude-4-sonnet
claude-4.5-sonnet
claude-3-5-sonnet-20241022

Example usage:

const response = await AgentBuilder
  .withModel("claude-4.5-sonnet")
  .ask("Hello!");

Google Vertex AI

For Google Cloud Vertex AI, you’ll need to set up authentication:

.env

GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
VERTEX_PROJECT_ID=your-gcp-project-id
VERTEX_LOCATION=us-central1

Example usage:

const response = await AgentBuilder
  .withModel("gemini-1.5-pro-vertex")
  .ask("Hello!");

Optional dependencies

Install additional dependencies based on your use case:

Database sessions
Vector databases
Observability

For persistent session storage with PostgreSQL:

npm install pg

For SQLite:

npm install better-sqlite3

For MySQL:

npm install mysql2

For Qdrant vector database integration:

npm install @qdrant/js-client-rest

For Langfuse observability:

npm install langfuse

For OpenTelemetry instrumentation:

npm install @opentelemetry/instrumentation-express
npm install @opentelemetry/instrumentation-http
npm install @opentelemetry/instrumentation-nestjs-core

CLI tools

The ADK CLI (@iqai/adk-cli) provides powerful commands for development:

adk

The CLI includes a built-in web interface for testing and debugging agents with real-time interaction and event streaming.

Verify installation

Create a simple test file to verify your installation:

test.ts

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

async function test() {
  const response = await AgentBuilder
    .withModel("gemini-2.5-flash")
    .ask("Say hello!");
  
  console.log("ADK-TS is working!");
  console.log("Response:", response);
}

test().catch(console.error);

Run it:

node test.ts

If you see a response from the AI, you’re all set!

Clone and run examples

Explore the comprehensive examples in the repository:

Clone the repository

git clone https://github.com/IQAIcom/adk-ts.git
cd adk-ts

Install dependencies

pnpm install

Build the framework

pnpm build

Set up API keys

cd apps/examples
echo "GOOGLE_API_KEY=your_key_here" > .env

Run examples

pnpm start

Choose from:

01: Getting started with basic agents
02: Tools and state management
03: Multi-agent systems
04: Persistence and sessions
05: Planning and code execution
06: MCP and integrations
07: Guardrails and evaluation
08: Observability and plugins
09: Memory systems
10: Workflow suspend/resume
11: Unified memory

Troubleshooting

Node version errors

ADK-TS requires Node.js 22.0 or higher. Update Node.js:

# Using nvm
nvm install 22
nvm use 22

# Or download from nodejs.org

API key issues

If you get authentication errors:

Verify your API key is correct
Check that your .env file is in the correct directory
Ensure you’re using the right environment variable name
Restart your terminal/IDE to load new environment variables

Module resolution errors

If you get module not found errors:

Clear your node_modules: rm -rf node_modules package-lock.json
Reinstall: npm install
Check your TypeScript configuration
Ensure you’re using a compatible Node.js version

Database connection issues

For database-related errors:

Ensure the database driver is installed (pg, mysql2, better-sqlite3)
Check your connection configuration
Verify database credentials in your .env file
Test database connectivity separately

Next steps

Quickstart

Build your first agent in minutes

Core concepts

Learn the fundamental concepts

Agent types

Explore different agent architectures

API reference

Browse the complete API documentation

Never commit API keys or sensitive credentials to version control. Always use environment variables and add .env to your .gitignore.

Getting Started

Core Concepts

Agents

Models & Providers

Tools

Memory & State

Advanced Features

CLI Tool

Examples

Requirements

Node.js

Package manager

Installation methods

LLM provider setup

Optional dependencies

CLI tools

Verify installation

Clone and run examples

Troubleshooting

Next steps

Quickstart

Core concepts

Agent types

API reference

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Agents

Models & Providers

Tools

Memory & State

Advanced Features

CLI Tool

Examples

​Requirements

Node.js

Package manager

​Installation methods

​LLM provider setup

​Optional dependencies

​CLI tools

​Verify installation

​Clone and run examples

​Troubleshooting

​Next steps

Quickstart

Core concepts

Agent types

API reference

Build docs developers (and LLMs) love

Requirements

Installation methods

LLM provider setup

Optional dependencies

CLI tools

Verify installation

Clone and run examples

Troubleshooting

Next steps