@agenite/agent NPM

@agenite/agent

A powerful and flexible TypeScript library for building AI agents with advanced tool integration and state management capabilities.

Features

🛠️ Advanced tool integration - Seamlessly integrate custom tools and APIs with type safety
🔄 Stateful conversations - Built-in state management with custom reducers
🌊 Streaming support - Real-time streaming of agent responses and tool executions
🎯 Execution context - Track and manage nested agent executions with context inheritance
🔌 Provider agnostic - Support for multiple LLM providers (Ollama, Bedrock)
🎨 Flexible architecture - Build simple to complex agent hierarchies with middleware support
📊 Token usage tracking - Monitor and optimize token consumption across executions
🔄 Step-based execution - Fine-grained control over agent execution flow

Installation

npm install @agenite/agent

Quick start

import { Agent } from '@agenite/agent';
import { OllamaProvider } from '@agenite/ollama';

// Create a simple calculator tool
const calculatorTool = new Tool({
  name: 'calculator',
  description: 'Perform basic math operations',
  execute: async ({ input }) => {
    // Tool implementation
    return { success: true, data: result.toString() };
  },
});

// Initialize the agent
const agent = new Agent({
  name: 'math-buddy',
  provider: new OllamaProvider({ model: 'llama2' }),
  tools: [calculatorTool],
  instructions: 'You are a helpful math assistant.',
});

// Execute the agent
const result = await agent.execute({
  messages: [{ role: 'user', content: [{ type: 'text', text: 'What is 1234 * 5678?' }] }],
});

Core concepts

Agent

The main class that orchestrates interactions between the LLM and tools. It handles:

Message processing and state management
Tool execution and result handling
Response streaming
Nested agent execution
Token usage tracking

Tools

Tools are functions that agents can use to perform specific tasks. Each tool has:

Name and description
Input schema with type safety
Execute function with context support
Error handling capabilities

Providers

LLM providers that handle the actual language model interactions:

Ollama
Amazon Bedrock
Extensible for other providers

Steps

The agent execution is broken down into steps:

llm-call - Handles LLM interactions
tool-call - Manages tool execution
tool-result - Processes tool results
agent-call - Handles nested agent execution

Advanced usage

Stateful agent with custom reducer

const customReducer = {
  messages: (newValue, previousValue) => [
    ...(previousValue || []),
    ...(newValue || []),
  ],
  runningTotal: (newValue, previousValue) =>
    (previousValue || 0) + (newValue || 0),
};

const agent = new Agent({
  name: 'stateful-calculator',
  provider,
  tools: [calculatorTool],
  stateReducer: customReducer,
  initialState: {
    runningTotal: 0,
  },
  instructions:
    'You are a helpful math assistant that maintains a running total.',
});

Nested agents with delegation

// Specialist agents
const calculatorAgent = new Agent({
  name: 'calculator-specialist',
  provider,
  tools: [calculatorTool],
  description: 'Specializes in mathematical calculations',
});

const weatherAgent = new Agent({
  name: 'weather-specialist',
  provider,
  tools: [weatherTool],
  description: 'Provides weather information',
});

// Coordinator agent
const coordinatorAgent = new Agent({
  name: 'coordinator',
  provider,
  agents: [calculatorAgent, weatherAgent],
  instructions:
    'Coordinate between specialist agents to solve complex problems.',
});

Streaming responses with middleware

const agent = new Agent({
  name: 'streaming-agent',
  provider,
  tools: [calculatorTool],
  middlewares: [
    executionContextInjector(),
    // Add custom middleware here
  ],
});

const iterator = agent.iterate({
  messages: [{ role: 'user', content: [{ type: 'text', text: 'Your query here' }] }],
  stream: true,
});

for await (const chunk of iterator) {
  switch (chunk.type) {
    case 'agenite.llm-call.streaming':
      console.log(chunk.content);
      break;
    case 'agenite.tool-call.params':
      console.log('Using tool:', chunk.toolUseBlocks);
      break;
    case 'agenite.tool-result':
      console.log('Tool result:', chunk.result);
      break;
  }
}

API reference

Agent constructor

new Agent({
  name: string;
  provider: LLMProvider;
  tools?: Tool[];
  instructions?: string;
  description?: string;
  agents?: Agent[];
  stateReducer?: CustomStateReducer;
  initialState?: Partial<StateFromReducer<CustomStateReducer>>;
  steps?: Steps;
  middlewares?: Middlewares;
})

Execute method

execute({
  messages: BaseMessage[];
  stream?: boolean;
  context?: Record<string, unknown>;
}): Promise<ExecutionResult>

Iterate method

iterate({
  messages: BaseMessage[];
  stream?: boolean;
  context?: Record<string, unknown>;
}): AsyncIterator<StreamChunk>

Examples

Check out the examples directory for more detailed examples:

basic/ - Simple examples showing core functionality
- simple-chat.ts - Basic chat agent with calculator tool
advanced/ - More complex examples
- nested-agents.ts - Agent composition and delegation
- stateful-agent.ts - Maintaining conversation state
- streaming-agent.ts - Real-time response streaming
- multi-tool-agent.ts - Using multiple tools