Agents are the core components of the Axicov platform. Each agent is a conversational AI assistant with its own identity, capabilities, and memory. This guide will help you understand how to create, configure, and interact with agents using the Axicov SDK.
Agent Lifecycle
1. Creation
The first step is creating an Agent instance with a unique thread ID and configuration parameters:
import { Agent } from "axicov-sdk";
const agent = new Agent({
threadId: "user123-session456", // Unique identifier for this conversation
params: {
name: "Axicov Assistant", // The agent's name
instruction: "You are a helpful AI assistant focused on blockchain technology", // Base instructions
// Any other persistent parameters
}
});
2. Initialization
After creating an agent, you need to initialize it with tools and configure its storage:
await agent.initialize({
toolNumbers: [0, 1, 3], // Select specific tools by index
client: [blockchainClient], // Essential tools
allRegistry: [
blockchainToolRegistry, // index 0
cryptoDataToolRegistry, // index 1
transactionToolRegistry, // index 2
nftToolRegistry, // index 3
],
checkPointer: "mongo", // "local" or "mongo" for persistence
});
3. Interaction
Once initialized, you can send messages to the agent and receive responses:
const response = await agent.messageAgent("What's the current price of Sonic?");
console.log(response);
4. State Management
Agents maintain state between messages using their checkpoint system:
// First message in a conversation
const response1 = await agent.messageAgent("Tell me about NFTs");
// Later message in the same conversation (same threadId)
const response2 = await agent.messageAgent("How can I create one?");
// The agent remembers the context from the first message
Agent Configuration
Essential Properties
The Agent class has several important properties:
class Agent {
public threadId: string; // Unique conversation identifier
public tools: any[]; // List of available tools
public toolMetadata: string; // Tool descriptions for the agent
public model; // The underlying AI model
public systemPrompt?: SystemMessage; // Instructions for the agent
public mongoClient: any; // MongoDB client (if using mongo checkpointing)
public checkPointSaver: any; // Storage system for conversation state
public config; // Configuration object
public agent: any; // The underlying LangGraph agent
public params: any; // Persistent parameters
public runtimeParams: any; // Temporary runtime parameters
}
When initializing an agent, a system prompt is automatically generated based on your configuration. However, you can also customize it after initialization:
import { SystemMessage } from "@langchain/core/messages";
// After initialization but before sending messages
agent.systemPrompt = new SystemMessage(`
You are ${agent.params.name}, an expert in blockchain technology.
Your goal is to help users understand and navigate the crypto ecosystem.
Always explain complex concepts in simple terms.
When analyzing market data, consider both technical and fundamental factors.
`);
Thread Context Management
Axicov uses thread contexts to isolate conversations:
import { setThreadContext, clearThreadContext } from "axicov-sdk";
// Manually manage thread context if needed
setThreadContext("user456-session789");
// Always clear context when done
clearThreadContext();
Error Handling
Implement proper error handling when working with agents:
async function sendMessage(agent, message) {
try {
await setThreadContext(agent.threadId);
const response = await agent.messageAgent(message);
clearThreadContext();
return response;
} catch (error) {
console.error("Agent error:", error);
clearThreadContext(); // Always clear context, even on error
return "I encountered an error processing your request.";
}
}
Working with Different Models
Axicov supports multiple underlying AI models:
Anthropic Claude
// Claude is used automatically if ANTHROPIC_API_KEY is set in .env
process.env.ANTHROPIC_API_KEY = "your-anthropic-api-key";
const agent = new Agent({
threadId: "claude-test",
params: { name: "Claude Assistant" }
});
Google Gemini
// Gemini is used if GEMINI_API_KEY is set and ANTHROPIC_API_KEY is not
process.env.GEMINI_API_KEY = "your-gemini-api-key";
const agent = new Agent({
threadId: "gemini-test",
params: { name: "Gemini Assistant" }
});
Best Practices
Unique Thread IDs: Use unique and consistent thread IDs for each conversation
Clear Instructions: Provide clear instructions in the agent's parameters
Tool Selection: Only include tools that the agent actually needs
Error Handling: Always implement proper error handling and context clearing
Parameter Usage: Use params for persistent data and runtimeParams for temporary data
Model Selection: Choose the appropriate AI model for your use case
Performance: Initialize agents once and reuse them for multiple interactions
Example: Creating a Specialized Agent
import { Agent } from "axicov-sdk";
import { blockchainToolRegistry } from "./tools/blockchain";
import { analyticsToolRegistry } from "./tools/analytics";
async function createCryptoAnalyst() {
// Create unique thread ID
const threadId = `crypto-analyst-${Date.now()}`;
// Create agent with specialized configuration
const agent = new Agent({
threadId,
params: {
name: "Crypto Analyst",
instruction: "Analyze cryptocurrency markets and provide insights to users",
expertise: ["technical analysis", "blockchain fundamentals", "market trends"],
dataPreferences: {
timeframes: ["1h", "4h", "1d", "1w"],
indicators: ["RSI", "MACD", "Moving Averages"]
}
}
});
// Initialize with specific tools
await agent.initialize({
toolNumbers: [0, 1, 3], // Select specific blockchain tools
coreRegistry: [analyticsToolRegistry], // Core analytics capabilities
allRegistry: [blockchainToolRegistry],
checkPointer: "mongo" // Use persistent storage
});
return agent;
}
// Usage
async function main() {
const analyst = await createCryptoAnalyst();
const analysis = await analyst.messageAgent("Analyze BTC price action for the last week");
console.log(analysis);
}
