Agent Guide

Understanding Axicov Agents

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
}

Parameters System

Agents have two parameter objects:

params: Persistent configuration data

agent.params = {
  name: "Market Analyst",
  instruction: "Provide financial market analysis and advice",
  expertise: ["crypto", "stocks", "commodities"],
  preferredDataSources: ["CoinGecko", "Yahoo Finance"]
};

runtimeParams: Temporary session data

agent.runtimeParams = {
  currentAnalysis: {
    asset: "BTC",
    timeframe: "1d",
    indicators: ["RSI", "MACD"]
  },
  lastUpdated: Date.now(),
  calculationResults: {}
};

Advanced Agent Features

Custom System Prompts

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

Next Steps

PreviousClients Guide NextTools

Last updated 3 months ago