agentkit-js

TypeScript agent runtime with WASM sandboxing, prompt-cache optimization, and parallel quality runners.

Build production-grade AI agents in TypeScript — code-execution agents, tool-calling agents, or multi-path reasoning pipelines — with built-in cost controls and Cloudflare Workers deployment.

# For Anthropic (Claude)
npm add @agentkit-js/core @anthropic-ai/sdk

# For OpenAI / compatible endpoints (Ollama, vLLM, etc.)
npm add @agentkit-js/core openai

📚 Docs site: https://telleroutlook.github.io/agentkit-js/ · Getting started in 5 min: docs/guides/getting-started.md · Benchmarks: docs/benchmarks.md · Changelog: CHANGELOG.md · API stability: docs/strategy/api-stability.md · Strategy memo: docs/strategy/2026-06-competitiveness.md · Trust Page (D4): docs/strategy/trust.md · Enterprise security face: docs/strategy/security-face.md

🤝 Looking for a co-maintainer. @agentkit-js/core@1.0.0 is on the calendar for 2026-12-15. If you ship to the Vercel AI SDK / Mastra / Claude Agent SDK / OpenAI Agents JS / Cloudflare Agents / LangGraph.js communities and want npm-publish + merge rights, see CONTRIBUTING.md and GOVERNANCE.md. Release cadence ledger: docs/strategy/release-cadence-log.md. Sandbox-escape SLA drill log: docs/strategy/security-drill-log.md.

Comparison

There are several mature TypeScript agent frameworks. Here is an honest assessment of where agentkit-js fits.

Last verified: 2026-06-13. Each ⚠️/❌ cell links to its source on the column header's project. The "sandbox" rows have been re-framed (D2, 2026-06-13) so that having some sandbox is no longer the differentiator — three competitors now ship one. The remaining axes — isolation tier composability, cross-runtime neutrality, offline closure — are what no other framework offers in one package.

Where competitors are stronger

• Vercel AI SDK — If you're building a chat UI with Next.js, use this. The React hooks (useChat, useAgent), DurableAgent for stateful/resumable workflows (AI SDK 6), native MCP support, and DevTools panel are all best-in-class. 57M monthly downloads.

• LangChain/LangGraph.js — If you need 300+ integrations (vector stores, document loaders, obscure providers) or graph-based durable workflows with checkpointing and human-in-the-loop, LangGraph is battle-tested at LinkedIn, Uber, and GitLab scale.

• Mastra — Best eval framework (12+ built-in scorers including trajectory and tool accuracy). Strong developer onboarding. Their "Observational memory" pattern was first-mover; agentkit-js now ships an equivalent (ObservationalMemory) plus extra prompt-cache-aware compression — see docs/guides/observational-memory.md.

• Cloudflare Agents SDK — If you're building on Cloudflare specifically, Durable Objects give you stateful agents with persistent scheduling that nothing else matches natively.

• OpenAI Agents JS — If your stack is OpenAI-only and you want first-party support, the cleanest path. The 2026-04 release added SandboxAgent with Unix-local, Docker, and hosted clients; for OS-level isolation backed by OpenAI itself, this is the path of least resistance.

Where agentkit-js is differentiated

• Three isolation tiers under one swappable interface (D2, 2026-06-13). OpenAI Agents JS now ships SandboxAgent (Unix-local / Docker / hosted) and Mastra ships Workspace providers (E2B / Daytona / Modal / Blaxel / Railway). The differentiator is no longer "has a sandbox" — it's that agentkit-js exposes three tiers (VmKernel in-process, QuickJSKernel / PyodideKernel / WasmtimeKernel true WASM, RemoteSandboxKernel microVM) under one Kernel interface, swap them with one line at call time, and apply one CapabilityManifest (network/fs/env/cpu/memory) across every tier. Competitors give you one tier wired to one provider. See docs/kernels/comparison.md for the decision tree.

• Cross-runtime neutrality. Cloudflare's sandbox is fast on Cloudflare. Mastra's providers are SaaS. agentkit-js kernels run on Node, on any edge runtime, in a browser tab, and on a laptop with the network unplugged — same Kernel API, same security manifest. This is the structural advantage no platform-bound competitor can match.

