keyring-agent-core

Core AI chat agent package with multi-agent architecture, ReAct agentic pattern, and a modular tool system — powered by Google Gemini.

Architecture

User Message
     │
     ▼
┌─────────────────┐
│   AgentCore      │  ← Orchestrator
│  (chat history)  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    Planner       │  ← Analyses query, decides which tools to call
└────────┬────────┘
         │  ExecutionPlan
         ▼
┌─────────────────┐
│    Executor      │  ← ReAct loop: Think → Act → Observe
│  (Tool calls)    │
└────────┬────────┘
         │  ReActTrace
         ▼
┌─────────────────┐
│   Synthesizer    │  ← Produces polished user-facing answer
└─────────────────┘

Key patterns

• Plan → Task → Get Data → Answer: The Planner creates a structured execution plan; the Executor runs tools and gathers data; the Synthesizer produces the answer.
• ReAct (Reason + Act): The Executor uses a Think → Act → Observe loop, allowing multi-step reasoning with tool calls.
• Multi-agent: Planner, Executor, and Synthesizer are independent agents, each with specialised system prompts.
• Conversation memory: Automatic chat history management with LLM-based summarisation when the conversation grows too long.

Quick Start

import { AgentCore, BaseTool, ToolParameter } from 'keyring-agent-core';

// 1. Create a tool
class FaqTool extends BaseTool {
  name = 'get-faq';
  description = 'Fetch FAQ data from the CoinPool API';
  parameters: ToolParameter[] = [
    {
      name: 'query',
      type: 'string',
      description: 'Search query for FAQ',
      required: false,
    },
  ];

  protected async run(args: Record<string, unknown>) {
    const res = await fetch('https://api.coinpool.app/faq');
    return res.json();
  }
}

// 2. Initialise the agent
const agent = new AgentCore({
  llm: {
    apiKey: process.env.GEMINI_API_KEY!,
    model: 'gemini-2.5-flash-lite',
  },
  maxIterations: 8,
  maxHistoryMessages: 40,
  systemPrompt: 'You are the CoinPool assistant. Help users with their questions.',
  debug: true,
});

// 3. Register tools
agent.registerTool(new FaqTool());

// 4. Chat
const response = await agent.chat('What are the fees on CoinPool?');
console.log(response.answer);

Creating Custom Tools

Extend BaseTool and implement the run() method:

import { BaseTool, ToolParameter } from 'keyring-agent-core';

class MoralisAITool extends BaseTool {
  name = 'moralis-ai';
  description = 'Call Moralis AI for blockchain analysis';
  category = 'ai';
  parameters: ToolParameter[] = [
    { name: 'prompt', type: 'string', description: 'Prompt for Moralis AI', required: true },
  ];

  protected async run(args: Record<string, unknown>) {
    const response = await fetch('https://your-moralis-endpoint.com/ai', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ prompt: args.prompt }),
    });
    return response.json();
  }
}

Each tool is independent — add or remove tools without affecting others.

Chat History & Summarisation

The agent automatically manages conversation history:

• Messages are stored in a ChatHistory instance
• When the history exceeds maxHistoryMessages, it is automatically summarised using the LLM and compacted
• You can persist/restore history:

// Save
const data = agent.serialiseHistory();
await saveToDatabase(data);

// Restore
const saved = await loadFromDatabase();
agent.restoreHistory(saved);

API Reference

AgentCore

| Method | Description | | -------------------------- | ---------------------------------------- | | chat(message: string) | Process a user message and get an answer | | registerTool(tool) | Register a tool | | registerTools(tools) | Register multiple tools | | unregisterTool(name) | Remove a tool | | listTools() | List registered tool names | | getHistory() | Get full conversation history | | clearHistory() | Clear conversation history | | serialiseHistory() | Serialise history for persistence | | restoreHistory(messages) | Restore history from saved data |

AgentConfig

{
  llm: {
    apiKey: string;
    model?: string;        // default: 'gemini-2.5-flash-lite'
    maxTokens?: number;    // default: 4096
    temperature?: number;  // default: 0.7
  };
  maxIterations?: number;       // default: 10
  maxHistoryMessages?: number;  // default: 50
  systemPrompt?: string;
  debug?: boolean;
}

License

MIT