Stark-Kit / Docs

Quick Start

From zero to a running AI agent in under five minutes. This guide covers installation, API key setup, and a minimal WeatherBot example.

1. Install

Install Stark-Kit and its peer dependency zod using your package manager of choice.

bash
bun add @mehularora/stark-kit zod
Note: The examples in this guide use bun. You can also use npm, pnpm, or yarn — the API is identical.

2. Set up your API key

Stark-Kit reads provider keys from environment variables automatically. Create a .env file in your project root:

.env
# .env
ANTHROPIC_API_KEY=your_key_here

Then install dotenv and import it at the top of your entry file so the variables are loaded before Stark-Kit initialises:

bash
# Install dotenv for loading .env files at runtime
bun add dotenv

Add import "dotenv/config"; as the first line of your script (before any Stark-Kit imports). See the full example below.

3. Write a minimal agent

Here is the complete WeatherBot — a single file that installs a tool, configures an agent, and runs the loop:

weather-bot.ts
import "dotenv/config";
import { Agent, run, defineTool, ClaudeProvider } from "@mehularora/stark-kit";
import z from "zod";


// Initialize a provider — reads ANTHROPIC_API_KEY automatically
const provider = new ClaudeProvider();


// Define a typed tool
const weatherTool = defineTool({
  name: "getWeather",
  description: "Get the current weather for a city.",
  parameters: z.object({
    city: z.string().describe("The name of the city, e.g. Tokyo"),
  }),
  execute: async ({ city }) => {
    return `The weather in ${city} is sunny and 22°C.`;
  },
});


// Configure the agent
const agent = new Agent({
  name: "WeatherBot",
  provider,
  instructions: "You are a helpful assistant. Keep answers brief.",
  tools: [weatherTool],
});


// Execute the run loop
const response = await run({
  agent,
  messages: "What's the weather in Tokyo?",
});


if (response.status === "complete") {
  console.log(response.content);
  // → "The weather in Tokyo is sunny and 22°C."
}

What just happened?

When you called run(), the run loop:

  1. 1Sent the user message and the agent's system instructions to Claude.
  2. 2Claude decided to call the getWeather tool with { city: "Tokyo" }.
  3. 3The run loop executed your tool's execute() function and got back the weather string.
  4. 4It sent the tool result back to Claude as part of the conversation.
  5. 5Claude composed its final answer and the loop returned a RunResult with status "complete".
Tip: The run loop repeats steps 1–4 until the model stops calling tools or maxSteps is exceeded (default: 10). This is the core of how agentic systems work.

Next steps

Now that you have a working agent, explore the rest of the documentation: