Skip to content

Agent SDKLightweight AI Agent Framework

Message-first agent loop with planning, summarization, and multi-agent orchestration

Agent SDK

Quick Start

bash
npm install @cognipeer/agent-sdk zod
bash
yarn add @cognipeer/agent-sdk zod
bash
pnpm add @cognipeer/agent-sdk zod

Basic Usage

typescript
import { createSmartAgent, createTool, fromLangchainModel } from "@cognipeer/agent-sdk";
import { ChatOpenAI } from "@langchain/openai";
import { z } from "zod";

// Define a simple tool
const echo = createTool({
  name: "echo",
  description: "Echo back the input text",
  schema: z.object({ text: z.string().min(1) }),
  func: async ({ text }) => ({ echoed: text }),
});

// Create model adapter
const model = fromLangchainModel(new ChatOpenAI({
  model: "gpt-4o-mini",
  apiKey: process.env.OPENAI_API_KEY,
}));

// Create smart agent with planning
const agent = createSmartAgent({
  name: "Assistant",
  model,
  tools: [echo],
  useTodoList: true,
  limits: { maxToolCalls: 5, maxToken: 6000 },
  tracing: { enabled: true },
});

// Run the agent
const result = await agent.invoke({
  messages: [{ 
    role: "user", 
    content: "Plan a greeting and send it via the echo tool" 
  }],
});

console.log(result.content);

Key Capabilities

  • Planning Mode: Structured TODO tool with strict workflow rules
  • Smart Summarization: Token-aware context archiving with retrieval
  • Structured Output: Zod-powered schema validation and parsing
  • Tool Limits: Total and parallel execution limits with automatic finalization
  • Multi-Agent: Compose agents via asTool and runtime handoffs
  • Vision Support: Multimodal message parts and provider normalization
  • Tracing: Structured JSON logs with streaming onEvent hooks

Advanced Features

Planning Mode

typescript
const agent = createSmartAgent({
  model,
  tools,
  useTodoList: true, // Enable planning mode
});

Structured Output

typescript
const agent = createSmartAgent({
  model,
  tools,
  outputSchema: z.object({
    summary: z.string(),
    items: z.array(z.string()),
  }),
});

const result = await agent.invoke({ messages });
console.log(result.output); // Parsed structured output

Multi-Agent Delegation

typescript
const specialist = createSmartAgent({ name: "Specialist", model, tools });
const coordinator = createSmartAgent({
  name: "Coordinator",
  model,
  tools: [specialist.asTool({ toolName: "delegate_to_specialist" })],
});

Why Agent SDK?

  • Minimal Dependencies: Lightweight core with optional adapters for LangChain and MCP
  • Type-Safe: Full TypeScript support with Zod schema validation
  • Flexible: Use createSmartAgent for batteries-included experience or createAgent for full control
  • Production Ready: Built-in tracing, guardrails, and token management
  • Composable: Easy multi-agent orchestration with delegation and handoffs
  • Observable: Predictable events, inspection-ready state, and structured traces

Released under the MIT License.