• Offline / air-gapped closure. @agentkit-js/model-local (node-llama-cpp + grammar-constrained tool calls + multi-mirror downloads HF / hf-mirror / ModelScope) plus a WASM kernel = full agent loop with zero outbound traffic. For compliance-bound and air-gapped deployments, no other framework gives you this without writing the integration yourself.

• Durable runtime — Same KvBackend powers checkpoints, the SSE event log, and structured memory. Four production backends ship out of the box (Cloudflare KV / Durable Objects / Redis / Upstash REST). A paused await_human_input survives worker recycle for hours/days; POST /resume is stateless. See docs/guides/durable-runtime.md.

• Quality runners — Self-consistency with answer extraction (boxed / last-line / custom), reflect-refine, budget forcing ("Wait" prefill), and parallel fork-join are not shipped as first-class APIs by any competitor.

• Anthropic prompt-cache optimization — Framework actively manages cache_control breakpoint placement across multi-turn history, supports the 1-hour extended TTL (ttl:"1h"), and reports per-TTL cache usage. Competitors pass through or validate limits but do not optimise placement.

• Speculative tool execution — Read-only, idempotent tools are pre-executed ahead of write barriers within a DAG step. The scheduler is awakened by $<callId> dependency references in the system prompt, enabling true parallel + ordered hybrid scheduling. No competitor implements this.

• GenAI semantic conventions — OtelBridge emits standard gen_ai.* attributes (Datadog / Honeycomb / Grafana GenAI view compatible) alongside legacy names, switchable via semconvMode.

• Observational Memory + cache-stable prefix (A1) — Background "observer" model continuously compresses history into ranked observation paragraphs. The compressed prefix is byte-stable so Anthropic prompt cache hits stay hot across observations — Mastra's reference work has no equivalent. ~22% of baseline tokens on a 50-turn synthetic trace; see examples/benchmarks/observational-memory.mjs.

• Time-travel debugger (A2) — @agentkit-js/devtools exposes the existing EventLog + Checkpointer data through a navigable step timeline + "fork from any step" UI. LangGraph Studio's headline feature, shipped as a tiny opt-in package (logic core ~250 LOC, React UI optional).

• Skills + lifecycle hooks (A3) — SkillRegistry for progressive instruction/tool disclosure (Claude Agent SDK / CrewAI v1.12 convention). ToolPostHook chain (redact, truncate, audit) sits beside the existing ToolGuardrail — pre/post symmetry without confusing block vs transform semantics.

• Multi-criterion LLM judges (A4) — judgeScorer extends llmJudge with weighted criterion-level scoring + configurable scale. Two built-in judges (trajectoryQualityJudge, answerCompletenessJudge) work with any cheap Model adapter so judges run on Haiku/Doubao while the agent stays on Sonnet/Opus.

• Reproducible benchmarks — Every percentage in this README (−37%, 72→90%, −85%, −84%) is verified by an offline benchmark in examples/benchmarks/. Run pnpm bench to reproduce. CI fails the PR if any number drifts outside its tolerance.

Honest caveats

agentkit-js is early-stage. The differentiating features (code execution kernels, durable runtime, quality runners, speculative scheduling) are technically novel but also niche — most teams pick a framework based on ecosystem breadth and documentation volume, where the mature options above win. Choose agentkit-js when sandboxed code execution, durable agent runs, prompt-cache cost control, or output quality runners are first-order concerns.

Verified status

Related MCP server: Code Executor MCP Server

Features

• Two agent modes — CodeAgent (writes + executes code) and ToolCallingAgent (native tool_use)

• Code execution — three isolation tiers — VmKernel (node:vm, in-process dev/test), QuickJSKernel / PyodideKernel / WasmtimeKernel (true WASM, language-level isolation, edge-safe), RemoteSandboxKernel (E2B / Cloudflare Sandbox microVM, full process isolation). Mix tiers via factory.createKernel().

• Programmatic Tool Calling (PTC) — ProgrammaticOrchestrator executes model-generated scripts inside any kernel; callTool() calls registered tools without surfacing intermediate results to the context (−37% tokens). Self-hosted alternative to Anthropic's managed PTC container.

• Prompt-cache optimization — MessageAssembler builds cache-stable prefixes; Anthropic cache_control breakpoints respect the 4-breakpoint limit, per-chunk token thresholds, and the 1-hour extended TTL (ttl:"1h"); per-TTL usage metering (5m vs 1h); OpenAI automatic prefix cache hit tracking

