NestJS Base Agent

A flexible and reusable NestJS library for building AI agent systems with Ollama integration.

Features

• 🔧 Configurable: Define your own agent types, models, and system prompts
• 🎯 Type-safe: Full TypeScript support with generic types
• 🛠️ Tool support: Built-in support for function calling and tool execution
• 🔄 Streaming: Real-time streaming responses with thinking/content separation
• 📝 Logging: Comprehensive logging for debugging and monitoring
• 🎮 Flexible: Use for any type of AI agent (content, gaming, data processing, etc.)

Installation

npm install @dimrev4/nest-base-agent ollama
# or
pnpm add @dimrev4/nest-base-agent ollama

Quick Start

1. Define Your Agent Types

// Define your agent types
type MyAgentType = 'content-writer' | 'data-processor' | 'code-reviewer';

// Define your model types
type MyModelType = 'llama3.1:8b' | 'phi3:14b' | 'qwen2.5:14b-instruct';

2. Create Configuration

import { AgentServiceConfig } from '@dimrev4/nest-base-agent';

const agentConfig: AgentServiceConfig<MyAgentType, MyModelType> = {
  routing: {
    'content-writer': 'llama3.1:8b',
    'data-processor': 'phi3:14b',
    'code-reviewer': 'qwen2.5:14b-instruct'
  },
  defaults: {
    'content-writer': {
      temperature: 0.7,
      top_p: 0.9,
      systemPrompt: 'You are a creative content writer with expertise in engaging storytelling.'
    },
    'data-processor': {
      temperature: 0.1,
      top_p: 0.7,
      systemPrompt: 'You are a data processing expert focused on accuracy and structure.'
    },
    'code-reviewer': {
      temperature: 0.2,
      top_p: 0.8,
      systemPrompt: 'You are a senior code reviewer focused on best practices and security.'
    }
  }
};

3. Create and Use the Service

import { Injectable } from '@nestjs/common';
import { AgentService } from '@dimrev4/nest-base-agent';

@Injectable()
export class MyService {
  private readonly agentService: AgentService;

  constructor() {
    // Create the agent service
    this.agentService = new AgentService(agentConfig, {
      isDebug: true,
      toolCallIterations: 5
    });
  }

  async generateContent(prompt: string) {
    // Get agent configuration
    const options = this.agentService.getAgentOptions('content-writer');

    // Run the agent
    const response = await this.agentService.runAgent(
      prompt,
      'content-writer', // agent type
      [], // conversation history
      { 
        model: options.model,
        temperature: options.temperature,
        top_p: options.top_p,
        systemPrompt: options.systemPrompt
      }
    );

    return response;
  }
}

Advanced Usage

With Tools

const tools = {
  search_web: async (args: { query: string }) => {
    // Your tool implementation
    return await searchWeb(args.query);
  }
};

const response = await agentService.runAgent(
  'Find information about TypeScript',
  'content-writer',
  [],
  {
    model: 'llama3.1:8b',
    temperature: 0.5,
    systemPrompt: 'You are a helpful assistant with web search capabilities.'
  },
  tools
);

With Conversation History

const history = [
  { role: 'user', content: 'What is TypeScript?' },
  { role: 'assistant', content: 'TypeScript is a strongly typed programming language...' }
];

const response = await agentService.runAgent(
  'Can you give me an example?',
  'content-writer',
  history,
  {
    model: 'llama3.1:8b',
    systemPrompt: 'You are a helpful programming assistant.'
  }
);

Configuration

Agent Configuration Interface

interface AgentServiceConfig<TAgentType, TModel> {
  routing: AgentRouting<TAgentType, TModel>;
  defaults: AgentDefaults<TAgentType>;
}

interface AgentConfig {
  temperature: number;    // 0.0 to 2.0
  top_p: number;         // 0.0 to 1.0
  systemPrompt: string;  // System prompt for the agent
}

type AgentRouting<TAgentType, TModel> = {
  [key in TAgentType]: TModel;
};

type AgentDefaults<TAgentType> = {
  [key in TAgentType]: AgentConfig;
};

Service Options

interface AgentServiceOptions {
  isDebug: boolean;           // Enable debug logging
  toolCallIterations: number; // Max iterations for tool calls
  logger?: Logger;           // Optional custom logger
}

API Reference

AgentService

Main service class for running AI agents.

Constructor

constructor(
  config: AgentServiceConfig<TAgentType, TModel>,
  options: AgentServiceOptions
)

Methods

runAgent(prompt, agentType, history, runOptions, tools?)

Runs an agent with the specified parameters.

Parameters:

• prompt: User prompt/message
• agentType: The type of agent to use
• history: Previous conversation messages
• runOptions: Runtime options (model, temperature, etc.)
• tools: Optional tool functions for function calling

Returns: Promise<string>

getAgentOptions(agentType, overrides?)

Gets the default options for a specific agent type.

Parameters:

• agentType: The agent type to get options for
• overrides: Optional parameter overrides

Returns: Agent options object with model, temperature, top_p, and systemPrompt

License

MIT

Repository

• GitHub: DimRev/nest-base-agent
• NPM: @dimrev4/nest-base-agent

Configuration

Environment Variables

Make sure to set the following environment variable:

OLLAMA_HOST=http://localhost:11434

Agent Configuration Interface

interface AgentLibraryConfig<TAgentType, TModel> {
  routing: Record<TAgentType, TModel>;
  defaults: Record<TAgentType, AgentConfig>;
}

interface AgentConfig {
  temperature: number;    // 0.0 to 2.0
  top_p: number;         // 0.0 to 1.0
  systemPrompt: string;  // System prompt for the agent
}

API Reference

createAgentService(ollamaHost, agentConfig)

Creates a new AgentService instance with the provided configuration.

Parameters:

• ollamaHost: The Ollama host URL (e.g., 'http://localhost:11434')
• agentConfig: Your agent configuration object

Returns: AgentService<TAgentType, TModel>

validateAgentConfig(config)

Validates your agent configuration to ensure it's properly structured.

Parameters:

• config: Your agent configuration object

Throws: Error if configuration is invalid

agentService.runAgent(prompt, systemPrompt, history, tag, model, options?)

Runs an agent with the specified parameters.

Parameters:

• prompt: User prompt/message
• systemPrompt: System prompt for the agent
• history: Previous conversation messages
• tag: Tag for logging (default: 'assistant')
• model: Model to use
• options: Optional generation options (tools, temperature, etc.)

Returns: Promise<Message[]>

agentService.getAgentOptions(agentType, overrides?)

Gets the default options for a specific agent type.

Parameters:

• agentType: The agent type to get options for
• overrides: Optional parameter overrides

Returns: Agent options object

Examples

See the examples directory for complete configuration examples.

License

MIT