Skip to main content

Documentation Index

Fetch the complete documentation index at: https://icp-agent.com/llms.txt

Use this file to discover all available pages before exploring further.

The ICP Agent Kit provides 10 pre-built LangChain tools that enable natural language interaction with the Internet Computer blockchain. These tools are automatically available when you use natural language processing or specialized agents.

​
Tool Categories

Identity Tools

2 tools for identity management

Token Tools

3 tools for token operations

Canister Tools

3 tools for canister management

Cycles Tools

2 tools for cycles operations

​
Identity Tools

​
1. get_current_identity

Shows information about the current active identity. Usage: 
// Natural language
'Show me my current identity';
'What is my principal?';
'Display my account information';

// Direct tool usage
const tool = createGetCurrentIdentityTool(agent);
const result = await tool.invoke({}, { configurable: { agent } });
Output:
  • Current identity name
  • Principal ID
  • Account ID
  • Anonymous status

​
2. create_identity

Creates a new identity from a seed phrase or anonymous. Parameters:
  • type: “seed” | “anonymous”
  • name: Identity name/key
  • seedPhrase: (optional) 12 or 24 word mnemonic
Usage: 
// Natural language
'Create a new identity called trading';
'Generate anonymous identity for testing';
'Create identity from seed phrase: [words...]';

// Direct tool usage
const tool = createIdentityTool;
const result = await tool.invoke(
  {
    type: 'anonymous',
    name: 'test-identity',
  },
  { configurable: { agent } },
);

​
Token Tools

​
3. transfer_icp

Transfers ICP tokens to another account. Parameters:
  • to: Recipient account ID or principal
  • amount: Amount in ICP (not e8s)
  • memo: (optional) Transaction memo
Usage: 
// Natural language
'Transfer 5 ICP to alice.icp';
'Send 0.5 ICP to ryjl3-tyaaa-aaaaa-aaaba-cai with memo: payment';

// Direct tool usage
const result = await transferICPTool.invoke(
  {
    to: 'recipient-account-id',
    amount: '5.5',
    memo: 'Payment for services',
  },
  { configurable: { agent } },
);
Important:
  • Amount is specified in ICP (e.g., “1.5” = 1.5 ICP)
  • Automatically converts to e8s (smallest unit)
  • Validates recipient address format

​
4. get_balance

Checks ICP token balance for the current identity. Usage: 
// Natural language
'What is my ICP balance?';
'Check my balance';
'Show me how much ICP I have';

// Direct tool usage
const tool = createGetBalanceTool(agent);
const result = await tool.invoke({}, { configurable: { agent } });
Output:
  • Balance in ICP (formatted)
  • Balance in e8s (raw)
  • Account ID checked

​
5. icrc1_transfer

Transfers ICRC-1 standard tokens between accounts. Parameters:
  • canisterId: Token canister ID
  • to: Recipient principal
  • amount: Amount to transfer
  • memo: (optional) Transaction memo
Usage: 
// Natural language
'Transfer 1000 CHAT tokens to bob';
'Send 50 tokens from canister xyz to alice';

// Direct tool usage
const result = await icrc1TransferTool.invoke(
  {
    canisterId: 'token-canister-id',
    to: 'recipient-principal',
    amount: '1000',
    memo: 'Token payment',
  },
  { configurable: { agent } },
);

​
Canister Tools

​
6. create_canister

Creates a new canister with specified cycles. Parameters:
  • cycles: Amount of cycles (e.g., “5T” for 5 trillion)
Usage: 
// Natural language
'Create a new canister with 5 trillion cycles';
'Deploy new canister with 2T cycles';
'Make a canister with 10T cycles';

// Direct tool usage
const tool = createCreateCanisterTool(agent);
const result = await tool.invoke(
  {
    cycles: '5T',
  },
  { configurable: { agent } },
);
Output:
  • New canister ID
  • Cycles allocated
  • Controller information

​
7. deploy_wasm

Deploys WASM module to a canister. Parameters:
  • canisterId: Target canister ID
  • wasmPath: Path to WASM file
  • mode: “install” | “upgrade” | “reinstall”
