aikit-agent

TypeScript/Node.js scaffold for building independently deployable domain Agent services.

Quick Start

Install from npm:

npm install aikit-agent
npx aikit-agent --help
npx aikit-agent run support-ticket "What should we do for ticket T1001?"
npx aikit-agent serve support-ticket,demo-support --port 3000

Or install globally:

npm install -g aikit-agent
aikit-agent --help
aikit-agent run support-ticket "What should we do for ticket T1001?"
aikit-agent serve support-ticket,demo-support --port 3000

For local source development:

npm install
npm run build
node dist/src/cli.js --help
node dist/src/cli.js run support-ticket "What should we do for ticket T1001?"
node dist/src/cli.js eval support-ticket
node dist/src/cli.js serve support-ticket --port 3000

In another shell:

node -e "const r=await fetch('http://127.0.0.1:3000/run',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({prompt:'What should we do for ticket T1001?'})}); console.log(await r.text())"

HTTP and Web UI

The HTTP server can run as an API-only backend:

npm run build
node dist/src/cli.js serve support-ticket --port 3000

HTTP endpoints:

• GET /health
• GET /domains
• GET /domain
• GET /domain?domain=<name>
• POST /run with JSON body { "prompt": "Where is order A1001?" }
• POST /run with JSON body { "domain": "support-ticket", "prompt": "..." } when one server hosts multiple domains

The Web UI is a separate static directory and is not included in the default npm package. Mount it only when needed:

npm run build
npm run build:web
node dist/src/cli.js serve support-ticket --port 3000 --web-dir web

Then open http://127.0.0.1:3000/.

To host multiple domains behind one HTTP/Web server, pass a comma-separated list. The first domain is the default, and the Web UI shows a domain selector:

npm run build
npm run build:web
node dist/src/cli.js serve support-ticket,demo-support --port 3000 --web-dir web

For independent frontend deployment, serve web/ from any static host and point it at the backend with apiBase:

http://127.0.0.1:8080/?apiBase=http://127.0.0.1:3000

The frontend calls only HTTP APIs; it does not import backend runtime modules.

Create a Domain

npm run dev -- new my-domain
npm run dev -- new my-domain --force

Generated files:

• domains/my-domain/
• docs/demos/my-domain/README.md

Runtime Model Config

Domain code defines tools and behavior. Runtime model settings can be changed in domains/<domain>/config/local.json without rebuilding domain code. Restart the running CLI/server after editing the JSON file.

{
  "model": {
    "provider": "deepseek",
    "id": "deepseek-v4-flash",
    "apiKeyEnv": "DEEPSEEK_API_KEY",
    "baseURL": "https://api.deepseek.com"
  }
}

Supported providers are mock, anthropic and deepseek. If config/local.json is missing, the model config from domains/<domain>/index.ts or index.mjs is used. The legacy string form, for example { "model": "mock-tool-model" }, only overrides the model id and keeps the provider from domain code.

MCP

npm run build
node dist/src/cli.js mcp support-ticket
npm run mcp:smoke -- support-ticket "What should we do for ticket T1001?"

Domain code lives under domains/<domain>/. The invariant runtime lives under src/.

Polished demo tutorials live under docs/demos/<domain>/.

Provider config supports deterministic mock, Anthropic through @ai-sdk/anthropic, and DeepSeek through the OpenAI-compatible AI SDK adapter. Real-provider domains must provide the matching API key through the environment, or set a custom apiKeyEnv.

Running With a Real Provider

The demos can use mock so local runs are deterministic, fast and do not require secrets. To try a real model provider, switch a domain config from mock to anthropic or deepseek and provide an API key through the environment.

Example for domains/support-ticket/index.ts:

config: {
  name: "support-ticket",
  model: {
    provider: "anthropic",
    id: "claude-3-5-haiku-latest",
    apiKeyEnv: "ANTHROPIC_API_KEY"
  }
}

Then run:

export ANTHROPIC_API_KEY="..."
npm run build
node dist/src/cli.js run support-ticket "What should we do for ticket T1001?"

DeepSeek example:

config: {
  name: "support-ticket",
  model: {
    provider: "deepseek",
    id: "deepseek-v4-flash",
    apiKeyEnv: "DEEPSEEK_API_KEY",
    baseURL: "https://api.deepseek.com"
  }
}

Then run:

export DEEPSEEK_API_KEY="..."
npm run build
node dist/src/cli.js run support-ticket "What should we do for ticket T1001?"

Only provider config and environment variables should change. Domain tools, eval cases, CLI, HTTP and MCP entrypoints should continue to use the same runtime contract.

Release Preflight

npm audit --registry=https://registry.npmjs.org
npm run check
npm run build:web
npm run build
npm run dev -- eval support-ticket
npm run mcp:smoke -- support-ticket "What should we do for ticket T1001?"
npm --cache /tmp/aikit-agent-npm-cache pack --dry-run

The default package is the core backend package. It includes dist/, curated demo domains, docs and deployment files. It intentionally excludes web/, web/node_modules, frontend build caches and .ai/context so the Web UI can be used on demand without inflating the core package.

Publishing SOP:

• docs/release/npm-publish-sop.md

Architecture notes:

• docs/architecture/invariant-layer.md
• docs/architecture/optional-integrations.md