@hashgraphonline/standards-agent-kit 0.2.101 → 0.2.103

package/src/tools/hcs10/FindRegistrationsTool.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { AIAgentCapability } from '@hashgraphonline/standards-sdk';
 import { BaseHCS10QueryTool } from './base-hcs10-tools';
 import { HCS10QueryToolParams } from './hcs10-tool-params';
+import { NaturalLanguageMapper } from './natural-language-mapper';
 
 /**
  * A tool to search for registered HCS-10 agents using the configured registry.
@@ -14,10 +15,24 @@ const FindRegistrationsZodSchema = z.object({
       'Optional: Filter registrations by a specific Hedera account ID (e.g., 0.0.12345).'
     ),
   tags: z
-    .array(z.nativeEnum(AIAgentCapability))
+    .union([
+      z.array(z.nativeEnum(AIAgentCapability)),
+      z.array(z.string()),
+      z.string(),
+    ])
     .optional()
+    .transform((val) => {
+      if (!val) return undefined;
+      if (typeof val === 'string') {
+        return NaturalLanguageMapper.parseCapabilities(val);
+      }
+      if (Array.isArray(val) && val.length > 0 && typeof val[0] === 'string') {
+        return NaturalLanguageMapper.parseTagsOrCapabilities(val);
+      }
+      return val as AIAgentCapability[];
+    })
     .describe(
-      'Optional: Filter registrations by a list of tags (API filter only).'
+      'Optional: Filter by capabilities/tags like "ai", "data", "analytics". Can be natural language terms or capability numbers.'
     ),
 });
 
@@ -26,7 +41,7 @@ export class FindRegistrationsTool extends BaseHCS10QueryTool<
 > {
   name = 'find_registrations';
   description =
-    'Searches the configured agent registry for HCS-10 agents. You can filter by account ID or tags. Returns basic registration info.';
+    'Searches the configured agent registry for HCS-10 agents. You can filter by account ID or tags/capabilities using natural language like "ai", "data processing", "analytics". Returns basic registration info.';
   specificInputSchema = FindRegistrationsZodSchema;
   constructor(params: HCS10QueryToolParams) {
     super(params);
@@ -42,7 +57,7 @@ export class FindRegistrationsTool extends BaseHCS10QueryTool<
       params.accountId = accountId;
     }
     if (tags) {
-      params.tags = tags;
+      params.tags = tags as number[];
     }
     await hcs10Builder.findRegistrations(params);
 

package/src/tools/hcs10/RegisterAgentTool.ts

@@ -9,6 +9,7 @@ import {
 import { BaseHCS10TransactionTool } from './base-hcs10-tools';
 import { HCS10TransactionToolParams } from './hcs10-tool-params';
 import { RegisteredAgent } from '../../state/state-types';
+import { NaturalLanguageMapper } from './natural-language-mapper';
 
 const RegisterAgentZodSchema = z.object({
   name: z
@@ -44,9 +45,37 @@ const RegisterAgentZodSchema = z.object({
     .optional()
     .describe('AI model identifier (default: agent-model-2024)'),
   capabilities: z
-    .array(z.nativeEnum(AIAgentCapability))
+    .union([
+      z.array(z.nativeEnum(AIAgentCapability)),
+      z.array(z.string()),
+      z.string(),
+    ])
+    .optional()
+    .transform((val) => {
+      if (!val) return undefined;
+      if (typeof val === 'string') {
+        return NaturalLanguageMapper.parseCapabilities(val);
+      }
+      if (Array.isArray(val) && val.length > 0 && typeof val[0] === 'string') {
+        return NaturalLanguageMapper.parseTagsOrCapabilities(val);
+      }
+      return val as AIAgentCapability[];
+    })
+    .describe('Agent capabilities - can be capability names (e.g. "ai", "data processing"), capability enum values, or array of either. Common values: "ai"/"text" (TEXT_GENERATION), "data" (DATA_INTEGRATION), "analytics" (TRANSACTION_ANALYTICS)'),
+  tags: z
+    .union([
+      z.array(z.string()),
+      z.string(),
+    ])
     .optional()
-    .describe('Array of agent capabilities (default: [TEXT_GENERATION])'),
+    .transform((val) => {
+      if (!val) return undefined;
+      if (typeof val === 'string') {
+        return NaturalLanguageMapper.parseCapabilities(val);
+      }
+      return NaturalLanguageMapper.parseTagsOrCapabilities(val);
+    })
+    .describe('Tags for the agent (alternative to capabilities) - e.g. "ai", "data", "analytics". Will be converted to appropriate capabilities.'),
   creator: z.string().optional().describe('Creator attribution for the agent'),
   socials: z
     .record(
@@ -139,7 +168,7 @@ export class RegisterAgentTool extends BaseHCS10TransactionTool<
 > {
   name = 'register_agent';
   description =
-    'Creates and registers the AI agent on the Hedera network. Returns JSON string with agent details (accountId, privateKey, topics) on success. Note: This tool requires multiple transactions and cannot be used in returnBytes mode. If alias is set to "random" or contains "random", a unique alias will be generated.';
+    'Creates and registers the AI agent on the Hedera network. Returns JSON string with agent details (accountId, privateKey, topics) on success. Supports natural language for capabilities/tags like "ai", "data processing", "analytics". Note: This tool requires multiple transactions and cannot be used in returnBytes mode. If alias is set to "random" or contains "random", a unique alias will be generated.';
   specificInputSchema = RegisterAgentZodSchema;
   private specificArgs: z.infer<typeof RegisterAgentZodSchema> | undefined;
 
@@ -174,8 +203,11 @@ export class RegisterAgentTool extends BaseHCS10TransactionTool<
     if (specificArgs.model !== undefined) {
       params.model = specificArgs.model;
     }
-    if (specificArgs.capabilities !== undefined) {
-      params.capabilities = specificArgs.capabilities;
+    // Handle both capabilities and tags (tags takes precedence if both provided)
+    if (specificArgs.tags !== undefined) {
+      params.capabilities = specificArgs.tags as AIAgentCapability[];
+    } else if (specificArgs.capabilities !== undefined) {
+      params.capabilities = specificArgs.capabilities as AIAgentCapability[];
     }
     if (specificArgs.creator !== undefined) {
       params.creator = specificArgs.creator;

package/src/tools/hcs10/index.ts

@@ -10,4 +10,5 @@ export * from './ConnectionMonitorTool';
 export * from './ManageConnectionRequestsTool';
 export * from './AcceptConnectionRequestTool';
 export * from './RetrieveProfileTool';
-export * from './ListUnapprovedConnectionRequestsTool';
+export * from './ListUnapprovedConnectionRequestsTool';
+export * from './natural-language-mapper';

package/src/tools/hcs10/natural-language-mapper.ts

@@ -0,0 +1,194 @@
+import { AIAgentCapability } from '@hashgraphonline/standards-sdk';
+
+/**
+ * Maps natural language terms to AIAgentCapability enum values
+ */
+export class NaturalLanguageMapper {
+  private static readonly CAPABILITY_MAPPINGS: Record<string, AIAgentCapability[]> = {
+    // Common terms
+    'ai': [AIAgentCapability.TEXT_GENERATION],
+    'artificial intelligence': [AIAgentCapability.TEXT_GENERATION],
+    'chat': [AIAgentCapability.TEXT_GENERATION],
+    'conversation': [AIAgentCapability.TEXT_GENERATION],
+    'text': [AIAgentCapability.TEXT_GENERATION],
+    'text generation': [AIAgentCapability.TEXT_GENERATION],
+    
+    // Image
+    'image': [AIAgentCapability.IMAGE_GENERATION],
+    'picture': [AIAgentCapability.IMAGE_GENERATION],
+    'visual': [AIAgentCapability.IMAGE_GENERATION],
+    'photo': [AIAgentCapability.IMAGE_GENERATION],
+    
+    // Audio
+    'audio': [AIAgentCapability.AUDIO_GENERATION],
+    'sound': [AIAgentCapability.AUDIO_GENERATION],
+    'voice': [AIAgentCapability.AUDIO_GENERATION],
+    'speech': [AIAgentCapability.AUDIO_GENERATION],
+    
+    // Video
+    'video': [AIAgentCapability.VIDEO_GENERATION],
+    'movie': [AIAgentCapability.VIDEO_GENERATION],
+    'animation': [AIAgentCapability.VIDEO_GENERATION],
+    
+    // Code
+    'code': [AIAgentCapability.CODE_GENERATION],
+    'programming': [AIAgentCapability.CODE_GENERATION],
+    'development': [AIAgentCapability.CODE_GENERATION],
+    'coding': [AIAgentCapability.CODE_GENERATION],
+    
+    // Translation
+    'translate': [AIAgentCapability.LANGUAGE_TRANSLATION],
+    'translation': [AIAgentCapability.LANGUAGE_TRANSLATION],
+    'language': [AIAgentCapability.LANGUAGE_TRANSLATION],
+    
+    // Summarization
+    'summarize': [AIAgentCapability.SUMMARIZATION_EXTRACTION],
+    'summary': [AIAgentCapability.SUMMARIZATION_EXTRACTION],
+    'extract': [AIAgentCapability.SUMMARIZATION_EXTRACTION],
+    'extraction': [AIAgentCapability.SUMMARIZATION_EXTRACTION],
+    
+    // Knowledge
+    'knowledge': [AIAgentCapability.KNOWLEDGE_RETRIEVAL],
+    'search': [AIAgentCapability.KNOWLEDGE_RETRIEVAL],
+    'retrieve': [AIAgentCapability.KNOWLEDGE_RETRIEVAL],
+    'lookup': [AIAgentCapability.KNOWLEDGE_RETRIEVAL],
+    
+    // Data
+    'data': [AIAgentCapability.DATA_INTEGRATION],
+    'data processing': [AIAgentCapability.DATA_INTEGRATION],
+    'data integration': [AIAgentCapability.DATA_INTEGRATION],
+    'etl': [AIAgentCapability.DATA_INTEGRATION],
+    
+    // Market
+    'market': [AIAgentCapability.MARKET_INTELLIGENCE],
+    'trading': [AIAgentCapability.MARKET_INTELLIGENCE],
+    'finance': [AIAgentCapability.MARKET_INTELLIGENCE],
+    'financial': [AIAgentCapability.MARKET_INTELLIGENCE],
+    
+    // Analytics
+    'analytics': [AIAgentCapability.TRANSACTION_ANALYTICS],
+    'analysis': [AIAgentCapability.TRANSACTION_ANALYTICS],
+    'analyze': [AIAgentCapability.TRANSACTION_ANALYTICS],
+    'transactions': [AIAgentCapability.TRANSACTION_ANALYTICS],
+    
+    // Smart Contract
+    'audit': [AIAgentCapability.SMART_CONTRACT_AUDIT],
+    'contract': [AIAgentCapability.SMART_CONTRACT_AUDIT],
+    'smart contract': [AIAgentCapability.SMART_CONTRACT_AUDIT],
+    
+    // Governance
+    'governance': [AIAgentCapability.GOVERNANCE_FACILITATION],
+    'voting': [AIAgentCapability.GOVERNANCE_FACILITATION],
+    'dao': [AIAgentCapability.GOVERNANCE_FACILITATION],
+    
+    // Security
+    'security': [AIAgentCapability.SECURITY_MONITORING],
+    'monitoring': [AIAgentCapability.SECURITY_MONITORING],
+    'threat': [AIAgentCapability.SECURITY_MONITORING],
+    
+    // Compliance
+    'compliance': [AIAgentCapability.COMPLIANCE_ANALYSIS],
+    'regulatory': [AIAgentCapability.COMPLIANCE_ANALYSIS],
+    'regulation': [AIAgentCapability.COMPLIANCE_ANALYSIS],
+    
+    // Fraud
+    'fraud': [AIAgentCapability.FRAUD_DETECTION],
+    'detection': [AIAgentCapability.FRAUD_DETECTION],
+    'anomaly': [AIAgentCapability.FRAUD_DETECTION],
+    
+    // Multi-agent
+    'coordination': [AIAgentCapability.MULTI_AGENT_COORDINATION],
+    'multi-agent': [AIAgentCapability.MULTI_AGENT_COORDINATION],
+    'orchestration': [AIAgentCapability.MULTI_AGENT_COORDINATION],
+    
+    // API
+    'api': [AIAgentCapability.API_INTEGRATION],
+    'integration': [AIAgentCapability.API_INTEGRATION],
+    'webhook': [AIAgentCapability.API_INTEGRATION],
+    
+    // Workflow
+    'workflow': [AIAgentCapability.WORKFLOW_AUTOMATION],
+    'automation': [AIAgentCapability.WORKFLOW_AUTOMATION],
+    'process': [AIAgentCapability.WORKFLOW_AUTOMATION],
+  };
+
+  /**
+   * Parse natural language text and extract capability values
+   */
+  static parseCapabilities(text: string): AIAgentCapability[] {
+    if (!text) return [AIAgentCapability.TEXT_GENERATION];
+    
+    const normalizedText = text.toLowerCase();
+    const capabilities = new Set<AIAgentCapability>();
+    
+    // Check for exact matches first
+    for (const [term, caps] of Object.entries(this.CAPABILITY_MAPPINGS)) {
+      if (normalizedText.includes(term)) {
+        caps.forEach(cap => capabilities.add(cap));
+      }
+    }
+    
+    // Default to TEXT_GENERATION if no capabilities found
+    if (capabilities.size === 0) {
+      capabilities.add(AIAgentCapability.TEXT_GENERATION);
+    }
+    
+    return Array.from(capabilities);
+  }
+
+  /**
+   * Parse tags/capabilities from various input formats
+   */
+  static parseTagsOrCapabilities(input: any): AIAgentCapability[] {
+    // If already an array of numbers, return as is
+    if (Array.isArray(input) && input.every(item => typeof item === 'number')) {
+      return input;
+    }
+    
+    // If array of strings, parse each
+    if (Array.isArray(input) && input.every(item => typeof item === 'string')) {
+      const capabilities = new Set<AIAgentCapability>();
+      input.forEach(term => {
+        this.parseCapabilities(term).forEach(cap => capabilities.add(cap));
+      });
+      return Array.from(capabilities);
+    }
+    
+    // If single string, parse it
+    if (typeof input === 'string') {
+      return this.parseCapabilities(input);
+    }
+    
+    // Default
+    return [AIAgentCapability.TEXT_GENERATION];
+  }
+
+  /**
+   * Convert capability enum to human-readable name
+   */
+  static getCapabilityName(capability: AIAgentCapability): string {
+    const names: Record<AIAgentCapability, string> = {
+      [AIAgentCapability.TEXT_GENERATION]: 'Text Generation',
+      [AIAgentCapability.IMAGE_GENERATION]: 'Image Generation',
+      [AIAgentCapability.AUDIO_GENERATION]: 'Audio Generation',
+      [AIAgentCapability.VIDEO_GENERATION]: 'Video Generation',
+      [AIAgentCapability.CODE_GENERATION]: 'Code Generation',
+      [AIAgentCapability.LANGUAGE_TRANSLATION]: 'Language Translation',
+      [AIAgentCapability.SUMMARIZATION_EXTRACTION]: 'Summarization & Extraction',
+      [AIAgentCapability.KNOWLEDGE_RETRIEVAL]: 'Knowledge Retrieval',
+      [AIAgentCapability.DATA_INTEGRATION]: 'Data Integration',
+      [AIAgentCapability.MARKET_INTELLIGENCE]: 'Market Intelligence',
+      [AIAgentCapability.TRANSACTION_ANALYTICS]: 'Transaction Analytics',
+      [AIAgentCapability.SMART_CONTRACT_AUDIT]: 'Smart Contract Audit',
+      [AIAgentCapability.GOVERNANCE_FACILITATION]: 'Governance Facilitation',
+      [AIAgentCapability.SECURITY_MONITORING]: 'Security Monitoring',
+      [AIAgentCapability.COMPLIANCE_ANALYSIS]: 'Compliance Analysis',
+      [AIAgentCapability.FRAUD_DETECTION]: 'Fraud Detection',
+      [AIAgentCapability.MULTI_AGENT_COORDINATION]: 'Multi-Agent Coordination',
+      [AIAgentCapability.API_INTEGRATION]: 'API Integration',
+      [AIAgentCapability.WORKFLOW_AUTOMATION]: 'Workflow Automation',
+    };
+    
+    return names[capability] || 'Unknown Capability';
+  }
+}

