Migration Guide v3 to v4

const realBytes = parseTransactionBytes(toolCall.parsedData.raw.bytes);
const realBytes = Buffer.isBuffer(bytesObject)
? bytesObject
: Buffer.from(bytesObject.data);
const tx = Transaction.fromBytes(realBytes);

npm install hedera-agent-kit @hashgraph/sdk @langchain/core langchain @langchain/langgraph @langchain/openai dotenv

npm install hedera-agent-kit @hashgraph/sdk ai @ai-sdk/openai dotenv

npm install hedera-agent-kit @hashgraph/sdk

npm install hedera-agent-kit @hashgraph/sdk

npm install hedera-agent-kit @hashgraph/sdk @langchain/core langchain @langchain/langgraph @langchain/openai dotenv

import { Client, PrivateKey } from '@hashgraph/sdk';
import { HederaLangchainToolkit, AgentMode } from 'hedera-agent-kit';
import { ChatOpenAI } from '@langchain/openai';
import { ChatPromptTemplate } from '@langchain/core/prompts';
import { AgentExecutor, createToolCallingAgent } from 'langchain/agents';

const client = Client.forTestnet().setOperator(
  process.env.ACCOUNT_ID,
  PrivateKey.fromStringECDSA(process.env.PRIVATE_KEY)
);

const toolkit = new HederaLangchainToolkit({
  client,
  configuration: {
    plugins: [],
    context: { mode: AgentMode.AUTONOMOUS },
  },
});

const tools = toolkit.getTools();

const llm = new ChatOpenAI({ model: 'gpt-4o-mini' });

const prompt = ChatPromptTemplate.fromMessages([
  ['system', 'You are a helpful assistant with access to Hedera blockchain tools'],
  ['human', '{input}'],
  ['placeholder', '{agent_scratchpad}'],
]);

const agent = createToolCallingAgent({ llm, tools, prompt });

const agentExecutor = new AgentExecutor({ agent, tools });

const response = await agentExecutor.invoke({
  input: "What's my HBAR balance?",
});

npm install hedera-agent-kit @hashgraph/sdk ai @ai-sdk/openai dotenv

import { Client, PrivateKey } from '@hashgraph/sdk';
import { HederaAIToolkit, AgentMode, coreTokenPlugin, coreAccountPlugin } from 'hedera-agent-kit';
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const client = Client.forTestnet().setOperator(
  process.env.ACCOUNT_ID,
  PrivateKey.fromStringECDSA(process.env.PRIVATE_KEY)
);

const toolkit = new HederaAIToolkit({
  client,
  configuration: {
    plugins: [coreTokenPlugin, coreAccountPlugin],
    context: { mode: AgentMode.AUTONOMOUS },
  },
});

const response = await generateText({
  model: openai('gpt-4o'),
  messages: [{ role: 'user', content: "What's my balance?" }],
  tools: toolkit.getTools(),
});

npm install hedera-agent-kit @hashgraph/sdk

import { HederaElizaOSToolkit } from 'hedera-agent-kit/elizaos';

const toolkit = new HederaElizaOSToolkit({
  client,
  configuration: {
    plugins: [],
    context: { mode: AgentMode.AUTONOMOUS },
  },
});

npm install hedera-agent-kit @hashgraph/sdk

import { HederaMCPToolkit, AgentMode } from 'hedera-agent-kit';

const server = new HederaMCPToolkit({
  client,
  configuration: {
    plugins: [],
    context: { mode: AgentMode.AUTONOMOUS },
  },
});

import { HederaMCPServer } from 'hedera-agent-kit';

import { z } from 'zod';
import type { Context } from '@/shared/configuration';
// ── The old approach returned a plain Tool object literal ──
import type { Tool } from '@/shared/tools';
import { Client, Status } from '@hashgraph/sdk';
import { handleTransaction, RawTransactionResponse } from '@/shared/strategies/tx-mode-strategy';
import HederaBuilder from '@/shared/hedera-utils/hedera-builder';
import { transferHbarParameters } from '@/shared/parameter-schemas/account.zod';
import HederaParameterNormaliser from '@/shared/hedera-utils/hedera-parameter-normaliser';
import { PromptGenerator } from '@/shared/utils/prompt-generator';
import { transactionToolOutputParser } from '@/shared/utils/default-tool-output-parsing';

// ── Tool description / prompt ──────────────────────────────────────────────
const transferHbarPrompt = (context: Context = {}) => {
  const contextSnippet = PromptGenerator.getContextSnippet(context);
  const sourceAccountDesc = PromptGenerator.getAccountParameterDescription(
    'sourceAccountId', context,
  );
  const usageInstructions = PromptGenerator.getParameterUsageInstructions();
  return `
${contextSnippet}
This tool will transfer HBAR to an account.
Parameters:
- transfers (array): List of transfers. Each: { accountId, amount }
- ${sourceAccountDesc}
- transactionMemo (string, optional)
${PromptGenerator.getScheduledTransactionParamsDescription(context)}
${usageInstructions}
`;
};

// ── Post-processing helper ─────────────────────────────────────────────────
const postProcess = (response: RawTransactionResponse) => {
  if (response.scheduleId) {
    return `Scheduled HBAR transfer created successfully.\nTransaction ID: ${response.transactionId}\nSchedule ID: ${response.scheduleId.toString()}`;
  }
  return `HBAR successfully transferred.\nTransaction ID: ${response.transactionId}`;
};

// ── Standalone execute function - ALL logic lives here ─────────────────────
// This monolithic function cannot be split into hookable lifecycle stages,
// so hooks and policies have no entry points.
const transferHbar = async (
  client: Client,
  context: Context,
  params: z.infer<ReturnType<typeof transferHbarParameters>>,
) => {
  try {
    const normalisedParams = await HederaParameterNormaliser.normaliseTransferHbar(
      params, context, client,
    );
    const tx = HederaBuilder.transferHbar(normalisedParams);
    return await handleTransaction(tx, client, context, postProcess);
  } catch (error) {
    const desc = 'Failed to transfer HBAR';
    const message = desc + (error instanceof Error ? `: ${error.message}` : '');
    console.error('[transfer_hbar_tool]', message);
    return { raw: { status: Status.InvalidTransaction, error: message }, humanMessage: message };
  }
};

export const TRANSFER_HBAR_TOOL = 'transfer_hbar_tool';

// ── Factory function returns a plain Tool object literal ───────────────────
// ✗ No hook/policy support - execute() is opaque to the framework
const tool = (context: Context): Tool => ({
  method: TRANSFER_HBAR_TOOL,
  name: 'Transfer HBAR',
  description: transferHbarPrompt(context),
  parameters: transferHbarParameters(context),
  execute: transferHbar,
  outputParser: transactionToolOutputParser,
});

export default tool;