@kognitivedev/client

TypeScript client for connecting to Kognitive runtime servers.

Installation

bun add @kognitivedev/client

Quick Start

import { KognitiveClient } from "@kognitivedev/client";

const client = new KognitiveClient({
  baseUrl: "http://localhost:3001",
  apiKey: "your-api-key",
});

await client.connect();

// Generate a response
const result = await client.generateAgent("support", {
  messages: [{ role: "user", content: "Help me" }],
});
console.log(result.text);

Agents

const agents = await client.listAgents();
const agent = await client.getAgent("support");

// Non-streaming
const result = await client.generateAgent("support", { messages });

// Streaming (returns raw SSE Response)
const response = await client.streamAgent("support", {
  messages,
  streamMode: "values,messages",  // optional: multi-mode streaming
});

// URL for callers that already send ModelMessage[]
const url = client.getAgentStreamUrl("support");

// If you use useChat(), serialize UI messages before hitting runtime endpoints:
import { convertToModelMessages, DefaultChatTransport } from "ai";

const transport = new DefaultChatTransport({
  api: url,
  prepareSendMessagesRequest: async ({ messages, body }) => ({
    body: {
      ...(body ?? {}),
      messages: await convertToModelMessages(
        messages.map(({ id: _id, ...message }) => message),
      ),
    },
  }),
});

Workflows

const workflows = await client.listWorkflows();
const result = await client.executeWorkflow("onboarding", { name: "Alice" });
const resumed = await client.resumeWorkflow("onboarding", snapshot, resumeData);

// Streaming
const response = await client.streamWorkflow("onboarding", {
  input: { name: "Alice" },
  streamMode: "values",
});

Checkpoints & Runs

// List runs for a workflow
const runs = await client.listWorkflowRuns("onboarding", { status: "completed" });

// Get run details with checkpoint count
const run = await client.getWorkflowRun("onboarding", runId);

// Browse checkpoints (state history)
const checkpoints = await client.getRunCheckpoints("onboarding", runId);

// Rollback to a previous step
const snapshot = await client.rollbackRun("onboarding", runId, 2);

Prompt Resolution

Resolve prompts by environment tag (production, staging, etc.):

const prompt = await client.resolvePrompt("welcome-message", { tag: "production" });
console.log(prompt.content);   // prompt text
console.log(prompt.version);   // version number

Tools

const tools = await client.listTools();
const result = await client.executeTool("search", { query: "help" });

Remote Proxies

Wrap remote agents/workflows/tools as local-like objects:

const remoteAgent = await client.getRemoteAgent("support");
const result = await remoteAgent.generate({ messages, resourceId });

// Or fetch all at once for the Kognitive constructor:
const config = await client.toKognitiveConfig();
const app = new Kognitive({
  agents: { ...localAgents, ...config.agents },
});