@llm-utils/agents

Agent building blocks for LLM applications. Type-safe tools, token-aware memory, and structured output parsing.

Installation

pnpm add @llm-utils/agents
# or
npm install @llm-utils/agents

Features

• Tool Definition - Type-safe tool/function definitions with Zod schemas
• Memory Management - Token-aware conversation memory with windowing
• Output Parsing - Parse and validate structured LLM outputs
• Provider Agnostic - Works with OpenAI, Anthropic, and other providers
• Full TypeScript - Complete type safety with generics

Usage

Define Tools

import { defineTool, createToolExecutor, z } from '@llm-utils/agents';

// Define a tool with Zod schema
const weatherTool = defineTool({
  name: 'get_weather',
  description: 'Get current weather for a location',
  parameters: z.object({
    location: z.string().describe('City name'),
    units: z.enum(['celsius', 'fahrenheit']).optional(),
  }),
  execute: async ({ location, units }) => {
    // Your implementation
    return { temperature: 22, conditions: 'sunny' };
  },
});

// Create an executor
const executor = createToolExecutor([weatherTool]);

// Get tools in provider format
const openaiTools = executor.toOpenAI();
const anthropicTools = executor.toAnthropic();

// Execute a tool call from LLM response
const result = await executor.execute({
  id: 'call_123',
  name: 'get_weather',
  arguments: { location: 'San Francisco' },
});

Conversation Memory

import { createMemory, createSlidingWindowMemory } from '@llm-utils/agents';

// Token-aware memory with automatic windowing
const memory = createMemory({
  maxTokens: 4000,
  systemMessage: 'You are a helpful assistant.',
  preserveRecent: 3, // Always keep last 3 messages
});

// Add messages
memory.add({ role: 'user', content: 'Hello!' });
memory.add({ role: 'assistant', content: 'Hi there! How can I help?' });

// Get messages within token budget
const messages = memory.getMessages();

// Check memory stats
const stats = memory.getStats();
console.log(`Using ${stats.utilizationPercent}% of token budget`);

// Simple sliding window (last N messages)
const simpleMemory = createSlidingWindowMemory(20, 'System prompt here');

Structured Output Parsing

import { parseWithSchema, createSchemaParser, Parsers, z } from '@llm-utils/agents';

// Parse with a Zod schema
const result = parseWithSchema(
  llmResponse,
  z.object({
    answer: z.string(),
    confidence: z.number(),
  })
);

if (result.success) {
  console.log(result.data.answer);
}

// Create a reusable parser
const analysisParser = createSchemaParser(
  'Analysis',
  z.object({
    sentiment: z.enum(['positive', 'negative', 'neutral']),
    topics: z.array(z.string()),
    summary: z.string(),
  }),
  'Analyze the provided text'
);

// Get prompt instructions for the LLM
const instructions = analysisParser.getPromptInstructions();

// Parse response
const analysis = analysisParser.parseOrThrow(llmResponse);

// Use built-in parsers
const decision = Parsers.Decision.parse(llmResponse);
const sentiment = Parsers.Sentiment.parse(llmResponse);
const entities = Parsers.Entities.parse(llmResponse);

Summary-Based Memory

import { createSummaryMemory } from '@llm-utils/agents';

const memory = createSummaryMemory({
  maxMessages: 10,
  systemMessage: 'You are an assistant.',
  summarizer: async (messages) => {
    // Call LLM to summarize old messages
    const response = await llm.chat({
      messages: [
        { role: 'system', content: 'Summarize this conversation briefly.' },
        ...messages,
      ],
    });
    return response.content;
  },
});

// Periodically summarize old messages
await memory.summarize();

API Reference

Tools

• defineTool(config) - Define a tool with typed parameters
• createToolExecutor(tools?) - Create a tool executor
• toOpenAITool(tool) - Convert to OpenAI format
• toAnthropicTool(tool) - Convert to Anthropic format
• zodToJsonSchema(schema) - Convert Zod to JSON Schema

Memory

• createMemory(config) - Token-aware memory
• createSlidingWindowMemory(size, system?) - Simple sliding window
• createSummaryMemory(config) - Memory with summarization
• estimateTokens(text) - Rough token estimation

Output Parsing

• parseWithSchema(text, schema) - Parse and validate with Zod
• createSchemaParser(name, schema) - Create reusable parser
• extractJson(text) - Extract JSON from mixed content
• Parsers - Pre-built parsers for common patterns

Common Schemas

CommonSchemas.Decision    // Yes/no with reasoning
CommonSchemas.Sentiment   // Sentiment analysis
CommonSchemas.Entities    // Entity extraction
CommonSchemas.Classification // Classification result
CommonSchemas.Summary     // Text summary
CommonSchemas.ActionItems // Action item extraction

License

MIT