@hashgraphonline/conversational-agent 0.0.1 → 0.1.0

package/README.md

@@ -1,11 +1,13 @@
 # Hashgraph Online Conversational Agent
 
 | ![](./Hashgraph-Online.png) | A conversational AI agent that implements Hashgraph Consensus Standards (HCS) for agent communication, registry management, and content inscription on the Hedera network.<br><br>This package is built and maintained by [Hashgraph Online](https://hashgraphonline.com), a consortium of leading Hashgraph organizations within the Hedera ecosystem.<br><br>[📚 Conversational Agent Documentation](https://hashgraphonline.com/docs/libraries/conversational-agent/)<br>[📖 HCS Standards Documentation](https://hcs-improvement-proposals.pages.dev/docs/standards) |
-| :-------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+
+![Conversational Agent CLI](./conversational-agent.png)
 
 ## Overview
 
-The Hashgraph Online Conversational Agent provides a comprehensive AI agent implementation that supports:
+The Hashgraph Online Conversational Agent provides a comprehensive AI agent implementation that supports all tools from the `hedera-agent-kit` v2 package and the following HCS standards:
 
 - **HCS-10**: AI Agent Communication standard for trustless peer-to-peer messaging
 - **HCS-2**: Registry management for decentralized data storage
@@ -37,7 +39,7 @@ const agent = new ConversationalAgent({
   network: 'testnet',
   openAIApiKey: process.env.OPENAI_API_KEY!,
   openAIModelName: 'gpt-4o',
-  verbose: true
+  verbose: true,
 });
 
 // Initialize (automatically detects key type)
@@ -48,9 +50,85 @@ const response = await agent.processMessage(
   'Register me as an AI agent with the name TestBot, a random unique alias, and description "A test bot"'
 );
 
+// Transfer HBAR
+const transferResponse = await agent.processMessage(
+  'I want to transfer 1 HBAR to the account 0.0.800'
+);
+
 console.log(response.response);
+
+// Or use returnBytes mode for external signing
+const bytesAgent = new ConversationalAgent({
+  accountId: process.env.HEDERA_ACCOUNT_ID!,
+  privateKey: process.env.HEDERA_PRIVATE_KEY!,
+  network: 'testnet',
+  openAIApiKey: process.env.OPENAI_API_KEY!,
+  operationalMode: 'returnBytes',
+  userAccountId: '0.0.12345',
+});
+
+await bytesAgent.initialize();
+
+const bytesResponse = await bytesAgent.processMessage(
+  'Transfer 5 HBAR to 0.0.98765'
+);
+
+if (bytesResponse.transactionBytes) {
+  console.log('Transaction bytes:', bytesResponse.transactionBytes);
+}
 ```
 
+### Using returnBytes Mode
+
+The agent can be configured to return transaction bytes instead of executing them directly. This is useful when you want to review or sign transactions externally. Here's how to execute the transaction after getting the bytes:
+
+```typescript
+import { ConversationalAgent } from '@hashgraphonline/conversational-agent';
+import { Client, Transaction, PrivateKey } from '@hashgraph/sdk';
+
+const agent = new ConversationalAgent({
+  accountId: process.env.HEDERA_ACCOUNT_ID!,
+  privateKey: process.env.HEDERA_PRIVATE_KEY!,
+  network: 'testnet',
+  openAIApiKey: process.env.OPENAI_API_KEY!,
+  operationalMode: 'returnBytes', // Return transaction bytes instead of executing
+  userAccountId: '0.0.12345', // The account that will sign the transaction
+});
+
+await agent.initialize();
+
+// The agent will return transaction bytes for operations
+const response = await agent.processMessage('Transfer 5 HBAR to 0.0.98765');
+
+if (response.transactionBytes) {
+  // Decode the transaction bytes
+  const transaction = Transaction.fromBytes(
+    Buffer.from(response.transactionBytes, 'base64')
+  );
+
+  // Sign the transaction with your private key
+  const privateKey = PrivateKey.fromString(process.env.USER_PRIVATE_KEY!);
+  const signedTransaction = transaction.sign(privateKey);
+
+  // Submit to the Hedera network
+  const client = Client.forTestnet();
+  client.setOperator('0.0.12345', privateKey);
+
+  const txResponse = await signedTransaction.execute(client);
+  const receipt = await txResponse.getReceipt(client);
+
+  console.log('Transaction status:', receipt.status.toString());
+  console.log('Transaction ID:', txResponse.transactionId.toString());
+}
+```
+
+When using `returnBytes` mode:
+
+- The agent prepares transactions but doesn't execute them
+- Transaction bytes are returned as base64-encoded strings
+- You can decode, sign, and submit the transaction using the Hedera SDK
+- This mode is ideal for wallet integrations, multi-signature scenarios, and when you need transaction review before execution
+
 ## Features
 
 - **Automatic Key Detection**: Smart detection of ED25519 and ECDSA key types via mirror node
@@ -59,12 +137,14 @@ console.log(response.response);
 - **TypeScript Support**: Full type definitions for all components
 - **State Management**: Integrated state management for agent operations
 - **CLI Interface**: Beautiful terminal interface for interactive agent communication
+- **MCP Support**: Extend agent capabilities with Model Context Protocol servers
 
 ## Available Tools
 
-The Conversational Agent includes all tools from the `@hashgraphonline/hedera-agent-kit` package, providing comprehensive access to Hedera network functionality:
+The Conversational Agent includes all tools from the `hedera-agent-kit` v2 package, providing comprehensive access to Hedera network functionality:
 
 ### Core Hedera Tools (from hedera-agent-kit)
+
 - **Account Management**: Create accounts, transfer HBAR, manage allowances, get account info
 - **Token Service (HTS)**: Create tokens/NFTs, mint, burn, transfer, manage token properties
 - **Smart Contract Service**: Deploy contracts, execute functions, query contract state
@@ -73,6 +153,7 @@ The Conversational Agent includes all tools from the `@hashgraphonline/hedera-ag
 - **Network Queries**: Get network info, HBAR price, transaction details
 
 ### HCS-10 Agent Communication Tools
+
 - **RegisterAgentTool**: Register new agents with capabilities and tags
 - **FindRegistrationsTool**: Search for agents by account ID or tags
 - **RetrieveProfileTool**: Get detailed agent profiles
@@ -86,6 +167,7 @@ The Conversational Agent includes all tools from the `@hashgraphonline/hedera-ag
 - **CheckMessagesTool**: Retrieve messages from connections
 
 ### HCS-2 Registry Tools
+
 - **CreateRegistryTool**: Create new HCS-2 registry topics
 - **RegisterEntryTool**: Add entries to existing registries
 - **UpdateEntryTool**: Modify existing entries in registries
@@ -94,6 +176,7 @@ The Conversational Agent includes all tools from the `@hashgraphonline/hedera-ag
 - **QueryRegistryTool**: Retrieve entries from registries
 
 ### Inscription Tools
+
 - **InscribeFromUrlTool**: Inscribe content from URLs
 - **InscribeFromFileTool**: Inscribe content from local files
 - **InscribeFromBufferTool**: Inscribe content from memory buffers
@@ -181,7 +264,9 @@ const MyToolSchema = z.object({
   param2: z.number().optional().describe('Optional second parameter'),
 });
 
-export class MyCustomTool extends BaseHederaTransactionTool<typeof MyToolSchema> {
+export class MyCustomTool extends BaseHederaTransactionTool<
+  typeof MyToolSchema
+> {
   name = 'my-custom-tool';
   description = 'Performs a custom Hedera transaction';
   specificInputSchema = MyToolSchema;
@@ -216,13 +301,15 @@ const agent = new ConversationalAgent({
   network: 'testnet',
   openAIApiKey: process.env.OPENAI_API_KEY!,
   // Add your custom plugins
-  additionalPlugins: [new MyCustomPlugin()]
+  additionalPlugins: [new MyCustomPlugin()],
 });
 
 await agent.initialize();
 
 // Your custom tools are now available to the agent
-const response = await agent.processMessage('Use my custom tool with param1 "test"');
+const response = await agent.processMessage(
+  'Use my custom tool with param1 "test"'
+);
 ```
 
 ### Plugin Best Practices
@@ -237,24 +324,24 @@ For more details, see our [Plugin Development Guide](docs/PLUGIN_DEVELOPMENT.md)
 
 ## Configuration Options
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `accountId` | string | **required** | Hedera account ID (e.g., '0.0.12345') |
-| `privateKey` | string | **required** | Private key for the account |
-| `network` | NetworkType | 'testnet' | Network to connect to ('mainnet' or 'testnet') |
-| `openAIApiKey` | string | **required** | OpenAI API key for the LLM |
-| `openAIModelName` | string | 'gpt-4o' | OpenAI model to use |
-| `verbose` | boolean | false | Enable verbose logging |
-| `operationalMode` | AgentOperationalMode | 'autonomous' | 'autonomous' or 'returnBytes' |
-| `userAccountId` | string | undefined | User's account ID for transaction context |
-| `customSystemMessagePreamble` | string | instructions | Custom system message prefix |
-| `customSystemMessagePostamble` | string | undefined | Custom system message suffix |
-| `additionalPlugins` | BasePlugin[] | [] | Additional plugins to load |
-| `stateManager` | IStateManager | OpenConvaiState | Custom state manager |
-| `scheduleUserTransactionsInBytesMode` | boolean | false | Schedule transactions in bytes mode |
-| `mirrorNodeConfig` | MirrorNodeConfig | undefined | Custom mirror node configuration |
-| `disableLogging` | boolean | false | Disable all logging |
-| `enabledPlugins` | string[] | undefined | Filter which plugins to enable by ID |
+| Option                                | Type                 | Default         | Description                                    |
+| ------------------------------------- | -------------------- | --------------- | ---------------------------------------------- |
+| `accountId`                           | string               | **required**    | Hedera account ID (e.g., '0.0.12345')          |
+| `privateKey`                          | string               | **required**    | Private key for the account                    |
+| `network`                             | NetworkType          | 'testnet'       | Network to connect to ('mainnet' or 'testnet') |
+| `openAIApiKey`                        | string               | **required**    | OpenAI API key for the LLM                     |
+| `openAIModelName`                     | string               | 'gpt-4o'        | OpenAI model to use                            |
+| `verbose`                             | boolean              | false           | Enable verbose logging                         |
+| `operationalMode`                     | AgentOperationalMode | 'autonomous'    | 'autonomous' or 'returnBytes'                  |
+| `userAccountId`                       | string               | undefined       | User's account ID for transaction context      |
+| `customSystemMessagePreamble`         | string               | instructions    | Custom system message prefix                   |
+| `customSystemMessagePostamble`        | string               | undefined       | Custom system message suffix                   |
+| `additionalPlugins`                   | BasePlugin[]         | []              | Additional plugins to load                     |
+| `stateManager`                        | IStateManager        | OpenConvaiState | Custom state manager                           |
+| `scheduleUserTransactionsInBytesMode` | boolean              | false           | Schedule transactions in bytes mode            |
+| `mirrorNodeConfig`                    | MirrorNodeConfig     | undefined       | Custom mirror node configuration               |
+| `disableLogging`                      | boolean              | false           | Disable all logging                            |
+| `enabledPlugins`                      | string[]             | undefined       | Filter which plugins to enable by ID           |
 
 ## Environment Variables
 
@@ -273,7 +360,9 @@ HEDERA_NETWORK=testnet  # defaults to testnet
 ### Direct Plugin Access
 
 ```typescript
-const agent = new ConversationalAgent({ /* config */ });
+const agent = new ConversationalAgent({
+  /* config */
+});
 await agent.initialize();
 
 // Access plugins directly
@@ -298,7 +387,7 @@ const customStateManager = new OpenConvaiState();
 
 const agent = new ConversationalAgent({
   // ... other config
-  stateManager: customStateManager
+  stateManager: customStateManager,
 });
 ```
 
@@ -312,7 +401,7 @@ const htsAgent = ConversationalAgent.withHTS({
   accountId: process.env.HEDERA_ACCOUNT_ID!,
   privateKey: process.env.HEDERA_PRIVATE_KEY!,
   network: 'testnet',
-  openAIApiKey: process.env.OPENAI_API_KEY!
+  openAIApiKey: process.env.OPENAI_API_KEY!,
 });
 
 // Create agent with only HCS-2 registry tools
@@ -320,7 +409,7 @@ const hcs2Agent = ConversationalAgent.withHCS2({
   accountId: process.env.HEDERA_ACCOUNT_ID!,
   privateKey: process.env.HEDERA_PRIVATE_KEY!,
   network: 'testnet',
-  openAIApiKey: process.env.OPENAI_API_KEY!
+  openAIApiKey: process.env.OPENAI_API_KEY!,
 });
 
 // Other presets available:
@@ -345,11 +434,12 @@ const agent = new ConversationalAgent({
   network: 'testnet',
   openAIApiKey: process.env.OPENAI_API_KEY!,
   // Only enable specific plugins by their ID
-  enabledPlugins: ['hcs-10', 'hts-token', 'account']
+  enabledPlugins: ['hcs-10', 'hts-token', 'account'],
 });
 ```
 
 Available plugin IDs:
+
 - Standard plugins: `hcs-10`, `hcs-2`, `inscribe`
 - Core Hedera plugins: `hts-token`, `account`, `file-service`, `consensus-service`, `smart-contract`, `network`
 
@@ -359,19 +449,19 @@ If you need to use this with hedera-agent-kit 2.0.3:
 
 ```typescript
 import { HederaConversationalAgent, ServerSigner } from 'hedera-agent-kit';
-import { HCS10Plugin, HCS2Plugin, InscribePlugin } from '@hashgraphonline/conversational-agent';
+import {
+  HCS10Plugin,
+  HCS2Plugin,
+  InscribePlugin,
+} from '@hashgraphonline/conversational-agent';
 
 const signer = new ServerSigner(accountId, privateKey, network);
 
 const agent = new HederaConversationalAgent(signer, {
   pluginConfig: {
-    plugins: [
-      new HCS10Plugin(),
-      new HCS2Plugin(),
-      new InscribePlugin()
-    ]
+    plugins: [new HCS10Plugin(), new HCS2Plugin(), new InscribePlugin()],
   },
-  openAIApiKey: process.env.OPENAI_API_KEY!
+  openAIApiKey: process.env.OPENAI_API_KEY!,
 });
 ```
 
@@ -380,8 +470,86 @@ const agent = new HederaConversationalAgent(signer, {
 - [Conversational Agent Documentation](https://hashgraphonline.com/docs/libraries/conversational-agent/)
 - [Standards Agent Kit Documentation](https://hashgraphonline.com/docs/libraries/standards-agent-kit/)
 - [HCS Standards Documentation](https://hcs-improvement-proposals.pages.dev/docs/standards)
+- [MCP Integration Guide](./docs/MCP_INTEGRATION.md)
 - [GitHub Repository](https://github.com/hashgraph-online/conversational-agent)
 
+## Contributing
+
+We welcome contributions from the community! Whether you're fixing bugs, adding features, or creating new plugins, your contributions help make the Conversational Agent better for everyone.
+
+### Contributing a Plugin
+
+If you've created a plugin that extends the Conversational Agent's capabilities, we'd love to include it in the repository. Here's how:
+
+1. **Fork the Repository**
+   ```bash
+   git clone https://github.com/hashgraph-online/conversational-agent.git
+   cd conversational-agent
+   pnpm install
+   ```
+
+2. **Create Your Plugin**
+   - Place your plugin in `src/plugins/community/[your-plugin-name]/`
+   - Follow the plugin structure outlined in the [Plugin Development Guide](docs/PLUGIN_DEVELOPMENT.md)
+   - Include comprehensive tests in `src/plugins/community/[your-plugin-name]/__tests__/`
+   - Add documentation in `src/plugins/community/[your-plugin-name]/README.md`
+
+3. **Plugin Requirements**
+   - Must extend `BasePlugin` from hedera-agent-kit
+   - Include clear tool descriptions for AI understanding
+   - Add proper error handling and validation
+   - Follow TypeScript best practices
+   - Include unit tests with >80% coverage
+   - Document all configuration options
+   - Add usage examples
+
+4. **Submit a Pull Request**
+   - Create a feature branch: `git checkout -b feature/add-[plugin-name]-plugin`
+   - Commit your changes with clear messages
+   - Push to your fork and create a PR
+   - Include a description of what your plugin does and why it's useful
+   - Link to any relevant HCS standards or documentation
+
+### Plugin Review Process
+
+1. **Code Review**: Maintainers will review your code for quality, security, and adherence to standards
+2. **Testing**: All tests must pass, and the plugin must work with the latest agent version
+3. **Documentation**: Clear documentation and examples are required
+4. **Integration**: Once approved, your plugin will be added to the community plugins directory
+
+### Example Plugin Structure
+
+```
+src/plugins/community/your-plugin/
+├── index.ts              # Main plugin export
+├── YourPlugin.ts         # Plugin implementation
+├── tools/               # Tool implementations
+│   ├── YourTool1.ts
+│   └── YourTool2.ts
+├── __tests__/           # Test files
+│   ├── YourPlugin.test.ts
+│   └── tools/
+│       ├── YourTool1.test.ts
+│       └── YourTool2.test.ts
+├── README.md            # Plugin documentation
+└── package.json         # Plugin metadata (optional)
+```
+
+### General Contribution Guidelines
+
+- **Code Style**: Follow the existing code style and linting rules
+- **Commits**: Use clear, descriptive commit messages
+- **Documentation**: Update relevant documentation for any changes
+- **Tests**: Add tests for new functionality
+- **Issues**: Open an issue before working on major changes
+
+### Getting Help
+
+- Join our [Discord community](https://discord.gg/hashgraphonline) for discussions
+- Check existing issues and PRs before starting work
+- Ask questions in the #development channel
+- Review the [HCS Standards](https://hcs-improvement-proposals.pages.dev/docs/standards) for protocol details
+
 ## License
 
-Apache-2.0
+Apache-2.0

package/dist/cjs/agent-factory.d.ts

@@ -0,0 +1,5 @@
+import { BaseAgent, HederaAgentConfiguration } from './base-agent';
+
+export declare function createAgent(config: HederaAgentConfiguration & {
+    framework?: 'langchain' | 'vercel' | 'baml';
+}): BaseAgent;

package/dist/cjs/base-agent.d.ts

@@ -0,0 +1,95 @@
+import { BaseMessage } from '@langchain/core/messages';
+import { StructuredTool } from '@langchain/core/tools';
+import { TransactionReceipt } from '@hashgraph/sdk';
+import { HederaAgentKit, ServerSigner, TokenUsageCallbackHandler, TokenUsage, BasePlugin, CostCalculation } from 'hedera-agent-kit';
+import { AIProvider, VercelAIProvider, BAMLProvider } from './providers';
+import { Logger } from '@hashgraphonline/standards-sdk';
+import { MCPServerConfig } from './mcp/types';
+
+export interface ToolFilterConfig {
+    namespaceWhitelist?: string[];
+    toolBlacklist?: string[];
+    toolPredicate?: (tool: StructuredTool) => boolean;
+}
+export type ExecutionMode = 'direct' | 'bytes';
+export type OperationalMode = 'autonomous' | 'returnBytes';
+export interface HederaAgentConfiguration {
+    signer: ServerSigner;
+    execution?: {
+        mode?: ExecutionMode;
+        operationalMode?: OperationalMode;
+        userAccountId?: string;
+        scheduleUserTransactions?: boolean;
+        scheduleUserTransactionsInBytesMode?: boolean;
+    };
+    ai?: {
+        provider?: AIProvider;
+        llm?: unknown;
+        apiKey?: string;
+        modelName?: string;
+        temperature?: number;
+    };
+    filtering?: ToolFilterConfig;
+    messaging?: {
+        systemPreamble?: string;
+        systemPostamble?: string;
+        conciseMode?: boolean;
+    };
+    extensions?: {
+        plugins?: BasePlugin[];
+        mirrorConfig?: Record<string, unknown>;
+        modelCapability?: string;
+    };
+    mcp?: {
+        servers?: MCPServerConfig[];
+        autoConnect?: boolean;
+    };
+    debug?: {
+        verbose?: boolean;
+        silent?: boolean;
+    };
+}
+export interface ConversationContext {
+    messages: BaseMessage[];
+    metadata?: Record<string, unknown>;
+}
+export interface ChatResponse {
+    output: string;
+    message?: string;
+    transactionBytes?: string;
+    receipt?: TransactionReceipt | object;
+    scheduleId?: string;
+    transactionId?: string;
+    notes?: string[];
+    error?: string;
+    intermediateSteps?: unknown;
+    rawToolOutput?: unknown;
+    tokenUsage?: TokenUsage;
+    cost?: CostCalculation;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface UsageStats extends TokenUsage {
+    cost: CostCalculation;
+}
+export declare abstract class BaseAgent {
+    protected config: HederaAgentConfiguration;
+    protected logger: Logger;
+    protected agentKit: HederaAgentKit | undefined;
+    protected tools: StructuredTool[];
+    protected initialized: boolean;
+    protected tokenTracker: TokenUsageCallbackHandler | undefined;
+    constructor(config: HederaAgentConfiguration);
+    abstract boot(): Promise<void>;
+    abstract chat(message: string, context?: ConversationContext): Promise<ChatResponse>;
+    abstract shutdown(): Promise<void>;
+    abstract switchMode(mode: OperationalMode): void;
+    abstract getUsageStats(): UsageStats;
+    abstract getUsageLog(): UsageStats[];
+    abstract clearUsageStats(): void;
+    getCore(): HederaAgentKit | undefined;
+    protected filterTools(tools: StructuredTool[]): StructuredTool[];
+    protected buildSystemPrompt(): string;
+    isReady(): boolean;
+}
+export type { AIProvider, VercelAIProvider, BAMLProvider };

package/dist/cjs/config/system-message.d.ts

@@ -1 +1 @@
-export declare const SYSTEM_MESSAGE: string;
+export declare const getSystemMessage: (accountId: string) => string;

package/dist/cjs/conversational-agent.d.ts

@@ -1,9 +1,13 @@
-import { HederaConversationalAgent, BasePlugin, AgentOperationalMode, AgentResponse, MirrorNodeConfig } from 'hedera-agent-kit';
+import { BasePlugin, AgentOperationalMode, MirrorNodeConfig } from 'hedera-agent-kit';
+import { NetworkType } from '@hashgraphonline/standards-sdk';
+import { createAgent } from './agent-factory';
+import { ChatResponse } from './base-agent';
 import { HCS10Plugin } from './plugins/hcs-10/HCS10Plugin';
 import { HCS2Plugin } from './plugins/hcs-2/HCS2Plugin';
 import { InscribePlugin } from './plugins/inscribe/InscribePlugin';
+import { HbarTransferPlugin } from './plugins/hbar-transfer/HbarTransferPlugin';
 import { IStateManager } from '@hashgraphonline/standards-agent-kit';
-import { NetworkType } from '@hashgraphonline/standards-sdk';
+import { MCPServerConfig } from './mcp/types';
 
 export interface ConversationalAgentOptions {
     accountId: string;
@@ -22,6 +26,11 @@ export interface ConversationalAgentOptions {
     mirrorNodeConfig?: MirrorNodeConfig;
     disableLogging?: boolean;
     enabledPlugins?: string[];
+    toolFilter?: (tool: {
+        name: string;
+        namespace?: string;
+    }) => boolean;
+    mcpServers?: MCPServerConfig[];
 }
 /**
  * The ConversationalAgent class is an optional wrapper around the HederaConversationalAgent class,
@@ -33,22 +42,58 @@ export interface ConversationalAgentOptions {
  * @returns A new instance of the ConversationalAgent class.
  */
 export declare class ConversationalAgent {
-    conversationalAgent?: HederaConversationalAgent;
+    private agent?;
     hcs10Plugin: HCS10Plugin;
     hcs2Plugin: HCS2Plugin;
     inscribePlugin: InscribePlugin;
+    hbarTransferPlugin: HbarTransferPlugin;
     stateManager: IStateManager;
     private options;
     private logger;
     constructor(options: ConversationalAgentOptions);
+    /**
+     * Initialize the conversational agent with Hedera network connection and AI configuration
+     * @throws {Error} If account ID or private key is missing
+     * @throws {Error} If initialization fails
+     */
     initialize(): Promise<void>;
+    /**
+     * Get the HCS-10 plugin instance
+     * @returns {HCS10Plugin} The HCS-10 plugin instance
+     */
     getPlugin(): HCS10Plugin;
+    /**
+     * Get the state manager instance
+     * @returns {IStateManager} The state manager instance
+     */
     getStateManager(): IStateManager;
-    getConversationalAgent(): HederaConversationalAgent;
+    /**
+     * Get the underlying agent instance
+     * @returns {ReturnType<typeof createAgent>} The agent instance
+     * @throws {Error} If agent is not initialized
+     */
+    getAgent(): ReturnType<typeof createAgent>;
+    /**
+     * Get the conversational agent instance (alias for getAgent)
+     * @returns {ReturnType<typeof createAgent>} The agent instance
+     * @throws {Error} If agent is not initialized
+     */
+    getConversationalAgent(): ReturnType<typeof createAgent>;
+    /**
+     * Process a message through the conversational agent
+     * @param {string} message - The message to process
+     * @param {Array<{type: 'human' | 'ai'; content: string}>} chatHistory - Previous chat history
+     * @returns {Promise<ChatResponse>} The agent's response
+     * @throws {Error} If agent is not initialized
+     */
     processMessage(message: string, chatHistory?: {
         type: 'human' | 'ai';
         content: string;
-    }[]): Promise<AgentResponse>;
+    }[]): Promise<ChatResponse>;
+    /**
+     * Create a ConversationalAgent with specific plugins enabled
+     */
+    private static withPlugins;
     /**
      * Create a ConversationalAgent with only HTS (Hedera Token Service) tools enabled
      */
@@ -89,4 +134,16 @@ export declare class ConversationalAgent {
      * Create a ConversationalAgent with minimal Hedera tools (no HCS standards)
      */
     static minimal(options: ConversationalAgentOptions): ConversationalAgent;
+    /**
+     * Create a ConversationalAgent with MCP servers configured
+     */
+    static withMCP(options: ConversationalAgentOptions, mcpServers: MCPServerConfig[]): ConversationalAgent;
+    /**
+     * Detect the private key type by querying the account info from mirror node
+     * @param {string} accountId - The Hedera account ID
+     * @param {string} privateKey - The private key string
+     * @param {NetworkType} network - The Hedera network
+     * @returns {Promise<PrivateKey>} The appropriate PrivateKey instance
+     */
+    private detectPrivateKeyType;
 }