Skip to main content

​
Project Overview & Structure

This document provides a comprehensive overview of the ICP Agent Kit project structure, current status, and technical architecture.

​
Project Overview

Production-Ready ICP Development Kit ✅ Core Infrastructure: Complete plugin system with 4 specialized modules
✅ AI Integration: LangChain tools and specialized agents for natural language interaction
✅ Sample Applications: Real-world examples demonstrating best practices
✅ Live Infrastructure: Deployed canisters for production-ready functionality
✅ Documentation: Comprehensive API reference and developer guides
✅ Quality Assurance: Extensive testing and type safety throughout

​
Technical Architecture

​
Core Components

icp-agent-kit/
├── src/
│   ├── agent.ts                    # Main ICPAgent class
│   ├── plugins/                    # Core plugin system
│   │   ├── base.ts                 # Base plugin interface
│   │   ├── identity/               # Identity management
│   │   │   ├── identity.plugin.ts
│   │   │   ├── identity.manager.ts
│   │   │   └── identity.utils.ts
│   │   ├── token/                  # Token operations
│   │   │   ├── token.plugin.ts
│   │   │   ├── token.manager.ts
│   │   │   └── ledger/
│   │   │       ├── icp-ledger.ts
│   │   │       └── icrc1-ledger.ts
│   │   ├── canister/               # Canister management
│   │   │   ├── canister.plugin.ts
│   │   │   ├── canister.manager.ts
│   │   │   └── management-canister.ts
│   │   └── cycles/                 # Cycles management
│   │       ├── cycles.plugin.ts
│   │       ├── cycles.manager.ts
│   │       └── cycles.monitor.ts
│   ├── langchain/                  # Natural language processing
│   │   ├── tools/                  # 10 specialized tools
│   │   │   ├── identity/
│   │   │   ├── token/
│   │   │   ├── canister/
│   │   │   └── cycles/
│   │   ├── agents/                 # 4 specialized agents
│   │   │   ├── developer.agent.ts
│   │   │   ├── defi.agent.ts
│   │   │   ├── governance.agent.ts
│   │   │   └── general.agent.ts
│   │   └── nlp-processor.ts        # Natural language processor
│   ├── types/                      # TypeScript definitions
│   └── utils/                      # Shared utilities
├── tests/                          # Comprehensive test suite
│   ├── unit/                       # Unit tests for all plugins
│   └── integration/                # Integration tests
├── sample-applications/            # Production-ready examples
│   ├── decentralized-trading-bot/
│   └── dao-voting-system/
├── docs/                           # Mintlify documentation
│   ├── api/                        # API reference
│   ├── plugins/                    # Plugin guides
│   ├── langchain/                  # LangChain integration
│   └── examples/                   # Examples and tutorials
└── canisters/                      # Deployed canister code
    ├── agent-connector/            # Communication canister
    ├── persistent-storage/         # Data storage canister
    └── governance-crosschain/      # Governance canister

​
Plugin System Details

​
1. Identity Plugin (IdentityPlugin)

Features:
  • BIP39 seed phrase generation (12/24 words)
  • Anonymous identity creation for testing
  • Identity switching and management
  • Principal and Account ID derivation
  • Secure in-memory storage
Key Methods:
  • generateSeedPhrase(wordCount?) - Generate BIP39 mnemonic
  • createFromSeedPhrase(phrase, key) - Create secp256k1 identity
  • createAnonymous(key) - Create anonymous identity
  • switch(key) - Switch active identity
  • getPrincipal() - Get current principal
  • getAccountId() - Get ICP account identifier

​
2. Token Plugin (TokenPlugin)

Features:
  • ICP transfers with memo support
  • ICRC-1/ICRC-2 token operations
  • Balance queries and formatting
  • Account management with subaccounts
  • Transaction utilities and validation
Key Methods:
  • getBalance(account?) - Get ICP balance
  • transfer(to, amount, options?) - Transfer ICP
  • icrc1Transfer(canisterId, to, amount) - Transfer ICRC-1 tokens
  • icrc1Balance(canisterId, account?) - Get token balance
  • icrc1Approve(canisterId, spender, amount) - Approve spending
  • getTokenMetadata(canisterId?) - Get token info

