Quickstart

Quick Start Alternative

Want to skip the manual setup? Use our CLI to create a complete project:

npx @iqai/adk-cli new

or, if you prefer a global install:

npm install -g @iqai/adk-cli
adk new

This creates a project with all the examples below already set up and ready to run!

ADK CLI Reference

Learn about all CLI commands (new, run, web, serve) and advanced usage in the ADK CLI Reference.

Your First Agent

Let’s create your first agent in a way that works both with the CLI and programmatically.

1. Quick Project Setup

Create and setup your project in one go:

mkdir my-first-agent && cd my-first-agent
npm init -y && npm install @iqai/adk tsx typescript dotenv
npx tsc --init --target ES2022 --module ESNext --moduleResolution bundler --allowImportingTsExtensions --noEmit
echo "GOOGLE_API_KEY=your_google_api_key_here" > .env
echo ".env" > .gitignore

API Key Required

Replace your_google_api_key_here with your actual API key from Google AI Studio.

Create src/agents/agent.ts:

// src/agents/agent.ts
import { AgentBuilder } from "@iqai/adk";

/**
 * This is your first agent!
 * Exported in a way that the ADK CLI can discover and run it.
 */
export async function agent() {
  return await AgentBuilder
    .create("my_first_agent")
    .withModel("gemini-2.5-flash")
    .withInstruction("You are a helpful assistant.")
    .build();
}

2. Run It with the CLI

If you have the CLI installed globally:

adk run

Or with npx:

npx @iqai/adk-cli run

The CLI will:

Auto-discover agent.ts
Start an interactive chat with your agent

You can also test your agent with Web interface:

adk web

Or with npx:

npx @iqai/adk-cli web

3. Run It Programmatically

If you want to run the agent in a script, create main.ts:

// src/main.ts
import { agent } from "./agents/agent";

async function main() {
  const { runner } = await agent();
  const response = await runner.ask("What is the capital of France?");
  console.log("🤖 Response:", response);
}

main().catch(console.error);

Run it with:

npx tsx src/main.ts

Expected Output

You should see something like:

🤖 Response: The capital of France is Paris.

Adding Tools

Now let's make your agent more powerful by adding tools. Update your agent.ts file:

// agent.ts
import { env } from "node:process";
import {
  AgentBuilder,
  GoogleSearch
} from "@iqai/adk";

// Load environment variables
import * as dotenv from "dotenv";
dotenv.config();

export async function agent() {
  return await AgentBuilder
    .create("research_agent")
    .withModel(env.LLM_MODEL || "gemini-2.5-flash")
    .withDescription("A research agent that can search the web")
    .withInstruction(
      "You are a helpful research assistant. Use the Google Search tool " +
      "when you need current information. Provide clear, well-sourced answers."
    )
    .withTools(new GoogleSearch())
    .build();
}

You can now run it with:

npx @iqai/adk-cli run

What's New Here?

AgentBuilder: Using the fluent API pattern for simpler agent creation
Tools: Added GoogleSearch for web searching capabilities
Instructions: Giving the agent specific guidance on how to behave
CLI Ready: This agent can be run directly via the CLI or web UI

Configuration Options

You can customize your agent in many ways:

export async function agent() {
  return await AgentBuilder
    .create("basic_agent")
    .withModel("gemini-2.5-flash")
    .build();
}

export async function agent() {
  return await AgentBuilder
    .create("helpful_assistant")
    .withModel("gemini-2.5-flash")
    .withDescription("A friendly and helpful assistant")
    .withInstruction(
      "You are a helpful assistant. Always be polite and " +
      "provide clear, accurate information."
    )
    .build();
}

export async function agent() {
  return await AgentBuilder
    .create("research_agent")
    .withModel("gemini-2.5-flash")
    .withDescription("A research agent with web search")
    .withInstruction("Use tools to find accurate information")
    .withTools(new GoogleSearch())
    .build();
}

Recommended Project Structure

Once you're ready to organize a larger project, we recommend this structure:

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

Each agent.ts should export one of the following:

An LlmAgent instance
A BuiltAgent object (returned by AgentBuilder.build())
A function (sync or async) returning an LlmAgent or BuiltAgent

This allows the CLI and web UI to auto-discover your agents for chat and iteration.

Using External Models

Want to use models from OpenAI, Anthropic, or other providers? ADK supports 100+ models through Vercel AI SDK:

OpenAI Example

npm install @ai-sdk/openai

import { LlmAgent } from "@iqai/adk";
import { openai } from "@ai-sdk/openai";

export default new LlmAgent({
  name: "openai_agent",
  model: openai("gpt-4.1"),
  instruction: "You are a helpful assistant"
});

Anthropic Example

npm install @ai-sdk/anthropic

import { LlmAgent } from "@iqai/adk";
import { anthropic } from "@ai-sdk/anthropic";

export default new LlmAgent({
  name: "claude_agent",
  model: anthropic("claude-3-5-sonnet-20241022"),
  instruction: "You are a helpful assistant"
});

More Providers

ADK supports many models through Vercel AI SDK including OpenAI, Anthropic, Google, Mistral, and more. Check the Models documentation for the complete list of supported providers.

Next Steps

Congratulations! You've created your first AI agent. Here's what to explore next:

🛠️ Add More Tools

Learn about built-in tools and how to create custom ones

🤖 Advanced Agents

Explore LLM agents, workflow agents, and multi-agent systems

💾 Sessions & Memory

Add persistent conversations and memory to your agents

📊 Real Examples

See complete working examples with different patterns

Troubleshooting

Common Issues

Model Access

If you get authentication errors, make sure you have access to the Gemini models or configure appropriate API keys in your environment.

Dependencies

If you encounter import errors, ensure all dependencies are installed:

npm install @iqai/adk dotenv tsx typescript

Environment Variables

Make sure your .env file is in the project root and contains your API keys. Never commit .env files to version control - add .env to your .gitignore:

echo ".env" >> .gitignore

Quickstart

🛠️ Add More Tools

🤖 Advanced Agents

💾 Sessions & Memory

📊 Real Examples

On this page