package/src/tools/hcs2/CreateRegistryTool.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { BaseHCS2QueryTool } from './base-hcs2-tools';
+import { HCS2RegistryType } from '@hashgraphonline/standards-sdk';
+import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+
+/**
+ * Schema for creating an HCS-2 registry
+ */
+const createRegistrySchema = z.object({
+  registryType: z
+    .nativeEnum(HCS2RegistryType)
+    .optional()
+    .describe('Registry type: 0 for indexed, 1 for non-indexed (default: 0)'),
+  ttl: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe('Time to live in seconds (default: 86400)'),
+  adminKey: z
+    .union([z.string(), z.boolean()])
+    .optional()
+    .describe('Admin key: public key string or true to use operator key'),
+  submitKey: z
+    .union([z.string(), z.boolean()])
+    .optional()
+    .describe('Submit key: public key string or true to use operator key'),
+});
+
+/**
+ * Tool for creating HCS-2 registries
+ */
+export class CreateRegistryTool extends BaseHCS2QueryTool<typeof createRegistrySchema> {
+  name = 'createHCS2Registry';
+  description = 'Create a new HCS-2 registry topic for storing decentralized data';
+
+  get specificInputSchema() {
+    return createRegistrySchema;
+  }
+
+  protected async executeQuery(
+    params: z.infer<typeof createRegistrySchema>,
+    _runManager?: CallbackManagerForToolRun
+  ): Promise<unknown> {
+    try {
+      const result = await this.hcs2Builder.createRegistry({
+        registryType: params.registryType,
+        ttl: params.ttl,
+        adminKey: params.adminKey,
+        submitKey: params.submitKey,
+      });
+
+      if (!result.success) {
+        throw new Error(result.error || 'Failed to create registry');
+      }
+
+      return `Successfully created HCS-2 registry!\n\nTopic ID: ${result.topicId}\nRegistry Type: ${params.registryType === 1 ? 'Non-Indexed' : 'Indexed'}\nTTL: ${params.ttl || 86400} seconds\n\nYou can now register entries to this registry using the topic ID.`;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Failed to create HCS-2 registry';
+      throw new Error(`Registry creation failed: ${errorMessage}`);
+    }
+  }
+}