​
3. Canister Plugin (CanisterPlugin)

Features:
  • Complete lifecycle management
  • WASM deployment with chunked upload
  • Query and update method calls
  • Actor creation with IDL support
  • Controller management
  • Metrics tracking
Key Methods:
  • create(options?) - Create new canister
  • deploy(options) - Deploy WASM code
  • call(options) - Execute update call
  • query(options) - Execute query call
  • createActor(canisterId, idlFactory) - Create typed actor
  • getStatus(canisterId) - Get canister status

​
4. Cycles Plugin (CyclesPlugin)

Features:
  • Balance monitoring and health checks
  • Top-up operations via management canister
  • ICP to cycles conversion with XDR rates
  • Automated monitoring and alerts
  • Forecasting and analytics
  • Batch operations
Key Methods:
  • getBalance(canisterId) - Get cycles balance
  • topUp(canisterId, amount) - Add cycles
  • convertIcpToCycles(amount, options?) - Convert ICP
  • getForecast(canisterId) - Get depletion forecast
  • startMonitoring(config) - Start auto-monitoring
  • getBatchBalances(canisterIds) - Bulk balance check

​
LangChain Integration

​
10 Specialized Tools

Identity Tools (2):
  1. get-current-identity - Show current identity info
  2. create-identity - Create new identity (seed/anonymous)
Token Tools (3): 3. get-balance - Check ICP balance 4. transfer-icp - Transfer ICP tokens 5. icrc1-transfer - Transfer ICRC-1 tokens Canister Tools (3): 6. create-canister - Create new canister 7. deploy-wasm - Deploy WASM to canister 8. get-canister-status - Check canister status Cycles Tools (2): 9. get-cycles-balance - Check cycles balance 10. top-up-cycles - Add cycles to canister

​
4 Specialized Agents

1. Developer Agent (DeveloperAgent)
  • Focus: Canister development and deployment
  • Tools: Canister lifecycle, WASM deployment, cycles management
  • Use Cases: dApp development, testing, debugging
2. DeFi Agent (DefiAgent)
  • Focus: Token operations and financial transactions
  • Tools: Token transfers, balance queries, multi-token management
  • Use Cases: Trading, portfolio management, payments
3. Governance Agent (GovernanceAgent)
  • Focus: NNS participation and voting operations
  • Tools: Proposal voting, neuron management, staking
  • Use Cases: DAO participation, governance automation
4. General Agent (GeneralAgent)
  • Focus: All-purpose ICP operations
  • Tools: All 10 tools available
  • Use Cases: Complex workflows, multi-step operations

​
Sample Applications

​
1. Decentralized Trading Bot

Location: /sample-applications/decentralized-trading-bot/ Features:
  • AI-powered market analysis using OpenAI GPT-4
  • On-chain trade data storage via Agent Connector canister
  • Natural language processing for trading commands
  • Real-time market data integration
  • Risk management and position sizing
Technology Stack:
  • TypeScript + Node.js
  • ICP Agent Kit for blockchain operations
  • OpenAI GPT-4 for analysis
  • LangChain for natural language processing
  • Deployed canisters for data persistence

​
2. DAO Voting System

Location: /sample-applications/dao-voting-system/ Features:
  • Secure vote recording with cryptographic verification
  • Member management and access control
  • Proposal creation and execution system
  • Multi-signature governance support
  • Immutable audit trail
Technology Stack:
  • TypeScript + Node.js
  • ICP Agent Kit for identity and storage
  • Cryptographic libraries for vote verification
  • Governance CrossChain canister for execution
  • React frontend for user interface

​
Deployed Infrastructure

​
Production Canisters

1. Agent Connector (rrkah-fqaaa-aaaaa-aaaaq-cai)
  • Purpose: Communication and coordination hub
  • Features: Agent message routing, command processing
  • Used by: Trading bot, natural language processing
2. Persistent Storage (ryjl3-tyaaa-aaaaa-aaaba-cai)
  • Purpose: Data persistence and retrieval
  • Features: Trade data storage, user preferences, analytics
  • Used by: Trading bot data storage, application state
