npm package: @krischank/agent-kit
Description: Lightweight, modular agent framework for TypeScript/JavaScript. Turn any LLM into an agent with providers, system prompts, and MCP tools.
Latest version: 0.1.0

# agent-kit

Lightweight agent framework for TypeScript & JavaScript. Turn any LLM into an agent with providers, system prompts, and MCP tools — in a few lines of code.

## Install

```bash
npm install agent-kit
```

## Quick start

```ts
import { createAgent } from 'agent-kit'

const agent = createAgent({
  provider: 'ollama',
  model: 'llama3',
  system: 'You are a helpful assistant.',
})

// Simple chat
const reply = await agent.chat('What is TypeScript?')
console.log(reply)

// Streaming
for await (const chunk of agent.stream('Explain Rust in 3 sentences')) {
  process.stdout.write(chunk)
}
```

## Tools

Define custom tools inline, or connect to MCP servers:

```ts
import { createAgent, mcpTools } from 'agent-kit'
import { readFile } from 'fs/promises'

const agent = createAgent({
  provider: 'ollama',
  model: 'llama3',
  system: 'You are a code assistant with file access.',
  tools: [
    // MCP server
    await mcpTools('http://localhost:3001/sse'),

    // Custom tool
    {
      name: 'read_file',
      description: 'Read a file from disk',
      parameters: {
        path: { type: 'string', description: 'File path to read' },
      },
      execute: async ({ path }) => readFile(path as string, 'utf-8'),
    },
  ],
})

// run() = agentic loop (auto-executes tool calls)
const result = await agent.run('Read package.json and summarize it')
console.log(result.message.content)
console.log(`Used ${result.toolResults.length} tool calls`)
```

## API

### `createAgent(config)`

| Option | Type | Default | Description |
|---|---|---|---|
| `provider` | `string \| Provider` | — | Provider name (`'ollama'`) or custom provider instance |
| `model` | `string` | `'llama3'` | Model name |
| `baseUrl` | `string` | `'http://localhost:11434'` | Provider API base URL |
| `system` | `string \| () => string` | — | System prompt (static or dynamic) |
| `tools` | `Array` | `[]` | Custom tools and/or MCP configs |
| `maxToolRounds` | `number` | `10` | Max tool-call rounds in `run()` |

### Agent methods

- **`agent.chat(input)`** — Single-turn, returns `string`
- **`agent.stream(input)`** — Single-turn streaming, yields `string` chunks
- **`agent.run(input)`** — Agentic loop with auto tool execution, returns `RunResult`

Input can be a `string` (user message) or `Message[]` (full conversation).

### `mcpTools(url)`

Connects to an MCP server, discovers tools, and returns `ToolDefinition[]` ready to use.

```ts
const tools = await mcpTools('http://localhost:3001/sse')
```

### Custom providers

```ts
import { registerProvider, createAgent } from 'agent-kit'

registerProvider('my-provider', (config) => ({
  async chat(messages, tools) {
    // Call your API, return AssistantMessage
  },
  async *stream(messages, tools) {
    // Yield StreamChunk objects
  },
}))

const agent = createAgent({ provider: 'my-provider', model: 'my-model' })
```

## Design principles

- **Minimal surface** — one function to start: `createAgent()`
- **Provider-agnostic** — Ollama built-in, add any provider with `registerProvider()`
- **MCP-native** — first-class MCP tool support
- **Zero dependencies** — only uses `fetch` (built into Node 18+)
- **TypeScript-first** — full type safety, works in plain JS too

## License

MIT