package/src/tools/hcs2/DeleteEntryTool.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { BaseHCS2QueryTool } from './base-hcs2-tools';
+import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+
+/**
+ * Schema for deleting an entry from HCS-2
+ */
+const deleteEntrySchema = z.object({
+  registryTopicId: z
+    .string()
+    .regex(/^\d+\.\d+\.\d+$/)
+    .describe('The HCS-2 registry topic ID (must be indexed)'),
+  uid: z
+    .string()
+    .describe('The unique ID of the entry to delete'),
+  memo: z
+    .string()
+    .max(500)
+    .optional()
+    .describe('Optional memo (max 500 characters)'),
+});
+
+
+/**
+ * Tool for deleting entries from HCS-2 registries
+ */
+export class DeleteEntryTool extends BaseHCS2QueryTool<typeof deleteEntrySchema> {
+  name = 'deleteHCS2Entry';
+  description = 'Delete an entry from an indexed HCS-2 registry';
+
+  get specificInputSchema() {
+    return deleteEntrySchema;
+  }
+
+  protected async executeQuery(
+    params: z.infer<typeof deleteEntrySchema>,
+    _runManager?: CallbackManagerForToolRun
+  ): Promise<unknown> {
+    try {
+      const result = await this.hcs2Builder.deleteEntry(
+        params.registryTopicId,
+        {
+          uid: params.uid,
+          memo: params.memo,
+        }
+      );
+
+      if (!result.success) {
+        throw new Error(result.error || 'Failed to delete entry');
+      }
+
+      return `Successfully deleted entry from HCS-2 registry!\n\nRegistry Topic: ${params.registryTopicId}\nUID: ${params.uid}${params.memo ? `\nMemo: ${params.memo}` : ''}\n\nThe entry has been removed from the registry.`;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Failed to delete entry';
+      throw new Error(`Entry deletion failed: ${errorMessage}`);
+    }
+  }
+}

