@agentskit/core

The zero-dependency foundation that every AgentsKit package builds on — 5 KB gzipped, edge-ready, works everywhere JavaScript runs.

Tags: ai · agents · llm · agentskit · typescript · orchestration · streaming · chat

Why core

• Zero external dependencies — no npm bloat, no audit surprises; installs in milliseconds and works in Node, Deno, edge runtimes, and the browser
• Stable contracts that unlock the whole ecosystem — six ADR-pinned interfaces (Adapter, Tool, Skill, Memory, Retriever, Runtime) make every package interchangeable
• Chat state machine included — createChatController handles streaming, abort, and message history so you never implement that loop yourself
• Under 10 KB gzipped, always — budget enforced in CI; the foundation you can commit to for the long term

Install

npm install @agentskit/core

Quick example

import { createChatController, createInMemoryMemory } from '@agentskit/core'
import { anthropic } from '@agentskit/adapters'

const controller = createChatController({
  adapter: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY, model: 'claude-sonnet-4-6' }),
  memory: createInMemoryMemory(),
})

await controller.send('Hello!')
console.log(controller.getState().messages)

Features

• createChatController — streaming-capable chat state machine with abort support
• createInMemoryMemory — zero-config in-process memory for prototyping
• TypeScript types for every contract: ToolDefinition, SkillDefinition, AgentEvent, Adapter, Memory, Retriever, RuntimeResult
• Event emitter for AgentEvent streams — observability hooks attach here
• Dual CJS/ESM output, strict TypeScript, no any

Error handling

AgentsKit ships a didactic error system inspired by the Rust compiler. Every error includes a code, a hint for the fix, and a docsUrl — no more vague "Something went wrong" messages.

import {
  AgentsKitError,
  AdapterError,
  ToolError,
  MemoryError,
  ConfigError,
  ErrorCodes,
} from '@agentskit/core'

try {
  await runtime.run(task)
} catch (err) {
  if (err instanceof ToolError) {
    // err.code     → 'AK_TOOL_EXEC_FAILED'
    // err.hint     → actionable suggestion
    // err.docsUrl  → https://www.agentskit.io/docs/tools
    console.error(err.toString())
    // error[AK_TOOL_EXEC_FAILED]: ...
    //   --> Hint: ...
    //   --> Docs: https://www.agentskit.io/docs/tools
  }
}

Available error codes (via ErrorCodes):

| Code | Thrown by | |------|-----------| | AK_ADAPTER_MISSING | adapter not provided to the controller | | AK_ADAPTER_STREAM_FAILED | streaming call to the provider fails | | AK_TOOL_NOT_FOUND | requested tool name is not registered | | AK_TOOL_EXEC_FAILED | execute() throws | | AK_MEMORY_LOAD_FAILED | memory.load() fails | | AK_MEMORY_SAVE_FAILED | memory.save() fails | | AK_MEMORY_DESERIALIZE_FAILED | persisted state is corrupt | | AK_CONFIG_INVALID | required config is missing or wrong type |

Type-safe tools with defineTool

defineTool infers the TypeScript type of execute's args parameter from the JSON Schema — no manual casting.

import { defineTool } from '@agentskit/core'

const greet = defineTool({
  name: 'greet',
  schema: {
    type: 'object',
    properties: { name: { type: 'string' } },
    required: ['name'],
  } as const,   // as const is required for inference
  execute(args) {
    // args.name → string  (inferred, not cast)
    return `Hello, ${args.name}!`
  },
})

Use InferSchemaType<typeof schema> to reference the inferred type elsewhere in your codebase.

Subpath exports (tree-shaken, zero main-bundle weight)

| Subpath | Purpose | |---------|---------| | @agentskit/core/agent-schema | Declarative YAML/JSON agent definitions + validator | | @agentskit/core/prompt-experiments | A/B prompts with PostHog / GrowthBook / custom flag providers | | @agentskit/core/auto-summarize | ChatMemory wrapper that folds old turns into a summary | | @agentskit/core/hitl | Approval gates + ApprovalStore | | @agentskit/core/security | PII redactor + injection detector + rate limiter | | @agentskit/core/compose-tool | Chain N tools into one macro tool | | @agentskit/core/self-debug | Retry failing tools with LLM-corrected arguments | | @agentskit/core/generative-ui | Typed UI element tree + code / markdown / html / chart artifacts | | @agentskit/core/a2a | Agent-to-Agent protocol spec (JSON-RPC over any transport) | | @agentskit/core/manifest | Skill + tool manifest format (MCP-compatible) | | @agentskit/core/eval-format | Portable eval dataset + run-result JSON |

See each page under docs.agentskit.io / for-agents for the full contract.

Ecosystem

| Package | Role | |---------|------| | @agentskit/adapters | LLM chat + embedding providers, router, ensemble, fallback | | @agentskit/runtime | createRuntime, speculate, topologies, durable execution, background agents | | @agentskit/react | useChat, headless chat components | | @agentskit/vue · svelte · solid · react-native · angular | Same ChatReturn contract, one package per framework | | @agentskit/tools | Built-in tools, 20+ integrations, MCP bridge | | @agentskit/memory | Chat + vector + hierarchical + encrypted + graph stores | | @agentskit/rag | Plug-and-play RAG + reranker + loaders | | @agentskit/skills | Ready-made personas + marketplace | | @agentskit/observability | Traces, audit log, cost guard, devtools | | @agentskit/sandbox | Secure code execution + mandatory sandbox policy | | @agentskit/eval | Eval suites, deterministic replay, snapshots, CI reporter | | @agentskit/cli | agentskit init / chat / run / ai / dev / doctor |

Contributors

License

MIT — see LICENSE.

Docs

Full documentation · GitHub