Overview
This example demonstrates the fundamentals of creating an AI agent with ADK-TS. You’ll learn how to:- Structure your agent code in a recommended folder layout
- Define structured output using Zod schemas
- Get fully-typed responses from your agent
This is the “Hello World” of ADK-TS, but it showcases best practices you’ll use in production applications.
Complete Example
import { AgentBuilder } from "@iqai/adk";
import z from "zod/v4"; // Ensure its v4!
export function getRootAgent() {
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"),
});
return AgentBuilder.withModel(
process.env.LLM_MODEL || "gemini-3-flash-preview",
)
.withOutputSchema(outputSchema)
.build();
}
Always use
zod/v4 for schema validation in ADK-TS. The framework is optimized for Zod v4’s features.import dedent from "dedent";
import { getRootAgent } from "./agents/agent";
async function main() {
const { runner } = await getRootAgent();
const question = "Give me stats about France";
const response = await runner.ask(question);
console.log(`👤 User: ${question}`);
console.log(
dedent`
🤖 Agent:
🌍 Country: ${response.country}
📍 Capital: ${response.capital}
👥 Population: ${response.population ? response.population.toLocaleString() : "N/A"}
🎉 Fun fact: ${response.funFact}
`,
);
}
main().catch(console.error);
Expected Output
Key Concepts
Structured Output with Zod
ThewithOutputSchema() method ensures your agent returns data in a specific format:
- Type Safety: TypeScript knows exactly what fields are available
- Validation: Responses are automatically validated against your schema
- Documentation: Descriptions help the LLM understand what to generate
Recommended Folder Structure
As your application grows, you’ll add
tools.ts, plugins.ts, and other files to the agents/ folder. This structure keeps your code organized and maintainable.Model Selection
You can use any supported LLM provider:Next Steps
Tools & State
Add custom tools and manage agent state
Multi-Agent Systems
Coordinate multiple agents to handle complex tasks