The ICP Agent Kit provides a comprehensive suite of LangChain tools for natural language processing of ICP operations. These tools enable AI agents to perform complex blockchain operations through conversational interfaces.

Overview

The LangChain integration includes:
  • 10 Core Tools: Cover all major ICP operations
  • 4 Specialized Agents: Pre-configured for different use cases
  • Natural Language Processing: Convert human language to blockchain operations
  • Type Safety: Full TypeScript support with proper validation

Tool Categories

Identity Tools

get-current-identity

Get information about the currently active identity. Description: “Get information about the currently active identity including principal, account ID, and type” Parameters: None Returns: Identity information as JSON string Example Usage:
const defiAgent = agent.createAgent('defi');
const response = await defiAgent.chat("What's my current identity?");
// Returns: "Current identity: principal abc123..., account ID: def456..., type: secp256k1"

create-identity

Create a new identity from seed phrase or generate anonymous identity. Description: “Create a new identity. Use ‘type: anonymous’ for anonymous identity or ‘type: seed’ with seedPhrase for secp256k1 identity” Parameters:
  • type: 'anonymous' | 'seed' - Type of identity to create
  • key: string - Unique identifier for the identity
  • seedPhrase (optional): string - Seed phrase for secp256k1 identity
Returns: Creation result with identity information Example Usage:
const response = await defiAgent.chat("Create a new anonymous identity called 'test-wallet'");
const response2 = await defiAgent.chat("Create an identity from seed phrase 'abandon abandon...' with key 'main-wallet'");

Token Tools

get-balance

Check ICP balance for current identity or specific account. Description: “Get ICP balance for the current identity or a specific account” Parameters:
  • account (optional): string - Account identifier to check
Returns: Balance information with formatted amount Example Usage:
const response = await defiAgent.chat("What's my ICP balance?");
const response2 = await defiAgent.chat("Check balance for account abc123...");

transfer-icp

Transfer ICP tokens to another account. Description: “Transfer ICP tokens to another account with optional memo” Parameters:
  • to: string - Recipient account identifier
  • amount: string - Amount to transfer (in ICP, e.g., “1.5”)
  • memo (optional): string - Transaction memo
Returns: Transfer result with block height Example Usage:
const response = await defiAgent.chat("Transfer 2.5 ICP to account def456... with memo 'Payment for services'");

icrc1-transfer

Transfer ICRC-1 tokens. Description: “Transfer ICRC-1 tokens from a specific token canister” Parameters:
  • canisterId: string - Token canister ID
  • to: string - Recipient principal
  • amount: string - Amount to transfer
  • memo (optional): string - Transaction memo
Returns: Transfer result with transaction ID Example Usage:
const response = await defiAgent.chat("Transfer 1000 tokens from canister xyz123... to principal abc456...");

Canister Tools

create-canister

Create a new canister with specified cycles. Description: “Create a new canister with specified cycles amount” Parameters:
  • cycles: string - Initial cycles amount (e.g., “5T” for 5 trillion)
Returns: Created canister information Example Usage:
const devAgent = agent.createAgent('developer');
const response = await devAgent.chat("Create a new canister with 10T cycles");

deploy-wasm

Deploy WASM module to a canister. Description: “Deploy WASM module to an existing canister” Parameters:
  • canisterId: string - Target canister ID
  • wasmPath: string - Path to WASM file
  • mode (optional): 'install' | 'upgrade' | 'reinstall' - Deployment mode
Returns: Deployment result Example Usage:
const response = await devAgent.chat("Deploy WASM from ./hello-world.wasm to canister abc123... in upgrade mode");

get-canister-status

Get detailed status information about a canister. Description: “Get detailed status information about a canister including cycles, memory usage, and controllers” Parameters:
  • canisterId: string - Canister ID to query
Returns: Comprehensive status information Example Usage:
const response = await devAgent.chat("What's the status of canister xyz789...?");

Cycles Tools

get-cycles-balance

Check cycles balance for a canister. Description: “Get cycles balance and status information for a specific canister” Parameters:
  • canisterId: string - Canister ID to check
Returns: Cycles balance and burn rate information Example Usage:
const response = await devAgent.chat("Check cycles balance for canister abc123...");

top-up-cycles

Add cycles to a canister. Description: “Add cycles to a canister to keep it running” Parameters:
  • canisterId: string - Canister to top up
  • amount: string - Cycles amount (e.g., “2T”)
Returns: Top-up confirmation Example Usage:
const response = await devAgent.chat("Top up canister xyz789... with 5T cycles");

Specialized Agents

Developer Agent

Pre-configured for canister development and deployment workflows. Capabilities:
  • Canister lifecycle management
  • WASM deployment and upgrades
  • Cycles monitoring and management
  • Development environment setup
Example Usage:
const devAgent = agent.createAgent('developer');

// Complete development workflow
await devAgent.chat("Create a new canister with 10T cycles");
await devAgent.chat("Deploy my hello-world.wasm to the canister");
await devAgent.chat("Check the canister status and cycles balance");
await devAgent.chat("If cycles are low, top up with 5T more");

DeFi Agent

Specialized for token operations and financial transactions. Capabilities:
  • ICP and ICRC token transfers
  • Balance management
  • Multi-token portfolio tracking
  • Transaction history analysis
Example Usage:
const defiAgent = agent.createAgent('defi');

