> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kairn.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> From zero to your first agent invocation in under 5 minutes.

## Install the SDK

```bash npm theme={null}
npm install @kairnsh/sdk
```

```bash pnpm theme={null}
pnpm add @kairnsh/sdk
```

```bash yarn theme={null}
yarn add @kairnsh/sdk
```

## Get an API key

1. Sign up at [app.kairn.sh](https://app.kairn.sh)
2. Go to **Settings → API Keys**
3. Create a new key — it starts with `kn_live_`

> [!WARNING]
>
> Keep your API key server-side only. Never expose it in client-side code or commit it to version control.

## Initialise the client

```ts theme={null}
import Kairn from '@kairnsh/sdk'

const kairn = new Kairn({
  apiKey: process.env.KAIRN_API_KEY!,
})
```

## Create a soul

A soul is the agent's identity — its instructions, personality, and tool access. Create it once; it serves all your users.

```ts theme={null}
await kairn.souls.create({
  name: 'assistant',
  label: 'Product Assistant',
  soulMd: `
    Hired as a senior product specialist — you know the product deeply and
    genuinely care about helping users get value from it. You're concise,
    warm, and action-oriented. You use memory to make every interaction feel
    personal — you never ask for information you already have.
  `,
  agentsMd: `
    Product: Acme — B2B SaaS project management tool.
    Users: team leads and individual contributors, mostly non-technical.
    Tone: friendly but efficient — people are busy.
  `,
  defaultModel: 'anthropic/claude-sonnet-4-6',
})
```

> [!NOTE]
>
> You only need to create a soul once. After that, you can update it with `kairn.souls.update()`.

## Seed user context

Write context from your database into the agent's memory before invoking. The agent reads it automatically.

```ts theme={null}
await kairn.memory.set('user_123', 'default', {
  name: 'Alex',
  plan: 'pro',
  company: 'Acme Corp',
  account_created: '2025-01-15',
})
```

## Invoke the agent

```ts theme={null}
const result = await kairn.invoke({
  agent: 'assistant',
  userId: 'user_123',
  input: 'What can you help me with?',
})

console.log(result.output)
// "Hi Alex! I'm your product assistant for Acme Corp.
//  I can help you with questions about your Pro account,
//  walk you through features, or assist with any issues..."
```

## Stream the response

For chat interfaces, use `stream()` to yield tokens as the agent generates them.

```ts theme={null}
for await (const event of kairn.stream({
  agent: 'assistant',
  userId: 'user_123',
  input: 'Summarise my account status.',
})) {
  if (event.type === 'token') {
    process.stdout.write(event.text)
  }
  if (event.type === 'done') {
    console.log('\nMemory written:', event.memoryDelta)
  }
}
```

## Next steps

> [card] [Core concepts](https://docs.kairn.sh/concepts.md)
>
> Understand souls, memory, sessions, and mandates.

> [card] [Customer support](https://docs.kairn.sh/use-cases/customer-support.md)
>
> Build a support agent that knows your users and takes real actions.

> [card] [Mandates](https://docs.kairn.sh/concepts.md#mandates)
>
> Schedule agents to run autonomously — check-ins, reports, nudges.

> [card] [SDK reference](https://docs.kairn.sh/sdk-reference.md)
>
> Full API reference for every method and type.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.