@llm-utils/agents

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

Installation

``bash
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

$3

`typescript
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' },
});
`

$3

`typescript
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');
`

$3

`typescript
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);
`

$3

`typescript
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

$3

- 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

$3

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

$3

- 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

$3

`typescript
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