Skip to main content

​
Get started in minutes

This guide will help you create your first AI agent with ADK-TS. You’ll learn how to set up the framework, create a simple agent, and make your first query.
1

Install ADK-TS

Install the ADK-TS package using your preferred package manager:
npm install @iqai/adk
ADK-TS requires Node.js version 22.0 or higher.
2

Set up your API key

ADK-TS supports multiple LLM providers. For this quickstart, we’ll use Google Gemini. Get your API key from Google AI Studio.Create a .env file in your project root:
.env
GOOGLE_API_KEY=your_google_api_key_here
ADK-TS also supports OpenAI, Anthropic, and other providers. See the installation guide for details.
3

Create your first agent

Create a new file agent.ts and add the following code:
agent.ts
import { AgentBuilder } from "@iqai/adk";

// Simple one-liner agent
const response = await AgentBuilder.withModel("gemini-2.5-flash").ask(
  "What is the capital of France?"
);

console.log(response);
That’s it! This creates an agent using Google’s Gemini model and asks a question.
4

Run your agent

Execute your agent with Node.js:
node agent.ts
You should see a response from the AI model with information about Paris being the capital of France.

​
Add structured output

Let’s enhance our agent to return structured data using Zod schemas: 
import { AgentBuilder } from "@iqai/adk";
import { z } from "zod";

// Define the output structure
const outputSchema = z.object({
  capital: z.string().describe("The capital city name"),
  country: z.string().describe("The country name"),
  population: z.number().optional().describe("Population of the capital city"),
  funFact: z.string().describe("An interesting fact about the city"),
});

// Create agent with structured output
const { runner } = AgentBuilder.withModel("gemini-2.5-flash")
  .withOutputSchema(outputSchema)
  .build();

// Ask a question and get typed response
const response = await runner.ask("Tell me about France");

console.log(`Country: ${response.country}`);
console.log(`Capital: ${response.capital}`);
console.log(`Population: ${response.population?.toLocaleString()}`);
console.log(`Fun fact: ${response.funFact}`);
The response is fully typed based on your Zod schema, giving you autocomplete and type safety!

​
Add custom tools

Tools allow your agent to perform actions. Let’s create a shopping cart agent with custom tools: 
import { AgentBuilder } from "@iqai/adk";
import { addItemTool, viewCartTool } from "./tools";

const { runner } = AgentBuilder.create("shopping_cart_agent")
  .withModel("gemini-2.5-flash")
  .withInstruction(`
    You are a shopping cart assistant. Help users manage their cart.
    You can add items and view the cart. Always be helpful with pricing.
  `)
  .withTools(addItemTool, viewCartTool)
  .withQuickSession({ 
    state: { cart: [], cartCount: 0 } 
  })
  .build();

// Interact with the agent
const response = await runner.ask(
  "Add 2 apples at $1.50 each to my cart"
);

console.log(response);

​
Build multi-agent systems

Create complex workflows by combining multiple specialized agents: 
import { AgentBuilder } from "@iqai/adk";

// Create specialized sub-agents
const customerAnalyzer = AgentBuilder.create("customer_analyzer")
  .withModel("gemini-2.5-flash")
  .withInstruction("Analyze customer preferences and dietary restrictions")
  .build();

const menuValidator = AgentBuilder.create("menu_validator")
  .withModel("gemini-2.5-flash")
  .withInstruction("Validate menu items against customer preferences")
  .build();

const orderFinalizer = AgentBuilder.create("order_finalizer")
  .withModel("gemini-2.5-flash")
  .withInstruction("Finalize and confirm the order")
  .build();

// Create orchestrator agent
const { runner } = AgentBuilder.create("restaurant_order_system")
  .withModel("gemini-2.5-flash")
  .withSubAgents([customerAnalyzer, menuValidator, orderFinalizer])
  .withQuickSession({ 
    state: {
      customer_preferences: "",
      menu_validation: "",
    }
  })
  .build();

// The root agent will delegate to sub-agents as needed
const response = await runner.ask(
  "I'd like something vegetarian, not too spicy, around $20"
);
The root agent automatically delegates tasks to the appropriate sub-agent based on the query and agent descriptions.

​
Next steps

Now that you’ve built your first agent, explore more advanced features:

Installation guide

Learn about advanced installation options and CLI tools

Core concepts

Understand agents, tools, memory, and sessions

Agent types

Explore different agent types for various use cases

Examples

Browse comprehensive examples in the repository
Remember to keep your API keys secure and never commit them to version control. Use environment variables or secure secret management.

Build docs developers (and LLMs) love

Get started for freeTalk to us