@agentskit/core

@agentskit/core

Profile: major-package

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

Verified proof

• Package metadata and tests live under packages/core/.
• Package guide: https://www.agentskit.io/docs/packages/core
• Stability map: docs/STABILITY.md

How this fits the ecosystem

@agentskit/core is the contract layer: the tiny, stable foundation that makes adapters, tools, skills, memory, retrievers, and runtimes interchangeable.

• AgentsKit: compose it with the other packages in this repo to build agents from small, swappable parts.
• Registry: look for ready agents and templates that already use this layer at registry.agentskit.io.
• Playbook: learn the production patterns behind this layer at playbook.agentskit.io.
• AKOS: run the same concepts with enterprise deployment, governance, and observability at akos.agentskit.io.

Docs: package guide · agent handoff

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

Maturity and compatibility

• Stability: stable — see docs/STABILITY.md
• Node.js 20+ and TypeScript strict mode
• Published as @agentskit/core

Contributing

See CONTRIBUTING.md and the monorepo LICENSE.