3. Governance CrossChain (rdmx6-jaaaa-aaaaa-aaadq-cai)
  • Purpose: Governance and cross-chain operations
  • Features: Vote execution, proposal management, token bridging
  • Used by: DAO voting system, governance automation

​
Network Configuration

Supported Networks:
  • Internet Computer Mainnet (production)
  • Local dfx replica (development)
  • Custom RPC endpoints (enterprise)
Connection Management:
  • Automatic network detection
  • Connection pooling and optimization
  • Retry mechanisms with exponential backoff
  • Certificate verification for security

​
Documentation Structure

​
API Reference (/docs/agent-api-reference/)

Complete API Documentation:
  • icp-agent.mdx - Main ICPAgent class
  • identity-plugin.mdx - Identity management API
  • token-plugin.mdx - Token operations API
  • canister-plugin.mdx - Canister management API
  • cycles-plugin.mdx - Cycles management API
  • langchain-tools.mdx - Natural language tools API

​
Plugin Guides (/docs/plugins/)

Comprehensive Plugin Documentation:
  • identity.mdx - Identity plugin guide
  • token.mdx - Token plugin guide
  • canister.mdx - Canister plugin guide
  • cycles.mdx - Cycles plugin guide

​
LangChain Integration (/docs/langchain/)

Natural Language Processing Guides:
  • overview.mdx - LangChain integration overview
  • tools.mdx - Tool usage and configuration
  • natural-language.mdx - Natural language processing

​
Testing Strategy

​
Unit Tests (/tests/unit/)

Comprehensive Plugin Coverage:
  • plugins/identity.plugin.unit.test.ts - Identity plugin tests
  • plugins/token.plugin.unit.test.ts - Token plugin tests
  • plugins/canister.plugin.unit.test.ts - Canister plugin tests
  • plugins/cycles.plugin.unit.test.ts - Cycles plugin tests
Test Patterns:
  • Mock-based testing for isolated unit tests
  • Type safety validation
  • Error handling verification
  • Plugin lifecycle testing

​
Integration Tests (/tests/integration/)

End-to-End Testing:
  • Real network interactions
  • Multi-plugin workflows
  • Sample application testing
  • Canister deployment verification

​
Development Workflow

​
Build System

# Development commands
npm run dev           # Development mode with hot reload
npm run build         # TypeScript compilation
npm run test          # Run all tests
npm run test:unit     # Unit tests only
npm run test:integration # Integration tests only
npm run lint          # ESLint validation
npm run typecheck     # TypeScript type checking

​
Code Quality

Standards:
  • TypeScript strict mode enabled
  • ESLint with comprehensive rules
  • Prettier for code formatting
  • 100% type safety target
  • Comprehensive error handling
Security:
  • Private keys never logged or exposed
  • Input validation for all parameters
  • Certificate verification for queries
  • Secure identity storage patterns

​
Performance Characteristics

​
Optimization Features

Caching:
  • Actor instance caching for repeated calls
  • Status information caching with TTL
  • Principal and account ID calculation caching
Batch Operations:
  • Multi-canister balance queries
  • Bulk cycles top-up operations
  • Parallel transaction processing
Network Efficiency:
  • Connection pooling for HTTP agents
  • Request deduplication
  • Automatic retry with backoff

​
Memory Management

Resource Cleanup:
  • Proper agent destruction
  • Identity storage cleanup
  • Cache eviction policies
  • Memory leak prevention

​
Next Steps & Roadmap

​
Immediate Priorities

  1. NPM Package Publishing
    • Official package release
    • Version management
    • Distribution optimization
  2. Enhanced Documentation
    • Video tutorials
    • Interactive examples
    • Migration guides
  3. Performance Optimization
    • Advanced caching strategies
    • Batch operation improvements
    • Memory usage optimization

​
Future Enhancements

  1. Governance Plugin
    • NNS integration
    • Neuron management
    • Proposal voting automation
  2. Advanced Features
    • Internet Identity integration
    • Multi-signature support
    • Cross-chain capabilities
  3. Developer Tools
    • CLI utilities
    • Development plugins
    • Testing frameworks
The ICP Agent Kit represents a mature, production-ready solution for ICP blockchain interaction with both traditional API access and cutting-edge natural language processing capabilities.