agent-kit

Plug-and-play TypeScript library for LLM agents: providers, agent loop, session memory, and compaction.

Quick start

npm install
copy .env.example .env    # Windows
# cp .env.example .env    # macOS/Linux — then add your API key
npm start

Requires Node.js >= 22.16.

PowerShell (one-off, without .env):

$env:OPENAI_API_KEY = "your-key"
npm start -- "Say hello in one sentence"

Install as a dependency

{
  "dependencies": {
    "@sumedhp21/agent-kit": "file:../path/to/agent"
  }
}

npm install runs prepare and compiles dist/ automatically.

Usage

One import for everything:

import {
  Agent,
  AgentHarness,
  InMemorySessionRepo,
  getModel,
  streamSimple,
} from "@sumedhp21/agent-kit";

Minimal agent loop

import { Agent, getModel } from "@sumedhp21/agent-kit";

const agent = new Agent({
  initialState: {
    systemPrompt: "You are helpful.",
    model: getModel("anthropic", "claude-sonnet-4-20250514"),
  },
});

agent.subscribe((event) => {
  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});

await agent.prompt("Hello!");

Full session + memory

import { AgentHarness, InMemorySessionRepo, NodeExecutionEnv, getModel } from "@sumedhp21/agent-kit";

const session = await new InMemorySessionRepo().create();

const harness = new AgentHarness({
  env: new NodeExecutionEnv({ cwd: process.cwd() }),
  session,
  model: getModel("anthropic", "claude-sonnet-4-20250514"),
  systemPrompt: "You are helpful.",
  tools: [],
});

await harness.prompt("Hello!");
await harness.waitForIdle();

For file-backed sessions, use JsonlSessionRepo.

Cost logging (tokens + INR)

import { AgentHarness, CostLogger, usdToInrRate } from "@sumedhp21/agent-kit";

const costLogger = new CostLogger({ usdToInr: usdToInrRate() });

harness.subscribe((event) => {
  costLogger.handleEvent(event);
  if (event.type === "turn_end") costLogger.printLatestTurn();
});

await harness.prompt("Hello!");
await harness.waitForIdle();
costLogger.printSummary();

// Or: const totals = costLogger.summary();

Set USD_TO_INR=84.5 in .env to control the conversion rate. Each turn is one LLM API call (tool loops produce multiple turns).

Scripts

| Script | Purpose | |--------|---------| | npm start | Run the basic example (reads .env) | | npm run build | Regenerate model catalogs + compile | | npm run compile | Compile TypeScript to dist/ | | npm test | Run tests |

Package layout

src/
├── ai/       LLM providers, streaming, models
├── agent/    Agent loop, harness, session memory, compaction
├── index.ts  Main export
└── node.ts   Node.js helpers (NodeExecutionEnv)
examples/
└── basic-agent/   Runnable starter

Subpath exports

| Import | Purpose | |--------|---------| | @sumedhp21/agent-kit | Everything | | @sumedhp21/agent-kit/node | NodeExecutionEnv + main exports | | @sumedhp21/agent-kit/oauth | OAuth providers | | @sumedhp21/agent-kit/anthropic | Anthropic provider | | @sumedhp21/agent-kit/google | Google provider |

Memory model

No vector database. Memory is:

• Session tree (in-memory or JSONL) with branching
• Compaction when context exceeds limits
• Skills and prompt templates for static context

See docs/ for harness lifecycle details.

API keys

Set in .env or environment variables: ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.