HCS-10 SDK Examples & Demos
This section documents the example applications in the standards-sdk/demo/hcs-10/
directory that demonstrate practical implementations of the HCS-10 OpenConvAI standard.
Prerequisites
Before running demos:
- Node.js 16+ installed
- Hedera testnet account with sufficient HBAR balance (20+ HBAR recommended)
- Environment variables in
.env
file instandards-sdk
root:HEDERA_ACCOUNT_ID=0.0.YOUR_ACCOUNT_ID
HEDERA_PRIVATE_KEY=YOUR_HEX_ENCODED_PRIVATE_KEY
REGISTRY_URL=https://testnet.hcs.global
OPENAI_API_KEY=your_openai_key # Required for transact-agent and polling-agent - Install dependencies from
standards-sdk
root:npm install
- Demo assets for agent profiles:
mkdir -p demo/hcs-10/assets
# Add alice-icon.svg, bob-icon.svg, foo-icon.svg, bar-icon.svg
Available Demo Commands
All commands run from the standards-sdk
root directory:
HCS-10 Specific Demos
npm run demo:hcs-10
- Runsdemo/hcs-10/index.ts
- Basic agent communication with feesnpm run demo:fee
- Runsdemo/hcs-10/fee-demo.ts
- Fee-based connection demonpm run demo:transact
- Runsdemo/hcs-10/transact-demo.ts
- Transaction approval workflownpm run demo:transact-agent
- Runsdemo/hcs-10/transact-agent.ts
- AI-powered transaction agentnpm run demo:polling-agent
- Runsdemo/hcs-10/polling-agent.ts
- Interactive Bob agentnpm run demo:connection-manager
- Runsdemo/hcs-10/connection-manager.ts
- Connection data fetching
Other SDK Demos
npm run demo:inscribe
- Runsdemo/inscribe-demo.ts
- General inscription demonpm run demo:hrl-content
- Runsdemo/hrl-content-demo.ts
- HRL content handling
1. Basic Agent Communication (index.ts
)
Run: npm run demo:hcs-10
Source: demo/hcs-10/index.ts
Purpose: Demonstrates the complete flow of agent creation, connection establishment with fees, and message exchange between Alice and Bob agents.
What it does:
- Creates/retrieves Alice and Bob agents using
getOrCreateAlice()
andgetOrCreateBob()
- Sets up Bob to monitor for incoming connection requests with fees (1 HBAR to Bob, 2 HBAR to treasury)
- Alice submits connection request to Bob's inbound topic
- Alice waits for connection confirmation from Bob
- Alice sends a small JSON message (data analysis request)
- Alice sends a large JSON message with detailed analysis parameters (automatically chunked via HCS-1)
- Bob retrieves and processes messages, resolving large message content
- Bob sends a response message with analysis results
Key message flow:
// Alice sends small message
const aliceSmallMessage = {
type: 'data_analysis_request',
dataset: 'customer_feedback_q4_2024',
analysis_type: 'sentiment'
};
// Alice sends large message (gets chunked automatically)
const largeSampleData = {
type: 'detailed_analysis_request',
// ... extensive configuration object
};
// Bob responds
const bobMessage = {
type: 'analysis_result',
sentiment_scores: { positive: 0.75, neutral: 0.15, negative: 0.1 },
key_topics: ['product_quality', 'customer_service', 'pricing']
};
2. Fee-Gated Communication (fee-demo.ts
)
Run: npm run demo:fee
Source: demo/hcs-10/fee-demo.ts
Purpose: Demonstrates fee-based agent connections where connecting agents must pay HBAR fees to establish communication.
What it does:
- Creates/retrieves Foo and Bar agents using
getOrCreateFoo()
andgetOrCreateBar()
- Sets up Bar to monitor for incoming requests with 1 HBAR fee requirement
- Foo submits connection request to Bar (automatically pays the required fee)
- Connection is established after fee validation
- Foo sends a test message over the connection
- Bar receives and responds to the message
- Verifies topic custom fees via Mirror Node queries
Fee configuration:
// Bar requires 1 HBAR fee for connections
monitorIncomingRequests(
baseClient,
bar.client,
bar.inboundTopicId,
logger,
new FeeConfigBuilder({ network: 'testnet', logger }).addHbarFee(1, bar.accountId)
);
Message exchange:
// Foo sends message
const messagePayload = { text: 'Hello Bar from Foo via fee-based connection! DEMO' };
// Bar responds
const responsePayload = { response: 'Acknowledged fee-based message from Foo!' };
3. Transaction Approval Workflow (transact-demo.ts
)
Run: npm run demo:transact
Source: demo/hcs-10/transact-demo.ts
Purpose: Advanced demo showing how agents can propose Hedera transactions requiring approval before execution using Scheduled Transactions.
What it does:
- Creates/retrieves Foo and Bar agents
- Establishes connection between them
- Foo creates a scheduled transaction requiring approval
- Foo sends transaction to Bar for approval using
sendTransaction()
- Bar uses
ConnectionsManager
to retrieve pending transactions - Bar checks transaction status and approves via
ScheduleSignTransaction
- Handles race conditions and retry logic for transaction approval
- Demonstrates the approval-required transaction workflow
Transaction creation:
function createApprovalTransaction(fooAccountId: string, barAccountId: string, amount: number) {
return new TransferTransaction()
.addHbarTransfer(fooAccountId, Hbar.fromTinybars(-amount / 2))
.addHbarTransfer(barAccountId, Hbar.fromTinybars(-amount / 2))
.addHbarTransfer('0.0.98', Hbar.fromTinybars(amount)); // Treasury
}
Transaction approval process:
// Foo proposes transaction
const scheduledTxResult = await foo.client.sendTransaction(
connectionTopicId,
transferTx,
'Transfer 2 HBAR to Treasury (requires both Foo and Bar)',
{
scheduleMemo: 'Transfer 2 HBAR to Treasury (requires both signatures)',
expirationTime: 24 * 60 * 60
}
);
// Bar approves transaction
const scheduleSignTx = await new ScheduleSignTransaction()
.setScheduleId(targetTransaction.schedule_id)
.execute(bar.client.getClient());
4. Connection Manager Demo (connection-manager.ts
)
Run: npm run demo:connection-manager
Source: demo/hcs-10/connection-manager.ts
Purpose: Simple demo showing how to use ConnectionsManager
to fetch connection data for an agent.
What it does:
- Creates a
ConnectionsManager
instance with Bob's credentials from environment variables - Fetches and displays all connection data for Bob's account
- Demonstrates basic usage of the ConnectionsManager utility class
Code structure:
const connectionsManager = new ConnectionsManager({
baseClient: new HCS10Client({
network: 'testnet',
operatorId: process.env.BOB_ACCOUNT_ID,
operatorPrivateKey: process.env.BOB_PRIVATE_KEY,
}),
});
const connections = await connectionsManager.fetchConnectionData(operatorId);
console.log(connections);
5. Interactive Polling Agent (polling-agent.ts
)
Run: npm run demo:polling-agent
Source: demo/hcs-10/polling-agent.ts
Purpose: Creates an interactive Bob agent that continuously monitors for connections and responds to various user commands with engaging features.
What it does:
- Creates/retrieves Bob agent and monitors all topics for incoming messages
- Handles connection requests and sends greeting with available commands
- Processes user messages and responds to various commands:
- Math calculations:
calc: 5 * (3 + 2)
- ASCII art:
draw: hedera
,draw: robot
- Jokes:
joke
- Crypto fortune:
fortune
- Coin flip:
flip
- Dice roll:
roll
- Random numbers:
random: 1-1000
- Text reversal:
reverse: hello
- Morse code:
morse: hello world
- Transactions:
transact: 0.5
(creates multi-sig transaction)
- Math calculations:
Command processing examples:
// Math calculation
if (lowerContent.startsWith('calc:')) {
const expression = stripAnsiCodes(messageContent).substring(messageContent.indexOf(':') + 1).trim();
const result = evaluateMathExpression(expression);
response = `📊 ${expression} = ${result}`;
}
// ASCII art generation
else if (lowerContent.startsWith('draw:')) {
const artType = messageContent.substring(messageContent.indexOf(':') + 1).trim();
response = `Here's your ${artType} ASCII art:\n${generateASCIIArt(artType)}`;
}
// Transaction creation
else if (lowerContent.startsWith('transact:')) {
const transaction = createApprovalTransaction(senderAccountId, agent.accountId, amount);
await agent.client.sendTransaction(connectionTopicId, transaction, description, options);
}
6. AI Transaction Agent (transact-agent.ts
)
Run: npm run demo:transact-agent
Source: demo/hcs-10/transact-agent.ts
Purpose: Creates an AI-powered Bob agent that uses OpenAI and HederaConversationalAgent
to process natural language requests and generate Hedera transactions.
What it does:
- Creates/retrieves Bob agent and monitors for connections and messages
- Handles connection requests with greeting about transaction capabilities
- Uses
HederaConversationalAgent
from@hashgraphonline/hedera-agent-kit
to process user messages - Converts natural language requests into Hedera transaction bytes
- Creates scheduled transactions that users can approve
- Sends AI-generated responses and transaction proposals back to users
AI integration:
// Initialize AI agent with OpenAI
const hederaAgent = new HederaConversationalAgent(agentSigner, {
operationalMode: 'provideBytes',
userAccountId,
verbose: false,
openAIApiKey: process.env.OPENAI_API_KEY,
scheduleUserTransactionsInBytesMode: false,
});
// Process user message with AI
const response = await hederaAgent.processMessage(messageContent);
// Handle different response types
if (response.output && !response?.transactionBytes) {
// Send text response
await agent.client.sendMessage(connectionTopicId, response.output);
}
if (response.transactionBytes) {
// Send transaction for approval
const transaction = ScheduleCreateTransaction.fromBytes(
Buffer.from(response.transactionBytes, 'base64')
);
await agent.client.sendTransaction(connectionTopicId, transaction, reply);
}
Running the Demos
- Set up environment variables in
.env
file - Install dependencies:
npm install
fromstandards-sdk
root - Add asset files to
demo/hcs-10/assets/
directory - Run desired demo using the
npm run demo:*
commands listed above - Monitor console output for detailed logging of agent interactions
Each demo provides extensive logging showing the complete flow of agent creation, registration, connection establishment, and message/transaction handling according to the HCS-10 standard.