@agent-system/core

Core agent orchestration system - autonomous agents with LLM providers

A TypeScript library for building autonomous agent systems with support for multiple LLM providers (Anthropic Claude, OpenAI, OpenRouter), tool execution, agent delegation, and session management.

Features

• 🤖 Multi-Provider Support: Anthropic Claude, OpenAI, OpenRouter with automatic routing
• 🔧 Built-in Tools: File operations, grep, shell execution, agent delegation
• 💾 Session Management: Persistent sessions with automatic recovery
• 📊 Event Logging: Real-time event streaming for monitoring and debugging
• 🎯 Pull Architecture: Agents gather their own context via tools (efficient with Anthropic's prompt caching)
• 🛡️ Security: Built-in protections for sensitive files and dangerous commands
• ⚡ Smart Caching: Anthropic prompt caching for 90% cost savings on repeated context
• 🔄 MCP Integration: Model Context Protocol support for external tool servers

Installation

npm install @agent-system/core

Quick Start

import { AgentSystemBuilder } from '@agent-system/core';

// Build an agent system with default tools
const system = await AgentSystemBuilder.default()
  .withAgents(['./agents'])
  .build();

// Execute an agent
const result = await system.executor.execute('orchestrator', 'Analyze the codebase');
console.log(result);

// Clean up when done
await system.cleanup();

Configuration

Basic Setup

const system = await AgentSystemBuilder.default()
  .withAgents(['./my-agents'])
  .withSessionId('my-session')
  .withConsole({ enabled: true, color: true })
  .build();

Custom Tools

const myTool = {
  name: 'my_tool',
  description: 'Does something useful',
  parameters: {
    type: 'object',
    properties: {
      input: { type: 'string', description: 'Input text' }
    },
    required: ['input']
  },
  execute: async (params) => {
    return { content: `Processed: ${params.input}` };
  },
  isConcurrencySafe: () => true
};

const system = await AgentSystemBuilder.default()
  .withTools([myTool])
  .build();

MCP Server Integration

const system = await AgentSystemBuilder.default()
  .withMCPServers({
    filesystem: {
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp']
    }
  })
  .build();

Agent Definition

Create agents as markdown files with YAML frontmatter:

---
name: code-reviewer
description: Reviews code for quality and security
tools:
  - Read
  - Write
  - Grep
model: anthropic/claude-3-5-sonnet-latest
behavior: precise
---

You are an expert code reviewer. Review code for:
- Code quality and best practices
- Security vulnerabilities
- Performance issues
- Documentation completeness

Built-in Tools

• Read: Read files from the filesystem
• Write: Write files (with size limits)
• List: List directory contents
• Grep: Search file contents with ripgrep
• Delegate: Delegate subtasks to other agents
• TodoWrite: Task tracking for complex workflows
• Shell: Execute shell commands (with security restrictions)
• GetSessionLog: Retrieve conversation history

Event Logging

Subscribe to real-time events for monitoring and debugging:

system.eventLogger.on('agent:start', (event) => {
  console.log(`Agent ${event.data.agent} started`);
});

system.eventLogger.on('tool:execute', (event) => {
  console.log(`Tool ${event.data.name} executed`);
});

system.eventLogger.on('agent:complete', (event) => {
  console.log(`Agent completed in ${event.data.duration}ms`);
});

Session Management

// Sessions persist automatically
const system = await AgentSystemBuilder.default()
  .withSessionId('my-session')
  .withStorage({
    type: 'filesystem',
    path: './sessions'
  })
  .build();

// Continue from previous session
const result = await system.executor.execute('agent', 'Continue our conversation');

Security

Built-in security features:

• File Protection: Blocks access to sensitive files (.ssh, .aws, .env)
• Shell Security: Prevents dangerous commands (rm -rf /, fork bombs)
• Size Limits: 50MB read limit, 10MB write limit
• Timeouts: Configurable timeouts on all operations
• Path Validation: Prevents path traversal attacks

Configuration

Code-First Configuration (Recommended)

Configuration files are optional. You can provide configuration programmatically:

import { AgentSystemBuilder, type ProvidersConfig } from '@agent-system/core';

// Define providers config in code
const providersConfig: ProvidersConfig = {
  providers: {
    anthropic: {
      type: 'native',
      apiKeyEnv: 'ANTHROPIC_API_KEY',
      models: [
        {
          id: 'claude-haiku-4-5',
          contextLength: 200000,
          maxOutputTokens: 8192,
        },
      ],
    },
    openrouter: {
      type: 'openai-compatible',
      baseURL: 'https://openrouter.ai/api/v1',
      apiKeyEnv: 'OPENROUTER_API_KEY',
    },
  },
  behaviorPresets: {
    balanced: { temperature: 0.5, top_p: 0.85 },
    precise: { temperature: 0.2, top_p: 0.6 },
  },
};

// Provide API keys programmatically (e.g., from secret manager)
const apiKeys = {
  ANTHROPIC_API_KEY: await secretManager.get('anthropic-key'),
  OPENROUTER_API_KEY: await secretManager.get('openrouter-key'),
};

// Build with code-first configuration
const system = await AgentSystemBuilder.default()
  .withModel('anthropic/claude-haiku-4-5')
  .withProvidersConfig(providersConfig)
  .withAPIKeys(apiKeys)
  .build();

Benefits:

• No file dependencies - ideal for testing and CI/CD
• Secret manager integration (AWS Secrets Manager, Vault, etc.)
• Type-safe configuration with full TypeScript support
• Dynamic configuration at runtime

API Key Precedence:

1. .withAPIKeys() - highest priority
2. process.env - fallback

Configuration Files (Optional)

Alternatively, use configuration files for simpler setups.

providers-config.json

Configure LLM providers and behavior presets:

{
  "behaviorPresets": {
    "deterministic": { "temperature": 0.1, "top_p": 0.5 },
    "precise": { "temperature": 0.2, "top_p": 0.6 },
    "balanced": { "temperature": 0.5, "top_p": 0.85 },
    "creative": { "temperature": 0.7, "top_p": 0.95 }
  },
  "providers": {
    "anthropic": {
      "type": "native",
      "apiKeyEnv": "ANTHROPIC_API_KEY"
    },
    "openrouter": {
      "type": "openai-compatible",
      "baseURL": "https://openrouter.ai/api/v1",
      "apiKeyEnv": "OPENROUTER_API_KEY"
    }
  }
}

agent-config.json

Set system-wide defaults:

{
  "defaultModel": "anthropic/claude-haiku-4-5",
  "defaultBehavior": "balanced"
}

Environment Variables

# At least one API key required:
ANTHROPIC_API_KEY=your-anthropic-key
OPENROUTER_API_KEY=your-openrouter-key

# Optional:
DISABLE_PROMPT_CACHING=true  # Disable Anthropic prompt caching

Testing

# Unit tests (no API calls)
npm test

# Integration tests (requires API key)
npm run test:integration

# All tests
npm run test:all

Examples

See the examples directory for complete working examples:

• quickstart.ts: Basic agent execution
• orchestration.ts: Agent delegation demo
• configuration.ts: Configuration options
• logging.ts: Event logging
• mcp-integration.ts: MCP server integration
• werewolf-game.ts: Autonomous multi-agent game

API Reference

AgentSystemBuilder

class AgentSystemBuilder {
  static default(): AgentSystemBuilder;
  static minimal(): AgentSystemBuilder;
  static forTest(): AgentSystemBuilder;
  static fromConfigFile(path: string): Promise<AgentSystemBuilder>;

  withAgents(dirs: string[]): this;
  withTools(tools: BaseTool[]): this;
  withModel(model: string): this;
  withSessionId(id: string): this;
  withConsole(config: ConsoleConfig): this;
  withMCPServers(servers: MCPConfig): this;
  withProvidersConfig(config: ProvidersConfig): this;  // NEW
  withAPIKeys(keys: Record<string, string>): this;     // NEW

  async build(): Promise<BuildResult>;
}

BuildResult

interface BuildResult {
  executor: AgentExecutor;
  toolRegistry: ToolRegistry;
  sessionManager: SessionManager;
  storage: SessionStorage;
  logger: AgentLogger;
  eventLogger: EventLogger;
  config: ResolvedSystemConfig;
  cleanup: () => Promise<void>;
}

License

MIT

Contributing

Contributions welcome! Please read the contributing guidelines before submitting PRs.

Links

• Documentation
• Examples
• GitHub Issues