Tools & State Management

import { createTool } from "@iqai/adk";
import * as z from "zod";

export const addItemTool = createTool({
	name: "add_item",
	description: "Add an item to the shopping cart",
	schema: z.object({
		item: z.string().describe("Item name"),
		quantity: z.number().default(1).describe("Quantity to add"),
		price: z.number().describe("Price per item"),
	}),
	fn: ({ item, quantity, price }, context) => {
		const cart: { item: string; quantity: number; price: number }[] =
			context.state.get("cart", []);
		const existingItemIndex = cart.findIndex(
			(cartItem) => cartItem.item === item,
		);

		let updatedCart: { item: string; quantity: number; price: number }[];
		if (existingItemIndex > -1) {
			updatedCart = cart.map((cartItem, index) => {
				if (index === existingItemIndex) {
					return { ...cartItem, quantity: cartItem.quantity + quantity };
				}
				return cartItem;
			});
		} else {
			updatedCart = [...cart, { item, quantity, price }];
		}

		context.state.set("cart", updatedCart);
		context.state.set("cartCount", updatedCart.length);

		const total = updatedCart.reduce(
			(sum, cartItem) => sum + cartItem.quantity * cartItem.price,
			0,
		);

		return {
			success: true,
			item,
			quantity,
			cartTotal: total,
			message: `Added ${quantity}x ${item} to cart`,
		};
	},
});

export const viewCartTool = createTool({
	name: "view_cart",
	description: "View current shopping cart contents",
	fn: (_, context) => {
		const cart = context.state.get("cart", []);
		const total = cart.reduce(
			(sum, item) => sum + item.quantity * item.price,
			0,
		);

		return {
			cart,
			total,
			itemCount: cart.reduce((sum, item) => sum + item.quantity, 0),
			message:
				cart.length > 0
					? `Cart has ${cart.length} different items`
					: "Cart is empty",
		};
	},
});

• context.state: Get and set state variables
• context.session: Access session metadata
• context.saveArtifact(): Save files and artifacts
• context.memory: Query long-term memory

import { AgentBuilder } from "@iqai/adk";
import dedent from "dedent";
import { addItemTool, viewCartTool } from "./tools";

export function getRootAgent() {
	const initialState = {
		cart: [],
		cartCount: 0,
	};

	return AgentBuilder.create("shopping_cart_agent")
		.withModel(process.env.LLM_MODEL || "gemini-3-flash-preview")
		.withInstruction(
			dedent`
			You are a shopping cart assistant. Help users manage their cart.

			Current cart state:
			- Items in cart: {cartCount}
			- Cart contents: {cart}

			You can add items and view the cart. Always be helpful with pricing and quantities.
		`,
		)
		.withTools(addItemTool, viewCartTool)
		.withQuickSession({ state: initialState })
		.build();
}

import { ask } from "../utils";
import { getRootAgent } from "./agents/agent";

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

	const questions = [
		"Add 2 apples to my cart at $1.50 each",
		"Add 1 banana for $0.75",
		"Show me my complete cart with total",
	];

	for (const question of questions) {
		await ask(runner, question);
	}
}

main().catch(console.error);

node index.ts