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();