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 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
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'");
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...");
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...?");
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);
}
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
}
});
// 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');
}
};
- Caching: Agent responses are cached for similar queries
- Batching: Combine related operations in single messages
- Rate Limiting: Respect OpenAI API rate limits
- Network Optimization: Use local network for development/testing
Security Notes
- API Keys: Never expose OpenAI API keys in client-side code
- Validation: All inputs are validated before blockchain operations
- Permissions: Tools respect identity permissions and canister controllers
- Audit Trail: All operations are logged for debugging and audit purposes