@vela-labs/sdk

TypeScript SDK for building agentic AI applications. Handles the agent loop, tool execution, context management, and provider abstraction.

Install

Install the latest published release from npm:

npm install @vela-labs/sdk

Quick start

import { Agent, OpenRouterProvider, createBashTool } from "@vela-labs/sdk";

const agent = new Agent({
  provider: new OpenRouterProvider({ apiKey: process.env.OPENROUTER_API_KEY! }),
  model: "deepseek/deepseek-v4-flash",
  systemPrompt: "You are a helpful assistant.",
  tools: [createBashTool()],
});

for await (const event of agent.stream("List the files in the current directory")) {
  if (event.type === "text_delta") process.stdout.write(event.text);
  if (event.type === "tool_call") console.log(`\n→ ${event.name}(${JSON.stringify(event.input)})`);
}

Built-in tools

import { createBashTool, createReadFilesTool, createWriteFileTool, createEditFileTool } from "@vela-labs/sdk";

Custom tools

import type { ToolDefinition } from "@vela-labs/sdk";

const myTool: ToolDefinition = {
  name: "fetch_url",
  description: "Fetch the contents of a URL.",
  parameters: {
    type: "object",
    properties: {
      url: { type: "string" },
    },
    required: ["url"],
  },
  async execute(input) {
    const res = await fetch(input.url as string);
    return { body: await res.text() };
  },
};

Providers

• OpenRouter — access any model via OpenRouter (DeepSeek, Claude, GPT-4o, etc.)
• OpenAI — use GPT and o-series models directly through the OpenAI API

import { OpenRouterProvider } from "@vela-labs/sdk";

const provider = new OpenRouterProvider({
  apiKey: "sk-or-...",
  reasoningEffort: "medium", // off | minimal | low | medium | high | xhigh
});

import { OpenAIProvider } from "@vela-labs/sdk";

const provider = new OpenAIProvider({
  apiKey: process.env.OPENAI_API_KEY!,
  reasoningEffort: "medium",
});

Context summarization

Automatically compacts conversation history when it grows large:

const agent = new Agent({
  // ...
  summarization: { threshold: 128_000 }, // token count that triggers compaction
});