• Tool deferred loading — deferLoading: true on any tool (or McpToolCollection.deferAll()) excludes its schema from the system prefix and loads on-demand via Anthropic Tool Search (−85% tokens for large MCP server collections)

• Tool Use Examples — inputExamples on any tool maps to Anthropic's input_examples wire field (72%→90% parameter accuracy)

• Context editing — assembler.editToolResults({ maxTokens, keepRecent }) truncates old tool outputs reversibly without breaking conversation structure (+29% task performance, −84% tokens on web search)

• Cross-session Memory Tool — createMemoryTool({ backend }) gives agents persistent read/write/list/delete memory backed by any KvBackend (Cloudflare KV, Redis, in-memory Map)

• Quality runners — majority-vote self-consistency with answer extraction (boxed / last-line / custom hook), critique-refine cycles, "Wait" prefill budget forcing, parallel fork-join with synthesis

• DAG scheduling — independent tool calls execute concurrently via Scheduler; read-only tools speculatively pre-execute ahead of write barriers; $<callId> dependency syntax in system prompt enables true data-dependency ordering; wired into ToolCallingAgent by default

• Long-history compaction — agent.assembler.compact(model, keepRecentSteps) summarises old steps; inject a custom MessageAssembler via assembler option

• Production resilience — automatic exponential backoff + jitter retry for 429 / 5xx / network errors on all model adapters; configurable via RetryPolicy

• Evals framework — runEval() with 16 built-in scorers covering correctness (exactMatch, toolCallAccuracy, trajectoryValidity, finalAnswerLength, guardrailCompliance), faithfulness, relevance, recovery, efficiency, constraints, plus two multi-criterion JudgeScorer judges (trajectoryQualityJudge, answerCompletenessJudge)

• Evaluation harness (@agentkit-js/evals-runner) — runEvaluation() plus agentkit evals run CLI: multi-model × multi-suite × multi-seed Pareto reports over (accuracy, cost, p95 wall). Six reference suites cover the gaps single-task benchmarks miss (long-context recall, multi-turn memory, agent trajectory, latency-under-budget, cost-per-correct, tool-sequence). Built-in paired statistics (McNemar exact / Wilson CI / paired bootstrap / G1 gate) match scipy reference values to ±1e-7. All synthetic fixtures — no overlap with public training corpora.

• Code-mode MCP server (@agentkit-js/mcp-server) — createCodeModeServer() collapses N downstream tools into a docs_search + execute_code two-tool MCP surface. At 30 tools the bootstrap-token cost drops to 13.6% of direct MCP (codemode-lite reported 53%); pairs with any agentkit kernel for unified security policy.

