Quick Start

Go from an API key to a completed Agent Session with the TypeScript SDK. Skopik requires Node.js 20 or newer.

1. Create an API key

Create an API key in the Skopik Console and copy its secret. The secret is shown once.

For this guide, use a key with write permission and expose it only to your server-side process:

export SKOPIK_API_KEY="sk_live_..."

See Auth for permissions, rotation, and production handling.

2. Install the SDK

npm install @skopiklabs/sdk

Create a client:

import { createSkopikClient } from '@skopiklabs/sdk'

const skopik = createSkopikClient({
	apiKey: process.env.SKOPIK_API_KEY,
})

The default API base URL is https://api.skopik.com/api/v1. Set baseUrl only when connecting to another Skopik deployment.

3. Run an Agent

The shortest path is run(). When you do not select an Agent or Template, Skopik creates an active Agent from the default Template, opens a Session, waits for the opening turn to settle, and returns the final response.

const result = await skopik.run({
	prompt: 'Research three current approaches to durable AI agent memory. Cite primary sources.',
	reasoning: 'high',
	permission: 'ask',
	limits: {
		maxTurns: 12,
		maxCostUsd: 2,
	},
})

console.log(result.sessionId)
console.log(result.text)
console.log(result.usage.costUsd)

run() waits locally for up to five minutes by default. If that wait expires, the Session keeps running in Skopik; the thrown SkopikWaitTimeout includes the sessionId so you can reconnect with sessions.get() or sessions.stream().

The equivalent raw API request opens the Session without waiting:

curl "https://api.skopik.com/api/v1/sessions" \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Research three current approaches to durable AI agent memory. Cite primary sources.",
    "reasoning": "high",
    "permission_mode": "ask",
    "limits": { "max_turns": 12, "max_cost_usd": 2 }
  }'

4. Keep a durable Agent

Create an Agent once when you want the same identity, instructions, brain, skills, and defaults across many Sessions:

const agent = await skopik.agents.upsert({
	name: 'researcher',
	displayName: 'Researcher',
	description: 'Produces concise, source-backed research briefs.',
	instructions: 'Prefer primary sources. Separate evidence from inference.',
	status: 'active',
	defaultReasoning: 'high',
	canWebSearch: true,
	canWebBrowse: true,
})

const session = await skopik.sessions.open({
	agent: agent.agentId,
	prompt: 'Compare the memory approaches and recommend one for an agent platform.',
	title: 'Memory architecture review',
	permission: 'ask',
})

console.log(session.sessionId, session.status)

Follow the Session as it works. Save the latest cursor if the connection may drop; passing it back as after replays missed frames before returning to the live stream.

let cursor: string | undefined

for await (const frame of skopik.sessions.stream(session.sessionId, { after: cursor })) {
	cursor = frame.cursor
	console.log(frame.envelope)
}

Read the latest state and persisted messages at any time:

const { session: latest, todos, approvals } =
	await skopik.sessions.get(session.sessionId)

const { data: messages } =
	await skopik.sessions.listMessages(session.sessionId)

Next steps

• Auth — secure and rotate API keys.
• Agents — configure identity, capabilities, budgets, and brain files.
• Sessions — stream, steer, pause, resume, and bound work.
• Templates — reuse complete Agent starting points.
• Skills — package focused capabilities.
• Remotes — give Sessions a work folder on your hardware.
• Environments — define setup, teardown, variables, secrets, and actions.