package/src/tools/hcs2/MigrateRegistryTool.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import { BaseHCS2QueryTool } from './base-hcs2-tools';
+import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+
+/**
+ * Schema for migrating an HCS-2 registry
+ */
+const migrateRegistrySchema = z.object({
+  registryTopicId: z
+    .string()
+    .regex(/^\d+\.\d+\.\d+$/)
+    .describe('The current HCS-2 registry topic ID'),
+  targetTopicId: z
+    .string()
+    .regex(/^\d+\.\d+\.\d+$/)
+    .describe('The new topic ID to migrate to'),
+  metadata: z
+    .string()
+    .optional()
+    .describe('Optional metadata URI for migration details'),
+  memo: z
+    .string()
+    .max(500)
+    .optional()
+    .describe('Optional memo (max 500 characters)'),
+});
+
+
+/**
+ * Tool for migrating HCS-2 registries
+ */
+export class MigrateRegistryTool extends BaseHCS2QueryTool<typeof migrateRegistrySchema> {
+  name = 'migrateHCS2Registry';
+  description = 'Migrate an HCS-2 registry to a new topic';
+
+  get specificInputSchema() {
+    return migrateRegistrySchema;
+  }
+
+  protected async executeQuery(
+    params: z.infer<typeof migrateRegistrySchema>,
+    _runManager?: CallbackManagerForToolRun
+  ): Promise<unknown> {
+    try {
+      const result = await this.hcs2Builder.migrateRegistry(
+        params.registryTopicId,
+        {
+          targetTopicId: params.targetTopicId,
+          metadata: params.metadata,
+          memo: params.memo,
+        }
+      );
+
+      if (!result.success) {
+        throw new Error(result.error || 'Failed to migrate registry');
+      }
+
+      return `Successfully migrated HCS-2 registry!\n\nFrom Registry Topic: ${params.registryTopicId}\nTo Target Topic: ${params.targetTopicId}${params.metadata ? `\nMetadata: ${params.metadata}` : ''}${params.memo ? `\nMemo: ${params.memo}` : ''}\n\nThe registry has been migrated to the new topic.`;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Failed to migrate registry';
+      throw new Error(`Registry migration failed: ${errorMessage}`);
+    }
+  }
+}