• MCP Portal — federate N upstream servers behind one neutral two-tool surface (D1, 2026-06-13) — createPortalServer() wraps multiple ToolRegistry / MCP upstreams (filesystem + GitHub + memory + …) into one code-mode face. Bootstrap stays O(1) regardless of how many upstreams are federated; at 5 servers × 30 tools = 150 tools, the Portal is 3.1% of direct multi-MCP and 19.8% of code-mode-per-server (examples/benchmarks/portal-tokens.mjs). One CapabilityManifest spans every upstream — the audit boundary platform-bound Portals (Cloudflare's announced version) cannot give you across heterogeneous providers. See examples/mcp-portal/.

• AI SDK + Mastra + Claude Agent SDK + OpenAI Agents JS plugin packages (@agentkit-js/aisdk, @agentkit-js/mastra-sandbox, @agentkit-js/claude-agent-sdk, @agentkit-js/openai-agents) — drop agentkit's WASM kernels into Vercel AI SDK 4–6 (sandboxedJsTool, codeModeTool), Mastra (agentkitMastraSandbox), Anthropic Claude Agent SDK (sandboxedJsClaudeTool, codeModeClaudeTool), or OpenAI Agents JS (sandboxedJsAgentTool, codeModeAgentTool) without an external sandbox provider.

• Observability — OtelBridge maps AgentEvent streams to OTel-compatible spans; emits gen_ai.* semantic convention attributes (Datadog/Honeycomb/Grafana GenAI view compatible) with semconvMode: "both" | "stable" | "legacy"

• Durable runtime — KvCheckpointer with four production backends: CloudflareKvBackend, DurableObjectKvBackend, RedisKvBackend (ioredis-style), RedisRestKvBackend (Upstash REST, edge-safe). CheckpointableRun saves state after every step; await_human_input persists pendingHumanInput and exits the iterator so the worker can recycle while a human reviews.

• SSE Last-Event-ID resume — EventLog tags every event with a monotonic id, persists to the same KvBackend, and replays only the missing tail when a client reconnects. The reference Cloudflare Worker honors Last-Event-ID natively; useAgentRun({ resume: { maxAttempts } }) retries automatically.

• Stateless human-in-the-loop — resumeFromHuman(checkpointer, traceId, promptId, response) writes the human's reply into a paused snapshot. Because there is no in-memory state, the worker that pauses and the worker that resumes can be different processes (and different days). See examples/durable-runtime/.

• React hooks — @agentkit-js/react provides useAgentRun() for streaming SSE agent events in Next.js / React apps

• Multi-model — Anthropic (Claude) and OpenAI-compatible endpoints (Ollama, vLLM, llama.cpp)

• MCP support — McpToolCollection wraps any MCP server's tools as first-class agentkit tools

• Cloudflare Workers — HTTP API entry point with KV session caching, ready to deploy with Wrangler

Quick Start

Code Agent

import { CodeAgent, AnthropicModel, AnthropicModels } from "@agentkit-js/core";

const agent = new CodeAgent({
  tools: [],
  model: new AnthropicModel(AnthropicModels.SONNET_LATEST),
  maxSteps: 10,
});

for await (const event of agent.run("What is 42 * 1337?")) {
  if (event.event === "final_answer") console.log(event.data.answer);
}

Tool-Calling Agent

import { ToolCallingAgent, AnthropicModel, AnthropicModels } from "@agentkit-js/core";
import { z } from "zod";

const searchTool = {
  name: "search",
  description: "Search the web",
  inputSchema: z.object({ query: z.string() }),
  outputSchema: z.string(),
  readOnly: true,
  idempotent: true,
  forward: async ({ query }) => `Results for: ${query}`,
};

const agent = new ToolCallingAgent({
  tools: [searchTool],
  model: new AnthropicModel(AnthropicModels.SONNET_LATEST),
  maxSteps: 5,
});

for await (const event of agent.run("Search for recent AI news")) {
  if (event.event === "final_answer") console.log(event.data.answer);
}

CLI

# Install globally
npm install -g @agentkit-js/cli

# Run a task
agentkit run "What is the square root of 144?"

# Stream all events as NDJSON
agentkit run "Summarise recent AI news" --stream | jq .

# Use a specific model
agentkit run "Write a haiku" --model claude-opus-4-8 --max-steps 5

Quality Runners

Self-Consistency — majority vote across N independent runs

import { SelfConsistencyRunner, AnthropicModel, AnthropicModels } from "@agentkit-js/core";

const runner = new SelfConsistencyRunner({
  model: new AnthropicModel(AnthropicModels.SONNET_LATEST),
  tools: [],
  n: 5,
  concurrency: 3,
  earlyStop: true,
});

const answer = await runner.run("What is the capital of France?");

Reflect-Refine — critique loop until quality signal passes

import { ReflectRefineRunner, AnthropicModel, AnthropicModels } from "@agentkit-js/core";

const runner = new ReflectRefineRunner({
  model: new AnthropicModel(AnthropicModels.SONNET_LATEST),
  tools: [],
  maxCycles: 3,
  qualitySignal: (answer) => answer.length > 100,
});

const answer = await runner.run("Write a detailed analysis of...");

Parallel Fork-Join — diverse reasoning paths, synthesised answer

import { ParallelForkJoinRunner, AnthropicModel, AnthropicModels } from "@agentkit-js/core";

const runner = new ParallelForkJoinRunner({
  branches: 3,
  concurrency: 3,
  aggregation: "summary",
  branchPrompt: (i, msgs) => [
    ...msgs,
    { role: "user", content: `Analyse from perspective ${i + 1} of 3.` },
  ],
});

const result = await runner.run(
  new AnthropicModel(AnthropicModels.SONNET_LATEST),
  [{ role: "user", content: "What are the trade-offs of microservices?" }]
);
console.log(result.answer);   // synthesised
console.log(result.branches); // individual paths

Long-history compaction

import { CodeAgent, AnthropicModel, AnthropicModels, MessageAssembler } from "@agentkit-js/core";

const model = new AnthropicModel(AnthropicModels.SONNET_LATEST);
const assembler = new MessageAssembler({ chunkSizeSteps: 8 });
const agent = new CodeAgent({
  tools: [],
  model,
  maxSteps: 50,
  assembler,
});

// Summarise old steps, keep context window in check
await agent.assembler.compact(model, 5);

Custom Endpoints & Local Models

Both adapters accept an optional baseURL to point at any compatible endpoint — local models, third-party proxies, or private deployments.

OpenAI-compatible (Ollama / vLLM / llama.cpp / any proxy)

import { OpenAIModel, OpenAIModels } from "@agentkit-js/core";

// Hosted OpenAI
const gpt4o = new OpenAIModel(OpenAIModels.GPT_4O);

// Local Ollama
const local = new OpenAIModel("mistral-7b", {
  baseURL: "http://localhost:11434/v1",
  apiKey: "ollama",
  samplingParams: { temperature: 0.7, seed: 42 },
});

Anthropic-compatible proxy or private deployment

import { AnthropicModel, AnthropicModels } from "@agentkit-js/core";

// Standard usage — reads ANTHROPIC_API_KEY from environment
const model = new AnthropicModel(AnthropicModels.SONNET_LATEST);

// Third-party proxy or private endpoint
const proxied = new AnthropicModel(AnthropicModels.SONNET_LATEST, {
  apiKey: "your-proxy-key",
  baseURL: "https://your-proxy.example.com",
});

Chinese model providers (first-class adapters)

Seven providers ship as dedicated packages with full thinking-mode, reasoning-field, and cache-strategy support:

// Doubao / Volcengine Ark (first-class thinking + effort tiers)
import { DoubaoModel, DoubaoModels } from "@agentkit-js/model-doubao";
const doubao = new DoubaoModel(DoubaoModels.LATEST, process.env.ARK_API_KEY);
for await (const e of doubao.generate(msgs, { thinking: { mode: "enabled", effort: "high" } })) { ... }

// DeepSeek V4 (thinking:{type} + effort, V4_FLASH available)
import { DeepSeekModel, DeepSeekModels } from "@agentkit-js/model-deepseek";
const ds = new DeepSeekModel(DeepSeekModels.V4_PRO, process.env.DEEPSEEK_API_KEY);

// Kimi K2.6 (reasoning field: delta.reasoning, thinking:{type} via extra_body)
import { MoonshotModel, KimiModels } from "@agentkit-js/model-moonshot";
const kimi = new MoonshotModel(KimiModels.LATEST, process.env.MOONSHOT_API_KEY);

// Qwen3 (enable_thinking + thinking_budget, intl region option)
import { QwenModel, QwenModels } from "@agentkit-js/model-qwen";
const qwen = new QwenModel(QwenModels.QWEN3_MAX, { region: "cn" });

// GLM-5 (Zhipu self-hosted, thinking:{type} via extra_body)
import { ZhipuModel, GLMModels } from "@agentkit-js/model-zhipu";
const glm = new ZhipuModel(GLMModels.GLM_5, process.env.ZHIPU_API_KEY);

// MiniMax M3 (reasoning_split=true → reasoning_details; or <think> tag parsing)
import { MiniMaxModel, MiniMaxModels } from "@agentkit-js/model-minimax";
const mm = new MiniMaxModel(MiniMaxModels.M3, process.env.MINIMAX_API_KEY);

Provider capability reference:

Note on multi-turn round-trip: DeepSeek/Doubao/Kimi require reasoning_content echoed back in assistant messages containing tool_use (not in text-only turns — that causes a 400 error). The adapters implement this automatically via reasoningRoundTripPolicy: "tool-turns-only".

Deploy to Cloudflare Workers

cd packages/cloudflare-worker
cp wrangler.toml.example wrangler.toml   # edit account_id and kv_namespaces
wrangler secret put ANTHROPIC_API_KEY
wrangler deploy

The Worker exposes a POST /run endpoint. Session state is stored in KV for cost-efficient prompt caching across requests.

Packages

Production APIs

Retry / Resilience (C1)

All model adapters automatically retry 429 / 5xx / network errors with exponential backoff + jitter:

import { AnthropicModel } from "@agentkit-js/core";

const model = new AnthropicModel("claude-sonnet-4-6", {
  apiKey: process.env.ANTHROPIC_API_KEY,
  retry: { maxRetries: 3, baseDelayMs: 500, maxDelayMs: 30_000 },
});

Evals (B1)

import { runEval, exactMatch, toolCallAccuracy } from "@agentkit-js/core";

const results = await runEval(dataset, async function* (task) {
  yield* agent.run(task);
}, [exactMatch, toolCallAccuracy]);

OpenTelemetry Bridge (C2)

import { OtelBridge, InMemorySpanExporter, withOtel } from "@agentkit-js/core";

const exporter = new InMemorySpanExporter(); // swap for OTLP in production
const bridge = new OtelBridge({ exporter });
for await (const ev of withOtel(agent.run(task), bridge)) {
  console.log(ev);
}
bridge.flush();

Durable runtime — Checkpoints, SSE resume, HITL

Pick one KvBackend and use it for checkpoints, the SSE event log, and structured memory — there is one canonical contract.

import {
  CheckpointableRun,
  EventLog,
  KvCheckpointer,
  resumeFromHuman,
  applyHumanResponse,
  restoreFromSnapshot,
} from "@agentkit-js/core";
// Pick a backend that matches your runtime.
import { CloudflareKvBackend } from "@agentkit-js/cloudflare-worker";
// Other options: DurableObjectKvBackend (CF), RedisKvBackend (Node/Bun),
// RedisRestKvBackend (Upstash, edge-safe), MapKvBackend (tests).

const kv = new CloudflareKvBackend(env.MY_KV);
const checkpointer = new KvCheckpointer(kv);
const log = new EventLog(kv); // SSE Last-Event-ID resume
const wrapper = new CheckpointableRun({ checkpointer }, agent.assembler);

// Stream + persist + tag every event with a monotonic id.
for await (const { eventId, event } of log.tap(
  wrapper.run(agent.run(task), task, traceId),
  traceId,
)) {
  // emit `id: ${eventId}\nevent: ${event.event}\ndata: ${...}\n\n` over SSE
  if (event.event === "await_human_input") {
    // Snapshot is already persisted; the worker is free to exit.
    return;
  }
}

Resume after a worker recycle (different process, possibly different machine):

const lastId = req.headers.get("Last-Event-ID");
for await (const { eventId, event } of log.replay(traceId, lastId)) { /* re-emit */ }
const startSeq = await log.nextSeq(traceId);
for await (const { eventId, event } of log.tap(agent.run(task, traceId), traceId, { startSeq })) { /* live tail */ }

Resume after human approval (could be hours/days later):

// In the /resume HTTP handler — stateless, returns immediately.
await resumeFromHuman(checkpointer, traceId, promptId, response);

// Later, when a worker picks up the trace:
const snap = await checkpointer.load(traceId);
restoreFromSnapshot(snap, agent.assembler);
applyHumanResponse(snap, agent.assembler); // injects user_message into history
// Then continue with `wrapper.run(agent.run(snap.task, traceId), ...)`.

The reference Cloudflare Worker (@agentkit-js/cloudflare-worker) wires all of this for you — bind AGENTKIT_EVENT_LOG and AGENTKIT_CHECKPOINTS in wrangler.toml and you get Last-Event-ID resume + a POST /resume endpoint out of the box. Full guide: docs/guides/durable-runtime.md.

React Hook (B2)

import { useAgentRun } from "@agentkit-js/react";

function ChatUI() {
  const { messages, isRunning, run } = useAgentRun("/api/run");
  return (
    <>
      {messages.map((m) => <div key={m.id}>{m.content}</div>)}
      <button onClick={() => run({ task: "What is 2 + 2?" })} disabled={isRunning}>
        Ask
      </button>
    </>
  );
}

Tool Deferred Loading (L1-1)

Exclude large MCP server tool schemas from the context prefix; load on-demand via Anthropic Tool Search. Reduces token usage by up to 85% on servers with many tools.

import { McpToolCollection, ToolCallingAgent, AnthropicModel, AnthropicModels } from "@agentkit-js/core";

// Option A: defer all tools from an MCP server with many tools.
const tools = await McpToolCollection.fromHttp("https://big-mcp-server.example.com");
tools.deferAll(); // marks all tools as deferLoading: true

// Option B: defer individual tools via the ToolDefinition field.
const myTool = {
  name: "my_tool",
  deferLoading: true,   // excluded from system prefix
  // ... other fields
};

const agent = new ToolCallingAgent({
  tools: tools.list(),
  model: new AnthropicModel(AnthropicModels.SONNET_LATEST),
});

Tool Use Examples (L1-2)

Provide few-shot examples to improve parameter accuracy from ~72% to ~90%.

const searchTool = {
  name: "search",
  description: "Search the web for information",
  inputSchema: z.object({ query: z.string(), maxResults: z.number().optional() }),
  inputExamples: [
    { query: "latest AI research 2026", maxResults: 5 },
    { query: "TypeScript best practices" },
  ],
  // ...
};

Context Editing (L2-1)

Truncate old tool outputs reversibly to reduce context size without breaking conversation structure.

import { MessageAssembler, AnthropicModel, AnthropicModels } from "@agentkit-js/core";

const model = new AnthropicModel(AnthropicModels.SONNET_LATEST);
const assembler = new MessageAssembler({ chunkSizeSteps: 8 });
const agent = new ToolCallingAgent({ tools, model, assembler, maxSteps: 50 });

// After many steps, truncate old tool outputs that are taking too many tokens.
// Keeps the 3 most recent tool steps verbatim; truncates older ones.
const truncated = agent.assembler.editToolResults({ maxTokens: 4096, keepRecent: 3 });
console.log(`Truncated ${truncated} tool outputs`);

Cross-Session Memory Tool (L2-2)

Give agents persistent memory that survives across separate run() calls.

import { createMemoryTool, MapKvBackend, ToolCallingAgent, AnthropicModel, AnthropicModels } from "@agentkit-js/core";

// Use MapKvBackend for in-process use, or KvCheckpointer's backend for persistence.
const memory = createMemoryTool({ backend: new MapKvBackend() });

const agent = new ToolCallingAgent({
  tools: [memory, ...otherTools],
  model: new AnthropicModel(AnthropicModels.SONNET_LATEST),
});

// Session 1: agent learns something
for await (const ev of agent.run("What's the capital of France? Remember it for later.")) { }

// Session 2: agent recalls it
for await (const ev of agent.run("What did you remember about France's capital?")) {
  if (ev.event === "final_answer") console.log(ev.data.answer); // "Paris"
}

Programmatic Tool Calling / Self-Hosted PTC (L3-1)

Execute model-generated orchestration scripts inside a kernel; only the final result enters the context window.

import { ProgrammaticOrchestrator, JsKernel, ToolRegistry } from "@agentkit-js/core";

const kernel = new JsKernel();
const registry = new ToolRegistry();
registry.register(searchTool);
registry.register(calcTool);

const orchestrator = new ProgrammaticOrchestrator(kernel, registry, {
  extraCapabilities: ["tool:search", "tool:calc"],
});

// Model-generated script — intermediate results never enter the LLM context.
const script = `
  const results = callTool('search', { query: 'AI news 2026' });
  const count = callTool('calc', { expr: results.length + ' items' });
  count + ' found';
`;
const { finalOutput, toolCallCount } = await orchestrator.run(script);
console.log(finalOutput);    // Only this enters the context window.
console.log(toolCallCount);  // e.g. 2 — intermediate results stayed in the kernel.

Development

pnpm install
pnpm build
pnpm test
pnpm typecheck

# Reproduce every percentage in the "Differentiated" section above.
pnpm bench

# Cloudflare Worker local dev
cd packages/cloudflare-worker && wrangler dev

Examples

Documentation

• docs/guides/durable-runtime.md — checkpoints, SSE Last-Event-ID resume, HITL

• docs/kernels/comparison.md — kernel selection decision tree

• docs/guides/evals-cookbook.md — eval design patterns (incl. A4 multi-criterion judges)

• docs/guides/memory-patterns.md — memory namespace + decay patterns

• docs/guides/observational-memory.md — A1 background-observer compression

• docs/guides/devtools.md — A2 time-travel debugger + fork-from-step

• docs/guides/skills-and-hooks.md — A3 progressive disclosure + post-tool hooks

Environment Variables

Acknowledgements

Inspired by Hugging Face's smolagents. agentkit-js is a ground-up TypeScript reimplementation — not a port — targeting async-first execution, WASM sandboxing, and edge deployment.

License

Apache 2.0