// DeFi operations
await defiAgent.chat("What's my current ICP balance?");
await defiAgent.chat("Transfer 5 ICP to principal abc123... with memo 'Investment'");
await defiAgent.chat("Check my balance in token canister xyz789...");
await defiAgent.chat("Transfer 1000 tokens to def456...");

Governance Agent

Focused on NNS governance and voting operations. Capabilities:
  • Proposal voting
  • Neuron management
  • Governance participation
  • Staking operations
Example Usage:
const govAgent = agent.createAgent('governance');

// Governance operations
await govAgent.chat("Show me current governance proposals");
await govAgent.chat("Vote YES on proposal 12345");
await govAgent.chat("Check my neuron status");
await govAgent.chat("Stake 10 ICP in governance");

General Agent

All-purpose agent with access to all tools. Capabilities:
  • Full access to all ICP operations
  • Cross-functional workflows
  • Complex multi-step operations
  • Comprehensive blockchain management
Example Usage:
const generalAgent = agent.createAgent('general');

// Complex multi-step workflow
await generalAgent.chat(`
  I want to deploy a new application:
  1. Create a canister with 20T cycles
  2. Deploy my app.wasm to it
  3. Check that it's running properly
  4. Transfer 1 ICP to the canister's account for operations
  5. Set up monitoring for cycles balance
`);

Natural Language Processing

Direct Processing

Process natural language commands directly through the main agent.
// Single operation
const result = await agent.processNaturalLanguage("Check my ICP balance");

// Complex operation
const result = await agent.processNaturalLanguage(
  "Create a new canister, deploy my hello-world.wasm, and top it up with 5T cycles"
);

// Conditional operation
const result = await agent.processNaturalLanguage(
  "If my ICP balance is above 10 ICP, transfer 5 ICP to account abc123..."
);

Multi-Step Workflows

const defiAgent = agent.createAgent('defi');

const conversation = [
  "What's my current portfolio?",
  "Transfer 2 ICP to my trading account",
  "Check the balance after transfer",
  "If successful, also transfer 1000 tokens from my main token canister"
];

for (const message of conversation) {
  const response = await defiAgent.chat(message);
  console.log('Response:', response);
}

Error Handling and Validation

The LangChain tools include comprehensive error handling:
try {
  const response = await defiAgent.chat("Transfer 999999 ICP to invalid-account");
} catch (error) {
  // Handles validation errors, insufficient funds, invalid accounts, etc.
  console.log('Error:', error.message);
}

Tool Integration Patterns

Custom Workflows

// Create a custom workflow combining multiple tools
const customWorkflow = async (agent: ICPSpecializedAgent) => {
  // Step 1: Check current state
  const balance = await agent.chat("What's my ICP balance?");
  
  // Step 2: Conditional logic
  if (parseFloat(balance) > 5) {
    await agent.chat("Create a new canister with 10T cycles");
    await agent.chat("Deploy my application WASM");
  }
  
  // Step 3: Monitoring setup
  await agent.chat("Check canister status and set up monitoring");
};

const devAgent = agent.createAgent('developer');
await customWorkflow(devAgent);

Batch Operations

const operations = [
  "Check cycles balance for canister-1",
  "Check cycles balance for canister-2", 
  "Check cycles balance for canister-3",
  "Top up any canisters with less than 2T cycles"
];

const generalAgent = agent.createAgent('general');
for (const operation of operations) {
  const result = await generalAgent.chat(operation);
  console.log(`${operation}: ${result}`);
}

Configuration and Customization

OpenAI Configuration

const agent = new ICPAgent({
  network: 'mainnet',
  openai: {
    apiKey: 'your-openai-key',
    model: 'gpt-4-turbo-preview', // or 'gpt-3.5-turbo'
    temperature: 0.1, // Lower for more deterministic responses
    maxTokens: 1000
  }
});

Tool Filtering

// Create agent with only specific tools
const limitedAgent = agent.createAgent('defi', {
  enabledTools: ['get-balance', 'transfer-icp', 'get-current-identity']
});

Best Practices

1. Clear Commands

// Good: Specific and clear
await agent.chat("Transfer 2.5 ICP to account abc123 with memo 'payment'");

// Avoid: Ambiguous or unclear
await agent.chat("send some tokens somewhere");

2. Error Recovery

const safeTransfer = async (agent, to, amount) => {
  try {
    // First check balance
    const balance = await agent.chat("What's my ICP balance?");
    
    // Then attempt transfer
    const result = await agent.chat(`Transfer ${amount} ICP to ${to}`);
    return result;
  } catch (error) {
    console.log('Transfer failed, checking balance...');
    await agent.chat("What's my current balance?");
    throw error;
  }
};

3. State Validation

// Validate operations completed successfully
const deployWorkflow = async (agent) => {
  const createResult = await agent.chat("Create canister with 10T cycles");
  
  // Verify creation
  const status = await agent.chat("Get status of the new canister");
  
  if (status.includes('running')) {
    await agent.chat("Deploy my app.wasm to the canister");
  } else {
    throw new Error('Canister creation failed');
  }
};

Performance Considerations

  1. Caching: Agent responses are cached for similar queries
  2. Batching: Combine related operations in single messages
  3. Rate Limiting: Respect OpenAI API rate limits
  4. Network Optimization: Use local network for development/testing

Security Notes

  1. API Keys: Never expose OpenAI API keys in client-side code
  2. Validation: All inputs are validated before blockchain operations
  3. Permissions: Tools respect identity permissions and canister controllers
  4. Audit Trail: All operations are logged for debugging and audit purposes