Usage: 
// Natural language
'Deploy my app.wasm to canister xyz';
'Upgrade canister abc with new code';
'Install WASM module to my canister';

// Direct tool usage
const result = await deployWasmTool.invoke(
  {
    canisterId: 'canister-id',
    wasmPath: './build/app.wasm',
    mode: 'install',
  },
  { configurable: { agent } },
);

​
8. get_canister_status

Retrieves detailed status information about a canister. Parameters:
  • canisterId: Canister ID to check
Usage: 
// Natural language
'Check status of canister xyz';
'Show me canister abc information';
'Get details about my canister';

// Direct tool usage
const result = await getCanisterStatusTool.invoke(
  {
    canisterId: 'canister-id',
  },
  { configurable: { agent } },
);
Output:
  • Canister status (running/stopped)
  • Memory usage
  • Cycles balance
  • Controllers list
  • Module hash

​
Cycles Tools

​
9. get_cycles_balance

Checks cycles balance for a canister. Parameters:
  • canisterId: Canister ID to check
Usage: 
// Natural language
'Check cycles for canister xyz';
'How many cycles does my canister have?';
'Show cycles balance';

// Direct tool usage
const tool = createGetCyclesBalanceTool(agent);
const result = await tool.invoke(
  {
    canisterId: 'canister-id',
  },
  { configurable: { agent } },
);
Output:
  • Current cycles balance
  • Formatted cycles (e.g., “5.2T”)
  • Burn rate information

​
10. top_up_cycles

Adds cycles to a canister. Parameters:
  • canisterId: Canister to top up
  • amount: Cycles amount (e.g., “2T”)
Usage: 
// Natural language
'Top up canister xyz with 2 trillion cycles';
'Add 5T cycles to my canister';
'Refill canister abc with cycles';

// Direct tool usage
const result = await topUpCyclesTool.invoke(
  {
    canisterId: 'canister-id',
    amount: '2T',
  },
  { configurable: { agent } },
);

​
Tool Integration

​
Using Tools Directly

import { transferICPTool, createGetBalanceTool, createCreateCanisterTool } from 'icp-agent-kit';

// Create agent
const agent = new ICPAgent({ network: 'mainnet' });
await agent.initialize();

// Use tools directly
const balanceTool = createGetBalanceTool(agent);
const balance = await balanceTool.invoke({}, { configurable: { agent } });

// Chain tools
const canisterTool = createCreateCanisterTool(agent);
const { canisterId } = await canisterTool.invoke({ cycles: '5T' }, { configurable: { agent } });

​
Tools in Natural Language

When using natural language, tools are automatically selected: 
// The NLP processor selects the appropriate tool
await agent.processNaturalLanguage('Create a canister and check its cycles balance');
// This will use: create_canister → get_cycles_balance

​
Tools with Agents

Specialized agents have access to all tools: 
const devAgent = agent.createAgent('developer');
await devAgent.chat('Deploy my latest build to the test canister');
// Uses: deploy_wasm tool

​
Error Handling

All tools include comprehensive error handling:
Tools validate inputs and provide clear error messages for invalid parameters.
Automatic retry logic for transient network failures.
Clear messages when lacking cycles, tokens, or permissions.
If the wrong tool is selected, the error guides to the correct one.

​
Best Practices

1

Use Natural Language First

Let the NLP processor select tools automatically for complex operations.
2

Validate Addresses

Always use full principal IDs or account identifiers for transfers.
3

Handle Responses

Tools return structured data - parse responses appropriately.
4

Monitor Tool Usage

Enable verbose mode to see which tools are being used.

​
Tool Schemas

Each tool has a defined Zod schema for validation. View the full schemas in the API Reference or the source code: 
// Example: Transfer ICP schema
const transferICPSchema = z.object({
  to: z.string().describe('Recipient account ID or principal'),
  amount: z.union([z.string(), z.number()]).describe('Amount in ICP'),
  memo: z.string().optional().describe('Optional transaction memo'),
});