TypeScriptADK-TS
Get Started

Quickstart

Build your first AI agent with ADK-TS in 5 minutes

Ready to build your first AI agent? This guide will take you from zero to a working agent with tools in just a few minutes.

Quick Start with CLI

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

npx @iqai/adk-cli new

This creates a project with working agents already set up and ready to run!

Learn more about installation options including adding ADK-TS to existing projects.

Build Your First Agent

Let's walk through creating your first AI agent step by step.

1. Set Up a New Project

Create a new project from scratch:

mkdir my-first-agent && cd my-first-agent
pnpm init -y
pnpm install @iqai/adk tsx typescript dotenv
npx tsc --init --target ES2022 --module ESNext --moduleResolution bundler --allowImportingTsExtensions --noEmit

2. Configure Environment Variables

Create a .env file in your project root with your API key:

echo "GOOGLE_API_KEY=your_google_api_key_here" > .env
echo -e ".env\nnode_modules/" > .gitignore

API Key Required

Replace your_google_api_key_here with your actual API key from Google AI Studio. ADK-TS supports Google Gemini models by default.

3. Create Your First Agent

Create a simple agent in src/agents/assistant/agent.ts:

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

dotenv.config();

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

Using Different Models

You can easily use other LLM models by changing the model parameter:

// For OpenAI models
.withModel("gpt-4o")

// For Anthropic models
.withModel("claude-3-5-sonnet")

ADK-TS will automatically detect the provider from the model name, but you'll need to set the appropriate API key in your .env file (e.g., OPENAI_API_KEY for OpenAI models or ANTHROPIC_API_KEY for Anthropic models).

For advanced LLM configurations, check our Models documentation.

4. Test Your Agent

Now let's test your agent. Create a simple script to interact with it. Add the following to src/agents/index.ts:

// src/agents/index.ts
import { agent } from "./assistant/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 in your terminal:

npx tsx src/agents/index.ts

You should see something like:

🤖 Response: The capital of France is Paris.

Congratulations! 🎉 You've just created and run your first AI agent.

Adding Tools to Your Agent

Now let's make your agent more powerful by adding the ability to search the web using our built-in GoogleSearch tool:

1. Update Your Agent with Tools

Replace your src/agents/assistant/agent.ts with this enhanced version:

// src/agents/assistant/agent.ts
import { AgentBuilder, GoogleSearch } from "@iqai/adk";
import * as dotenv from "dotenv";

dotenv.config();

export async function agent() {
  return await AgentBuilder.create("research_assistant")
    .withModel("gemini-2.5-flash")
    .withDescription(
      "A helpful research assistant with web search capabilities"
    )
    .withInstruction(
      "You are a helpful research assistant. When you need current information " +
        "or want to search for specific topics, use the Google Search tool. " +
        "Always cite your sources when providing information from search results."
    )
    .withTools(new GoogleSearch())
    .build();
}

2. Test the Tool Integration

Update your test script to ask a question that requires web search:

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

async function main() {
  const { runner } = await agent();

  const response = await runner.ask(
    "What are the latest developments in AI technology in 2024?"
  );
  console.log("🤖 Response:", response);
}

main().catch(console.error);

Run it again:

npx tsx src/agents/index.ts

Your agent will now search the web for current information and provide a more comprehensive, up-to-date answer!

Implementation Note

The current GoogleSearch implementation returns mock results. Integration with actual Google Search API requires additional configuration.

Using the CLI for Interactive Testing

Instead of writing test scripts, you can interact with your agent directly using our CLI. The CLI provides two ways to test your agents:

Terminal-Based Chat (adk run)

For a command-line chat experience, install the CLI globally and start the chat:

# Install the CLI globally
pnpm install -g @iqai/adk-cli

# Start terminal-based chat with your agent
adk run

Or use npx without global installation:

npx @iqai/adk-cli run

Agent Discovery

For the CLI to auto-discover your agents, make sure your agent files are placed under the src/agents directory.

This command will:

  • Auto-discover your agent file
  • Start an interactive chat session in your terminal
  • Allow you to ask questions and see responses in real-time
  • Show tool usage and agent reasoning (if applicable)

Web-Based Interface (adk web)

For a more visual chat experience with a web interface, if you have the ADK-TS CLI installed globally, run:

adk web

Or use npx without global installation:

npx @iqai/adk-cli web

This command will:

  • Launch a local web server with a chat interface
  • Display the URL where you can access the web interface (https://adk-web.iqai.com)
  • Provide a more user-friendly way to test your agent
  • Show conversation history and formatting

No Scripts Required

Both adk run and adk web let you test your agents interactively without writing any test scripts. Perfect for quick testing and experimentation!

As your project grows, we recommend organizing your code like this:

my-agent-project/
├── .env                # Environment variables (API keys)
├── .gitignore          # Don't commit .env files!
├── package.json
├── tsconfig.json
└── src/
    ├── agent.ts        # Main agent export
    ├── main.ts         # Script runner (optional)
    └── tools/          # Custom tools (optional)
        └── customTool.ts

For larger projects with multiple agents:

my-multi-agent-project/
├── .env
├── package.json
└── src/
    ├── agents/
    │   ├── research-agent/
    │   │   ├── agent.ts
    │   │   └── tools.ts
    │   ├── analysis-agent/
    │   │   ├── agent.ts
    │   │   └── tools.ts
    │   └── coordinator/
    │       └── agent.ts
    └── shared/
    │   └── tools/
    │       └── customTool.ts
    └── main.ts         # Script runner (optional)

Next Steps

Congratulations! You've built your first AI agent and learned how to add tools to it. Here's what to explore next:

🤖 Learn About Agents

Explore different types of agents: LLM agents, workflow agents, and multi-agent systems

🛠️ Discover More Tools

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

🔌 MCP Tools

Connect to external services and tools through the Model Context Protocol

🧠 Models & Providers

Learn how to use different LLM providers and configure model settings

💾 Sessions & Memory

Add persistent conversations and memory to your agents

📊 Real Examples

See complete working examples with different patterns and use cases

How is this guide?

Installation

Install ADK-TS and set up your development environment

Agents

Build autonomous AI agents for reasoning, tool usage, and multi-agent coordination in ADK-TS