ai-agent-starter-kit

v1.0.0

Published

3 months ago

A developer-friendly toolkit for building AI agents with memory, tool execution, and automation workflows.

🤖 AI Agent Starter Kit

Build powerful AI agents in minutes, not months.

A production-ready TypeScript framework for creating AI agents with persistent memory, tool execution, and automation workflows — zero AI vendor lock-in.

Quick Start · Examples · Documentation · Contributing

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   $ npx tsx cli/run-agent.ts run examples/research-agent.ts     │
│                                                                 │
│   🤖 AI Agent Starter Kit                                       │
│   ✓ Agent loaded: research-agent                                │
│   ▶ Task: Research TypeScript best practices                    │
│                                                                 │
│   ⚡ Calling tool: httpFetch                                     │
│   ⚡ Calling tool: extractKeywords                               │
│   ⚡ Calling tool: summarize                                     │
│   ✓ Task completed successfully.                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

🎥 Visual Demo

Watch the AI Agent Starter Kit in action! In the terminal session below, our Streaming Mode provides lightning-fast execution feedback while the robust Tool Execution loop natively bridges LLM logic with local systems. Notice how the agent automatically invokes httpFetch to retrieve live data, pipelines the response into extractKeywords, and distills it via summarize without any intermediate human intervention.

Live Execution Example:

$ npx tsx cli/run-agent.ts run examples/research-agent.ts --task "Research TypeScript" --verbose

┌──────────────────────────────────────────┐
│       🤖  AI Agent Starter Kit  🤖       │
│         CLI Runner v1.0.0                │
└──────────────────────────────────────────┘

✓ Agent loaded: research-agent
▶ Task: Research TypeScript

  ℹ Agent "research-agent" starting task.
  ⚡ Calling tool: httpFetch
  ← Tool "httpFetch" result: success
  ⚡ Calling tool: extractKeywords
  ← Tool "extractKeywords" result: success
  ⚡ Calling tool: summarize
  ← Tool "summarize" result: success
  ✓ Task completed successfully.

🤔 Why AI Agent Starter Kit?

Most AI agent frameworks are bloated, opinionated, or locked to a single LLM provider. This toolkit takes a different approach:

| Problem | Our Solution | |---------|-------------| | 🏗️ Complex setup with dozens of dependencies | 3 core files, zero bloat — start building in seconds | | 🔒 Locked to OpenAI / Anthropic / etc. | LLM-agnostic — plug in ANY provider (or none at all) | | 🧠 Agents forget everything between runs | Persistent JSON memory + Vector Memory with cosine-similarity search | | 🔧 Hard to give agents real capabilities | Tool framework with validation, built-in tools, and easy custom tools | | 🤖 No real LLM integration out of the box | Native Claude SDK example with full tool-use loop | | ❓ No tests, no CI, "works on my machine" | 40+ Vitest tests, GitHub Actions CI on Node 18/20/22 | | 📦 "Hello world" agents that can't do real work | 5 production-style example agents including multi-agent orchestration |

✨ Features

🧠 Persistent Memory + Vector Search

// Key-value memory persists across sessions
agent.memory.set("user_preference", "dark_mode");
agent.memory.get("user_preference"); // "dark_mode"

// Semantic vector memory with cosine similarity
const vm = new VectorMemory();
await vm.saveMemory("TypeScript is great");
const results = await vm.searchMemory("JavaScript");

🔧 Tool Framework

// Give agents real-world capabilities
const tool: Tool = {
  name: "sendEmail",
  description: "Send an email",
  parameters: [{ name: "to", type: "string", required: true }],
  execute: async (params) => {
    // Your implementation here
    return { success: true, data: "Sent!" };
  }
};

⚡ CLI Runner + Interactive Chat

# Run any agent from the terminal
npx tsx cli/run-agent.ts run my-agent.ts \
  --task "Analyse the codebase" \
  --verbose

# Interactive mode — multi-turn chat
npx tsx cli/run-agent.ts run my-agent.ts -i

🤖 Native Claude Integration

import { ClaudeAgent } from "./examples/claude-agent.js";

const agent = new ClaudeAgent({
  name: "claude-assistant",
  systemPrompt: "You are a helpful agent.",
});
// Full tool-use loop handled automatically
const result = await agent.run("What date is it?");

Built-in Tools

| Tool | Description | Use Case | |------|-------------|----------| | 📖 readFile | Read filesystem files | Config loading, code analysis | | ✍️ writeFile | Write content to files | Report generation, code output | | 🌐 httpFetch | HTTP/HTTPS requests | API calls, web scraping | | 💻 shellExec | Execute shell commands | Build scripts, system tasks | | 🧠 VectorMemory | Embedding-based semantic search | Long-term agent recall |

