@hashgraphonline/standards-agent-kit
Version:
A modular SDK for building on-chain autonomous agents using Hashgraph Online Standards, including HCS-10 for agent discovery and communication. https://hol.org
266 lines (265 loc) • 7.73 kB
TypeScript
import { BaseServiceBuilder, HederaAgentKit } from 'hedera-agent-kit';
import { PrivateKey, TransactionReceipt } from '@hashgraph/sdk';
import { IStateManager } from '../../state/state-types';
import { ExecuteResult } from '../types';
import { FeeConfigBuilderInterface, HCS10Client, ProfileResponse as SDKProfileResponse, HCSMessage, LogLevel, HandleConnectionRequestResponse } from '@hashgraphonline/standards-sdk';
/**
* Message response with timestamp
*/
export interface HCSMessageWithTimestamp extends Omit<HCSMessage, 'op'> {
timestamp: number;
data?: string;
sequence_number: number;
op?: HCSMessage['op'] | string;
operator_id?: string;
created?: Date;
m?: string;
}
/**
* Network type for HCS-10
*/
export type StandardNetworkType = 'mainnet' | 'testnet';
/**
* Parameters for agent registration
*/
export interface RegisterAgentParams {
name: string;
bio?: string;
alias?: string;
type?: 'autonomous' | 'manual';
model?: string;
capabilities?: number[];
creator?: string;
socials?: Record<string, string>;
properties?: Record<string, unknown>;
profilePicture?: string | {
url?: string;
path?: string;
filename?: string;
};
existingProfilePictureTopicId?: string;
initialBalance?: number;
userAccountId?: string;
hbarFee?: number;
tokenFees?: Array<{
amount: number;
tokenId: string;
}>;
exemptAccountIds?: string[];
}
/**
* Parameters for initiating a connection
*/
export interface InitiateConnectionParams {
targetAccountId: string;
disableMonitor?: boolean;
memo?: string;
}
/**
* Parameters for accepting a connection request
*/
export interface AcceptConnectionParams {
requestKey: string;
hbarFee?: number | undefined;
exemptAccountIds?: string[] | undefined;
}
/**
* Parameters for sending a message
*/
export interface SendMessageParams {
topicId: string;
message: string;
disableMonitoring?: boolean;
}
/**
* Parameters for sending a message to a connected account
*/
export interface SendMessageToConnectionParams {
targetIdentifier: string;
message: string;
disableMonitoring?: boolean;
}
/**
* HCS10Builder facilitates HCS-10 protocol operations for agent communication
* This builder incorporates all HCS10Client functionality directly
*/
export declare class HCS10Builder extends BaseServiceBuilder {
private standardClient;
private stateManager;
private executeResult?;
private network;
private sdkLogger;
constructor(hederaKit: HederaAgentKit, stateManager?: IStateManager, options?: {
useEncryption?: boolean;
registryUrl?: string;
logLevel?: LogLevel;
});
/**
* Get the operator account ID
*/
getOperatorId(): string;
/**
* Get the network type
*/
getNetwork(): StandardNetworkType;
/**
* Get state manager instance
*/
getStateManager(): IStateManager | undefined;
/**
* Get account and signer information
*/
getAccountAndSigner(): {
accountId: string;
signer: PrivateKey;
};
/**
* Get the inbound topic ID for the current operator
*/
getInboundTopicId(): Promise<string>;
/**
* Get agent profile
*/
getAgentProfile(accountId: string): Promise<SDKProfileResponse>;
/**
* Submit connection request
*/
submitConnectionRequest(inboundTopicId: string, memo: string): Promise<TransactionReceipt>;
/**
* Handle connection request
*/
handleConnectionRequest(inboundTopicId: string, requestingAccountId: string, connectionRequestId: number, feeConfig?: FeeConfigBuilderInterface): Promise<HandleConnectionRequestResponse>;
/**
* Send message to a topic
*/
sendMessage(topicId: string, data: string, memo?: string): Promise<{
sequenceNumber: number | undefined;
receipt: TransactionReceipt;
transactionId: string | undefined;
}>;
/**
* Get messages from a topic
*/
getMessages(topicId: string): Promise<{
messages: HCSMessageWithTimestamp[];
}>;
/**
* Get message stream from a topic
*/
getMessageStream(topicId: string): Promise<{
messages: HCSMessage[];
}>;
/**
* Get message content
*/
getMessageContent(inscriptionIdOrData: string): Promise<string>;
/**
* Get the standard client instance (for compatibility)
*/
getStandardClient(): HCS10Client;
/**
* Load profile picture from URL or file path
*/
private loadProfilePicture;
private pollForNewSequence;
/**
* Create and register an agent
*/
private createAndRegisterAgent;
/**
* Register a new HCS-10 agent
* Note: This performs multiple transactions and requires directExecution mode
*/
registerAgent(params: RegisterAgentParams): Promise<this>;
/**
* Initiate a connection to another agent
*/
initiateConnection(params: InitiateConnectionParams): Promise<this>;
/**
* Accept a connection request
* Note: This performs multiple transactions and requires directExecution mode
*/
acceptConnection(params: AcceptConnectionParams): Promise<this>;
/**
* Send a message using HCS (for operations that need direct topic access)
*/
sendHCS10Message(params: SendMessageParams): Promise<this>;
/**
* Send a message to a connected account with optional response monitoring
*/
sendMessageToConnection(params: SendMessageToConnectionParams): Promise<this>;
/**
* Monitor responses on a topic after sending a message
*/
private monitorResponses;
/**
* Start passive monitoring for incoming connection requests
* This method monitors continuously in the background
*/
startPassiveConnectionMonitoring(): Promise<this>;
/**
* Monitor for incoming connection requests
*/
monitorConnections(params: {
acceptAll?: boolean;
targetAccountId?: string;
monitorDurationSeconds?: number;
hbarFees?: Array<{
amount: number;
collectorAccount?: string;
}>;
tokenFees?: Array<{
amount: number;
tokenId: string;
collectorAccount?: string;
}>;
exemptAccountIds?: string[];
defaultCollectorAccount?: string;
}): Promise<this>;
/**
* Manage connection requests (list, view, or reject)
*/
manageConnectionRequests(params: {
action: 'list' | 'view' | 'reject';
requestKey?: string;
}): Promise<this>;
/**
* List unapproved connection requests
*/
listUnapprovedConnectionRequests(): Promise<this>;
/**
* List connections with enhanced details
*/
listConnections(params?: {
includeDetails?: boolean;
showPending?: boolean;
}): Promise<this>;
private formatConnection;
private getEnhancedConnections;
/**
* Check messages on a connection
*/
checkMessages(params: {
targetIdentifier: string;
fetchLatest?: boolean;
lastMessagesCount?: number;
}): Promise<this>;
/**
* Find registrations using the configured registry
*/
findRegistrations(params: {
accountId?: string;
tags?: number[];
}): Promise<this>;
/**
* Retrieve detailed profile information for an agent
*/
retrieveProfile(params: {
accountId: string;
disableCache?: boolean;
}): Promise<this>;
/**
* Override execute to return stored HCS10 operation results
*/
execute(): Promise<ExecuteResult>;
}