# @agentskit/core

Profile: <code>major-package</code>

<p align="center"><img alt="AgentsKit" src="https://raw.githubusercontent.com/AgentsKit-io/agentskit/main/apps/docs-next/public/brand/logo-wordmark.svg" width="180" /></p>

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

[![npm version](https://img.shields.io/npm/v/@agentskit/core?color=blue)](https://www.npmjs.com/package/@agentskit/core)
[![npm downloads](https://img.shields.io/npm/dm/@agentskit/core)](https://www.npmjs.com/package/@agentskit/core)
[![bundle size](https://img.shields.io/bundlejs/size/@agentskit/core?label=bundle)](https://bundlejs.com/?q=@agentskit/core)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
[![stability](https://img.shields.io/badge/stability-stable-brightgreen)](../../docs/STABILITY.md)
[![GitHub stars](https://img.shields.io/github/stars/AgentsKit-io/agentskit?style=social)](https://github.com/AgentsKit-io/agentskit)

**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/reference/packages/core
- Stability map: [docs/STABILITY.md](../../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](https://registry.agentskit.io).
- **Playbook**: learn the production patterns behind this layer at [playbook.agentskit.io](https://playbook.agentskit.io).
- **AKOS**: run the same concepts with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io).

Docs: [package guide](https://www.agentskit.io/docs/reference/packages/core) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt)

## 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

<!-- readme-command:install -->
```bash
npm install @agentskit/core
```

## Quick example

<!-- readme-example:quickstart -->
```ts
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.

```ts
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/agents/tools
    console.error(err.toString())
    // error[AK_TOOL_EXEC_FAILED]: ...
    //   --> Hint: ...
    //   --> Docs: https://www.agentskit.io/docs/agents/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_TOOL_PEER_MISSING` | optional tool peer dependency is not installed |
| `AK_TOOL_INVALID_INPUT` | tool arguments or proposal are invalid |
| `AK_TOOL_QUOTA_EXCEEDED` | tool execution exceeds its configured quota |
| `AK_TOOL_FORBIDDEN` | tool execution is denied by policy |
| `AK_MEMORY_LOAD_FAILED` | memory.load() fails |
| `AK_MEMORY_SAVE_FAILED` | memory.save() fails |
| `AK_MEMORY_DESERIALIZE_FAILED` | persisted state is corrupt |
| `AK_MEMORY_PEER_MISSING` | optional memory backend is not installed |
| `AK_MEMORY_REMOTE_HTTP` | remote memory request fails |
| `AK_CONFIG_INVALID` | required config is missing or wrong type |
| `AK_RUNTIME_INVALID_INPUT` | runtime input is invalid |
| `AK_RUNTIME_STEP_FAILED` | a runtime step fails |
| `AK_RUNTIME_DELEGATE_FAILED` | delegated agent execution fails |
| `AK_SANDBOX_DENIED` | sandbox policy denies execution |
| `AK_SANDBOX_INVALID_TOOL` | tool is not valid for the sandbox |
| `AK_SANDBOX_PEER_MISSING` | optional sandbox backend is not installed |
| `AK_SANDBOX_BACKEND_FAILED` | sandbox backend fails |
| `AK_SKILL_INVALID` | skill definition is invalid |
| `AK_SKILL_DUPLICATE` | skill identity is duplicated |

## Type-safe tools with `defineTool`

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

```ts
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 the [core guide for agents](https://www.agentskit.io/docs/for-agents/core) for the full contract.

## Ecosystem

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

## Contributors

<a href="https://github.com/AgentsKit-io/agentskit/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=AgentsKit-io/agentskit" alt="AgentsKit contributors" />
</a>

## License

MIT — see [LICENSE](../../LICENSE).

## Docs

[Full documentation](https://www.agentskit.io) · [GitHub](https://github.com/AgentsKit-io/agentskit)

## Maturity and compatibility

- Stability: **stable** — see [docs/STABILITY.md](../../docs/STABILITY.md)
- **Node.js 20+** and **TypeScript** strict mode
- Published as `@agentskit/core`

## Contributing

See [CONTRIBUTING.md](../../CONTRIBUTING.md) and the monorepo [LICENSE](../../LICENSE).