🚀 Quick Start

Installation

# Clone the repo
git clone https://github.com/MawGyi/ai-agent-starter-kit.git
cd ai-agent-starter-kit

# Install dependencies
npm install

Run Your First Agent

# Copy the example env file
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY (only needed for the Claude example)

# Run the research agent
npx tsx cli/run-agent.ts run examples/research-agent.ts \
  --task "Research TypeScript best practices" --verbose

# Run the Claude-powered agent (requires ANTHROPIC_API_KEY)
npx tsx cli/run-agent.ts run examples/claude-agent.ts \
  --task "What is TypeScript?" --verbose

# Interactive multi-turn chat mode
npx tsx cli/run-agent.ts run examples/research-agent.ts -i

Create Your First Agent (5 Lines)

// my-agent.ts
import { Agent } from "./agent-core/index.js";

const agent = new Agent({
  name: "my-first-agent",
  description: "My custom AI agent",
  systemPrompt: "You are a helpful assistant.",
});

export default agent;

npx tsx cli/run-agent.ts run my-agent.ts --task "Hello world"

🎓 Example Agents

🔬 Research Agent

Gathers information, extracts keywords, and generates summaries.

Fetch data → Extract keywords → Summarise findings → Store in memory → Return report

Custom tools: summarize, extractKeywords Demonstrates: Multi-step reasoning, HTTP fetching, memory persistence

⚙️ Automation Agent

Executes workflow steps sequentially with error handling and resume support.

Load workflow → Execute steps → Track progress → Handle errors → Send notification

Custom tools: notify, transformData Demonstrates: Sequential workflows, resumability via memory, error recovery

💻 Coding Agent

Analyses source code structure and generates TypeScript boilerplate.

Read source files → Analyse structure → Generate boilerplate → Compile report

Custom tools: analyseCode, generateBoilerplate Demonstrates: File I/O, static analysis, code generation

🤖 Claude Agent (Anthropic SDK)

Real LLM integration with full tool-use loop.

User prompt → Claude reasons → tool_use request → Agent executes → tool_result → Claude answers

Requires: ANTHROPIC_API_KEY environment variable Demonstrates: LLM subclassing, Anthropic SDK, dynamic tool schema mapping, multi-turn tool-use

🏗️ Multi-Agent Orchestrator

A manager agent delegates sub-tasks to specialist agents.

Complex task → Manager splits work → Research Agent runs → Coding Agent runs → Combined result

Demonstrates: Agent-to-agent communication, tool-wrapped agents, task decomposition

🏗️ Building Custom Agents

Level 1: Simple Agent (No Subclassing)

import { Agent } from "./agent-core/index.js";

const agent = new Agent({
  name: "simple-agent",
  tools: [myCustomTool],
});

const result = await agent.run("Do something useful");

Level 2: Custom Tools

import { Agent, type Tool } from "./agent-core/index.js";

const weatherTool: Tool = {
  name: "getWeather",
  description: "Get current weather for a city",
  parameters: [
    { name: "city", type: "string", description: "City name", required: true },
  ],
  execute: async (params) => {
    const response = await fetch(`https://api.weather.com/${params.city}`);
    const data = await response.json();
    return { success: true, data };
  },
};

const agent = new Agent({
  name: "weather-agent",
  tools: [weatherTool],
});

export default agent;

Level 3: Full Custom Agent (Subclassing)

import { Agent, type AgentConfig } from "./agent-core/index.js";

class DataPipelineAgent extends Agent {
  constructor() {
    super({
      name: "data-pipeline",
      description: "ETL pipeline with validation and error recovery",
    });
  }

  protected override async executeTask(task: string): Promise<unknown> {
    // Step 1: Extract
    const raw = await this.callTool("readFile", { path: "data/input.csv" });

    // Step 2: Transform
    this.memory.set("pipeline:raw_count", raw.data?.length ?? 0);
    const processed = transform(raw.data);

    // Step 3: Load
    await this.callTool("writeFile", {
      path: "data/output.json",
      content: JSON.stringify(processed),
    });

    return { records: processed.length, status: "complete" };
  }
}

export default new DataPipelineAgent();

Level 4: LLM Integration

// The framework is LLM-agnostic — bring your own provider
class SmartAgent extends Agent {
  protected override async executeTask(task: string): Promise<unknown> {
    // Use OpenAI, Anthropic, Ollama, or any LLM
    const response = await openai.chat.completions.create({
      model: "gpt-4",
      messages: [
        { role: "system", content: this.systemPrompt },
        { role: "user", content: task },
      ],
      tools: this.tools.describe(), // Auto-generate tool definitions
    });

    // Execute tool calls from LLM response
    for (const toolCall of response.tool_calls) {
      await this.callTool(toolCall.name, toolCall.arguments);
    }

    return response.choices[0].message;
  }
}

