Skip to main content
The ICPAgent class is the main entry point for the ICP Agent Kit, providing access to all plugins and LangChain integration.

​
Constructor

​
new ICPAgent(config)

Creates a new ICP Agent instance. Parameters:
  • config (optional): Configuration object
    • network: 'mainnet' | 'local' - Network to connect to (default: ‘local’)
    • identity: Identity | string - Identity instance or seed phrase
    • host: string - Custom RPC host
    • plugins: string[] - Plugins to enable (default: all)
    • openai: OpenAI configuration for natural language processing
      • apiKey: string - OpenAI API key
      • model: string - Model to use (default: ‘gpt-4-turbo-preview’)
Example: 
import { ICPAgent } from 'icp-agent-kit';

// Basic usage
const agent = new ICPAgent();

// With configuration
const agent = new ICPAgent({
  network: 'mainnet',
  identity: 'your-seed-phrase-here',
  openai: {
    apiKey: 'your-openai-key',
    model: 'gpt-4'
  }
});

​
Properties

​
identityPlugin

Access to the Identity Plugin for managing identities, seed phrases, and authentication. Type: IdentityPlugin

​
tokenPlugin

Access to the Token Plugin for ICP transfers, ICRC-1/ICRC-2 operations, and balance queries. Type: TokenPlugin

​
canisterPlugin

Access to the Canister Plugin for lifecycle management, WASM deployment, and method calls. Type: CanisterPlugin

​
cyclesPlugin

Access to the Cycles Plugin for cycles management, monitoring, and forecasting. Type: CyclesPlugin

​
config

Current agent configuration. Type: IICPAgentConfig

​
identity

Current identity being used by the agent. Type: Identity

​
Methods

​
createAgent(type)

Creates a specialized LangChain agent for natural language processing. Parameters:
  • type: 'developer' | 'defi' | 'governance' | 'general' - Type of specialized agent
Returns: ICPSpecializedAgent Example: 
const defiAgent = agent.createAgent('defi');
const response = await defiAgent.chat("Transfer 5 ICP to principal abc123");

​
processNaturalLanguage(command)

Process a natural language command directly through the agent. Parameters:
  • command: string - Natural language command to execute
Returns: Promise<string> - Execution result Example: 
const result = await agent.processNaturalLanguage(
  "Check my ICP balance and transfer 2 ICP to rdmx6-jaaaa-aaaaa-aaadq-cai"
);

​
getActor(canisterId, idlFactory)

Create a typed actor for canister interactions. Parameters:
  • canisterId: Principal | string - Canister ID
  • idlFactory: IDL.InterfaceFactory - Candid interface factory
Returns: ActorSubclass<T> - Typed actor instance Example: 
import { idlFactory } from './hello-world.did.js';

const actor = agent.getActor('rdmx6-jaaaa-aaaaa-aaadq-cai', idlFactory);
const result = await actor.greet('World');

​
getPrincipal()

Get the current identity’s principal. Returns: Principal - Current principal

​
getIdentity()

Get the current identity instance. Returns: Identity - Current identity

​
destroy()

Clean up resources and destroy the agent. Returns: Promise<void>

​
Plugin Access Patterns

​
Direct Plugin Usage

// Identity operations
const seedPhrase = agent.identityPlugin.generateSeedPhrase();
await agent.identityPlugin.createFromSeedPhrase(seedPhrase, 'my-wallet');

// Token operations
const balance = await agent.tokenPlugin.getBalance();
await agent.tokenPlugin.transfer('recipient-account', 100_000_000n);

// Canister operations
const { canisterId } = await agent.canisterPlugin.create();
await agent.canisterPlugin.deploy({ canisterId, wasmModule });

// Cycles operations
const cyclesBalance = await agent.cyclesPlugin.getBalance('canister-id');
await agent.cyclesPlugin.topUp('canister-id', '2T');

​
Natural Language Usage

// Using specialized agents
const defiAgent = agent.createAgent('defi');
await defiAgent.chat("What's my current ICP balance?");

// Direct natural language processing
await agent.processNaturalLanguage("Create a new canister with 5T cycles");

​
Error Handling

The ICP Agent Kit uses custom error types for better error handling: 
import { ICPAgentError } from 'icp-agent-kit';

try {
  await agent.tokenPlugin.transfer('invalid-account', 100n);
} catch (error) {
  if (error instanceof ICPAgentError) {
    console.log('Error code:', error.code);
    console.log('Error message:', error.message);
    console.log('Timestamp:', error.timestamp);
  }
}

​
TypeScript Support

Full TypeScript support with strict typing: 
import { ICPAgent, IICPAgentConfig, Principal } from 'icp-agent-kit';

const config: IICPAgentConfig = {
  network: 'mainnet',
  identity: 'seed phrase here'
};

const agent = new ICPAgent(config);
const principal: Principal = agent.getPrincipal();