package/src/tools/hcs2/QueryRegistryTool.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import { BaseHCS2QueryTool } from './base-hcs2-tools';
+import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+
+/**
+ * Schema for querying HCS-2 registry
+ */
+const queryRegistrySchema = z.object({
+  topicId: z
+    .string()
+    .regex(/^\d+\.\d+\.\d+$/)
+    .describe('The HCS-2 registry topic ID to query'),
+  limit: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe('Maximum number of entries to return'),
+  order: z
+    .enum(['asc', 'desc'])
+    .optional()
+    .describe('Order of results (ascending or descending)'),
+  skip: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe('Number of entries to skip'),
+});
+
+
+/**
+ * Tool for querying HCS-2 registries
+ */
+export class QueryRegistryTool extends BaseHCS2QueryTool<typeof queryRegistrySchema> {
+  name = 'queryHCS2Registry';
+  description = 'Query entries from an HCS-2 registry';
+
+  get specificInputSchema() {
+    return queryRegistrySchema;
+  }
+
+  protected async executeQuery(
+    params: z.infer<typeof queryRegistrySchema>,
+    _runManager?: CallbackManagerForToolRun
+  ): Promise<unknown> {
+    const registry = await this.hcs2Builder.getRegistry(params.topicId, {
+      limit: params.limit,
+      order: params.order,
+      skip: params.skip,
+    });
+
+    return {
+      topicId: registry.topicId,
+      registryType: registry.registryType === 0 ? 'indexed' : 'non-indexed',
+      ttl: registry.ttl,
+      totalEntries: registry.entries.length,
+      entries: registry.entries.map(entry => ({
+        sequence: entry.sequence,
+        timestamp: entry.timestamp,
+        payer: entry.payer,
+        operation: entry.message.op,
+        targetTopicId: entry.message.t_id,
+        uid: entry.message.uid,
+        metadata: entry.message.metadata,
+        memo: entry.message.m,
+      })),
+    };
+  }
+}