🏛️ Architecture

┌─────────────────────────────────────────────────────┐
│                    CLI Runner                       │
│              cli/run-agent.ts                       │
│                                                     │
│    $ ai-agent run <file> --task "..." --verbose     │
└────────────────────────┬────────────────────────────┘
                         │  dynamic import
                         ▼
┌─────────────────────────────────────────────────────┐
│                    Agent Core                       │
│                 agent-core/                         │
│                                                     │
│  ┌─────────────┐  ┌───────────┐  ┌──────────────┐  │
│  │    Agent     │  │  Memory   │  │    Tool      │  │
│  │             │──│           │  │   Registry   │  │
│  │  • run()    │  │  • get()  │  │  • register()│  │
│  │  • callTool │  │  • set()  │  │  • invoke()  │  │
│  │  • hooks    │  │  • search │  │  • validate  │  │
│  └─────────────┘  └───────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────┘

Agent Lifecycle

agent.run(task)
  │
  ├── 1. 🎬 onTaskStart hook
  ├── 2. 💾 Store task in memory
  ├── 3. ⚙️  executeTask()
  │       ├── callTool() → ToolRegistry.invoke()
  │       ├── memory.set() / memory.get()
  │       └── return result
  ├── 4. 📊 Compile AgentTaskResult
  ├── 5. 🏁 onTaskComplete hook
  └── 6. ✅ Return result with full execution log

📖 Full architecture docs: docs/architecture.md

📁 Project Structure

ai-agent-starter-kit/
├── agent-core/             # Core framework (the 🧠 of the toolkit)
│   ├── agent.ts            # Agent class — lifecycle, hooks, execution
│   ├── memory.ts           # Persistent JSON memory with namespaces
│   ├── tools.ts            # Tool registry + 4 built-in tools
│   ├── vectorMemory.ts     # Embedding-based vector memory with cosine similarity
│   ├── config.ts           # Environment variable validation
│   └── index.ts            # Public API barrel exports
├── cli/
│   └── run-agent.ts        # CLI entry point (run / list-tools / interactive mode)
├── examples/
│   ├── research-agent.ts   # 🔬 Multi-step research workflow
│   ├── automation-agent.ts # ⚙️  Sequential task automation
│   ├── coding-agent.ts     # 💻 Code analysis & generation
│   ├── claude-agent.ts     # 🤖 Native Anthropic Claude integration
│   └── multi-agent-orchestrator.ts # 🏗️ Multi-agent task delegation
├── tests/                  # Vitest unit tests (40+ tests)
│   ├── agent.test.ts
│   ├── memory.test.ts
│   └── tools.test.ts
├── .github/workflows/ci.yml # GitHub Actions CI (Node 18/20/22)
├── .env.example            # Environment variable template
├── docs/
│   ├── architecture.md     # Full system architecture docs
│   └── integrations.md     # LLM integration guide
├── vitest.config.ts
├── package.json
├── tsconfig.json
├── LICENSE                 # MIT
├── CONTRIBUTING.md
└── README.md

🛠️ Development

# Type-check (zero errors expected)
npm run typecheck

# Run the full test suite (40+ tests)
npm run test

# Run tests in watch mode during development
npm run test:watch

# Build to dist/
npm run build

# Run any agent in dev mode
npm run run-agent -- run examples/research-agent.ts --verbose

🗺️ Roadmap

[x] Test suite — 40+ Vitest unit tests with CI running on Node 18/20/22
[x] LLM provider adapters — Native Anthropic Claude SDK with full tool-use loop
[x] Agent-to-agent communication — Multi-agent orchestration example
[x] Vector memory — Cosine-similarity semantic search with pluggable embeddings
[x] Interactive CLI — Multi-turn chat mode with --interactive flag
[ ] Plugin system — Install tools from npm packages
[ ] Streaming execution — Real-time tool output streaming
[ ] Web UI dashboard — Visual agent monitoring and management
[ ] SQLite / Redis memory backends — Production-grade persistence
[ ] Agent templates — npx create-ai-agent scaffolding CLI

🤝 Contributing

We love contributions! Whether it's a new tool, an example agent, or a documentation fix — every PR makes this toolkit better for everyone.

See CONTRIBUTING.md for guidelines.

# Fork → Clone → Branch → Code → PR
git checkout -b feature/awesome-tool
# ... make changes ...
npm run typecheck  # Ensure zero errors
# Submit PR 🚀

📄 License

MIT — use it, modify it, ship it. See LICENSE for details.

⭐ If this project helps you build AI agents faster, give it a star!

Built with ❤️ for the AI developer community

Report Bug · Request Feature · Discussions