@kognitivedev/agents

Provider-agnostic agent framework with guardrails, memory, and multi-agent networks.

Installation

bun add @kognitivedev/agents @kognitivedev/adapter-ai-sdk @ai-sdk/openai zod

Use @kognitivedev/adapter-claude-agent-sdk instead when you want Claude Agent SDK as the runtime.

Quick Start

import { createAgent, contentFilter, tokenLimiter } from "@kognitivedev/agents";
import { createAISDKRuntimeAdapter } from "@kognitivedev/adapter-ai-sdk";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";

const agent = createAgent({
  name: "support",
  instructions: "You are a helpful support agent.",
  runtime: createAISDKRuntimeAdapter({
    model: openai("gpt-4o"),
  }),
  tools: [searchTool],
  guardrails: [
    tokenLimiter({ maxTokens: 4000 }),
    contentFilter({ patterns: [/password/i], mode: "block" }),
  ],
  maxSteps: 5,
});

const result = await agent.generate({
  messages: [{ role: "user", content: "Help me" }],
  resourceId: {},
});

console.log(result.text);

const summary = await agent.generateObject<{ sentiment: "positive" | "negative"; confidence: number }>({
  messages: [{ role: "user", content: "I love this product." }],
  resourceId: {},
  structuredOutput: {
    schema: z.object({
      sentiment: z.enum(["positive", "negative"]),
      confidence: z.number(),
    }),
  },
});

console.log(summary.object);

Core Ideas

• runtime is required and replaces the old provider-specific model field.
• messages use Kognitive's neutral message format from @kognitivedev/shared.
• prepare() returns neutral runtime inputs: { system, tools, maxTurns, resolvedPrompt }.
• generate() can return both text and a schema-validated object.
• generateObject() is typed convenience sugar for schema-backed runs.
• stream() returns ReadableStream<StreamEvent>.
• streamWithModes() gives richer event channels like messages, debug, and custom.

Instructions

The instructions field supports:

• string
• (ctx) => string | Promise<string>
• PromptHubConfig

Prompt Hub metadata is exposed at ctx.resolvedPrompt and prepare().resolvedPrompt.

Features

• createAgent orchestrates runtime adapters with memory, tools, and hooks
• First-class structured output via generate() or generateObject()
• Built-in guardrails plus composition helpers
• createAgentNetwork() for multi-agent routing
• prepare() for adapter-level escape hatches
• File preprocessing hooks for documents and images
• Multi-mode streaming via streamWithModes()
• Double-texting controls in the runtime API

File Processing

Agents can preprocess non-image file attachments through the Kognitive Documents API before the model runs.

const agent = createAgent({
  name: "doc-reader",
  instructions: "Analyze uploaded documents.",
  runtime: createAISDKRuntimeAdapter({
    model: openai("gpt-4o"),
  }),
  fileProcessing: {
    tier: "agentic",
    preset: "scientific",
    outputFormats: ["text", "markdown"],
    extractLayout: true,
    autoMode: true,
  },
});

fileProcessing: true keeps the zero-config behavior. A custom { processFile } callback is also supported.

The agent layer stays text-only: parsed text is injected into the prompt, with markdown as a fallback. Rich OCR/layout artifacts remain available in the Documents backend and SDK.

Provider Adapters

Kognitive's neutral packages do not depend on provider SDKs directly. Use an adapter package:

• @kognitivedev/adapter-ai-sdk
• @kognitivedev/adapter-claude-agent-sdk

Example with Claude Agent SDK:

import { createAgent } from "@kognitivedev/agents";
import { createClaudeAgentRuntimeAdapter } from "@kognitivedev/adapter-claude-agent-sdk";

const agent = createAgent({
  name: "researcher",
  instructions: "You are a careful research agent.",
  runtime: createClaudeAgentRuntimeAdapter({
    model: "sonnet",
    allowedTools: ["Read", "Glob", "Grep", "Agent"],
  }),
});

Both Zod schemas and raw JSON Schema objects are accepted at the agent layer. Adapter packages normalize schemas for their provider runtimes under the hood.

Structured Output

Use generateObject() when you want a typed object response:

import { z } from "zod";

const recipeAgent = createAgent({
  name: "recipe-parser",
  instructions: "Extract structured recipe data.",
  runtime: createAISDKRuntimeAdapter({
    model: openai("gpt-4o-mini"),
  }),
});

const result = await recipeAgent.generateObject<{
  title: string;
  ingredients: string[];
}>({
  messages: [{ role: "user", content: "Tomato pasta with basil and olive oil." }],
  resourceId: {},
  structuredOutput: {
    schema: z.object({
      title: z.string(),
      ingredients: z.array(z.string()),
    }),
  },
});

Use generate() when you want both free-form text and structured data:

const result = await recipeAgent.generate({
  messages: [{ role: "user", content: "Summarize this bug report and classify severity." }],
  resourceId: {},
  structuredOutput: {
    schema: {
      type: "object",
      properties: {
        severity: { type: "string" },
        owner: { type: "string" },
      },
      required: ["severity"],
    },
  },
});

console.log(result.text);
console.log(result.object);

Prepare Escape Hatch

prepare() returns neutral runtime inputs so you can bridge into a specific provider yourself:

import { stepCountIs, streamText } from "ai";
import { openai } from "@ai-sdk/openai";
import { toAISDKTools, toAISDKMessages } from "@kognitivedev/adapter-ai-sdk";

const prepared = await agent.prepare({ resourceId: { userId: "user_1" } });

const result = await streamText({
  model: openai("gpt-4o"),
  system: prepared.system,
  tools: toAISDKTools(prepared.tools),
  stopWhen: stepCountIs(prepared.maxTurns),
  messages: toAISDKMessages([{ role: "user", content: "Hello" }]),
});