package/src/tools/hcs2/RegisterEntryTool.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { BaseHCS2QueryTool } from './base-hcs2-tools';
+import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+
+/**
+ * Schema for registering an entry in HCS-2
+ */
+const registerEntrySchema = z.object({
+  registryTopicId: z
+    .string()
+    .regex(/^\d+\.\d+\.\d+$/)
+    .describe('The HCS-2 registry topic ID (e.g., 0.0.123456)'),
+  targetTopicId: z
+    .string()
+    .regex(/^\d+\.\d+\.\d+$/)
+    .describe('The target topic ID to register (e.g., 0.0.123456)'),
+  metadata: z
+    .string()
+    .optional()
+    .describe('Optional metadata URI (HIP-412 format)'),
+  memo: z
+    .string()
+    .max(500)
+    .optional()
+    .describe('Optional memo (max 500 characters)'),
+});
+
+/**
+ * Tool for registering entries in HCS-2 registries
+ */
+export class RegisterEntryTool extends BaseHCS2QueryTool<typeof registerEntrySchema> {
+  name = 'registerHCS2Entry';
+  description = 'Register a new entry in an HCS-2 registry';
+
+  get specificInputSchema() {
+    return registerEntrySchema;
+  }
+
+  protected async executeQuery(
+    params: z.infer<typeof registerEntrySchema>,
+    _runManager?: CallbackManagerForToolRun
+  ): Promise<unknown> {
+    try {
+      const result = await this.hcs2Builder.registerEntry(
+        params.registryTopicId,
+        {
+          targetTopicId: params.targetTopicId,
+          metadata: params.metadata,
+          memo: params.memo,
+        }
+      );
+
+      if (!result.success) {
+        throw new Error(result.error || 'Failed to register entry');
+      }
+
+      return `Successfully registered entry in HCS-2 registry!\n\nRegistry Topic: ${params.registryTopicId}\nTarget Topic ID: ${params.targetTopicId}${params.metadata ? `\nMetadata: ${params.metadata}` : ''}${params.memo ? `\nMemo: ${params.memo}` : ''}\n\nThe entry has been added to the registry.`;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Failed to register entry';
+      throw new Error(`Entry registration failed: ${errorMessage}`);
+    }
+  }
+}