SDK

Agents

Agents are the central building blocks in Agentopia. An agent is an AI-powered entity that can:

• Process natural language inputs
• Use tools to interact with external systems
• Maintain context through memory
• Make decisions based on goals and constraints

// JavaScript
const agent = new Agent({
  name: 'Customer Support',
  description: 'I help users with product questions',
  model: 'gpt-4',
  tools: [searchKnowledgeBase, createTicket],
  memory: new VectorMemory()
});

Tools

Tools enable agents to perform actions in the real world or access external information. A tool consists of:

• A name and description
• Parameter definitions
• An execution function

# Python
search_tool = Tool(
    name="search_database",
    description="Search the product database for information",
    parameters={
        "query": {
            "type": "string",
            "description": "The search query"
        },
        "limit": {
            "type": "integer",
            "description": "Maximum number of results",
            "default": 5
        }
    },
    function=search_database_function
)

Memory

Memory systems allow agents to retain information across interactions. Agentopia supports several memory types:

// JavaScript
const memory = new VectorMemory({
  collection: 'customer-support',
  embedModel: 'text-embedding-ada-002'
});

// Add information to memory
await memory.add({
  content: 'Our return policy allows returns within 30 days of purchase.',
  metadata: { category: 'policy', topic: 'returns' }
});

// Query memory
const results = await memory.search('How long do I have to return items?');

Multi-Agent Systems

Complex problems often require multiple specialized agents working together. Agentopia provides:

• Agent orchestration for coordinating multiple agents
• Message passing between agents
• Role-based agent definitions
• Workflow management for complex processes

# Python
from agentopia import AgentTeam, Agent

# Create specialized agents
researcher = Agent(name="Researcher", ...)
writer = Agent(name="Writer", ...)
editor = Agent(name="Editor", ...)

# Create a team
content_team = AgentTeam(
    name="Content Creation Team",
    agents=[researcher, writer, editor],
    workflow={
        "start": "researcher",
        "transitions": {
            "researcher": {"next": "writer", "condition": "research_complete"},
            "writer": {"next": "editor", "condition": "draft_complete"},
            "editor": {"next": "end", "condition": "editing_complete"}
        }
    }
)

# Run the team on a task
result = content_team.execute("Create an article about AI agents")

Agent Class

The core class for creating and managing AI agents.

new Agent({
  name: string,              // Agent name
  description: string,       // Agent description
  model: string,             // LLM model to use (e.g., 'gpt-4')
  tools?: Tool[],            // Array of tools
  memory?: Memory,           // Memory system
  systemPrompt?: string,     // Custom system prompt
  temperature?: number,      // Temperature for generation (0-1)
  maxTokens?: number,        // Maximum tokens in response
  options?: object           // Additional options
})

agent.chat({
  messages: [{ role: 'user', content: string }],
  stream?: boolean,
  tools?: Tool[],
  toolChoice?: string | object
})

agent.addTool(new Tool({...}))

agent.removeTool('tool_name')

agent.setMemory(new VectorMemory({...}))

Tool Class

Define tools that agents can use to perform actions or retrieve information.

new Tool({
  name: string,              // Tool name (must be unique)
  description: string,       // Tool description
  parameters: object,        // JSON Schema for parameters
  execute: function,         // Function to execute
  required?: boolean,        // Whether tool is required
  options?: object           // Additional options
})

const result = await tool.execute({ param1: 'value1' })

const isValid = tool.validate({ param1: 'value1' })

Memory Classes

Classes for implementing different types of memory systems.

new ConversationMemory({
  maxMessages?: number,      // Maximum messages to store
  summarizeThreshold?: number, // When to summarize history
  options?: object           // Additional options
})

new VectorMemory({
  collection: string,        // Collection name
  embedModel?: string,       // Embedding model to use
  dimensions?: number,       // Vector dimensions
  similarity?: string,       // Similarity metric
  options?: object           // Additional options
})

new StructuredMemory({
  schema: object,            // JSON Schema for data
  storage?: string,          // Storage backend
  options?: object           // Additional options
})

AgentTeam Class

Create and manage multi-agent systems.

new AgentTeam({
  name: string,              // Team name
  agents: Agent[],           // Array of agents
  workflow?: object,         // Workflow definition
  supervisor?: Agent,        // Supervisor agent
  options?: object           // Additional options
})

const result = await team.execute('Analyze this data and create a report')

team.addAgent(new Agent({...}), 'researcher')

Customer Support Agent

Create a customer support agent that can answer questions and create support tickets.

// JavaScript
const { Agent, Tool, VectorMemory } = require('@agentopia/sdk');

// Create knowledge base tool
const knowledgeBaseTool = new Tool({
  name: 'search_knowledge_base',
  description: 'Search the knowledge base for information',
  parameters: {
    query: {
      type: 'string',
      description: 'The search query'
    }
  },
  execute: async ({ query }) => {
    // In a real app, search your knowledge base
    return 'Information about: ' + query;
  }
});

// Create ticket creation tool
const createTicketTool = new Tool({
  name: 'create_support_ticket',
  description: 'Create a support ticket for issues that cannot be resolved',
  parameters: {
    issue: {
      type: 'string',
      description: 'Description of the issue'
    },
    priority: {
      type: 'string',
      enum: ['low', 'medium', 'high'],
      description: 'Ticket priority'
    }
  },
  execute: async ({ issue, priority }) => {
    // In a real app, create a ticket in your system
    return `Ticket created with issue: ${issue} and priority: ${priority}`;
  }
});

// Create memory system
const memory = new VectorMemory({
  collection: 'support-knowledge',
  embedModel: 'text-embedding-ada-002'
});

// Add knowledge to memory
await memory.add({
  content: 'Our return policy allows returns within 30 days of purchase with receipt.',
  metadata: { category: 'policy', topic: 'returns' }
});

await memory.add({
  content: 'Premium support is available 24/7 for enterprise customers.',
  metadata: { category: 'support', topic: 'premium' }
});

// Create the support agent
const supportAgent = new Agent({
  name: 'Support Assistant',
  description: 'I help customers with product questions and issues',
  model: 'gpt-4',
  tools: [knowledgeBaseTool, createTicketTool],
  memory: memory,
  systemPrompt: `You are a helpful customer support agent. 
  Always be polite and professional.
  Search the knowledge base before answering.
  Create a support ticket only if you cannot resolve the issue.`
});

// Start a conversation
const response = await supportAgent.chat({
  messages: [
    { role: 'user', content: 'What is your return policy?' }
  ]
});

Data Analysis Team

Create a multi-agent system for analyzing data and generating reports.

# Python
from agentopia import Agent, Tool, AgentTeam

# Create specialized agents
data_processor = Agent(
    name="Data Processor",
    description="I clean and prepare data for analysis",
    model="gpt-4",
    tools=[
        Tool(name="load_data", function=load_data_function),
        Tool(name="clean_data", function=clean_data_function)
    ]
)

analyst = Agent(
    name="Data Analyst",
    description="I analyze data and identify patterns",
    model="gpt-4",
    tools=[
        Tool(name="analyze_data", function=analyze_data_function),
        Tool(name="create_visualization", function=create_visualization_function)
    ]
)

report_writer = Agent(
    name="Report Writer",
    description="I create comprehensive reports based on analysis",
    model="gpt-4",
    tools=[
        Tool(name="generate_report", function=generate_report_function)
    ]
)

# Create the team
analysis_team = AgentTeam(
    name="Data Analysis Team",
    agents=[data_processor, analyst, report_writer],
    workflow={
        "start": "data_processor",
        "transitions": {
            "data_processor": {"next": "analyst", "condition": "data_prepared"},
            "analyst": {"next": "report_writer", "condition": "analysis_complete"},
            "report_writer": {"next": "end", "condition": "report_generated"}
        }
    }
)

# Execute a data analysis task
result = analysis_team.execute(
    "Analyze the sales data for Q2 2025 and create a comprehensive report"
)

Web Research Agent

Create an agent that can search the web and summarize information.

// JavaScript
const { Agent, Tool } = require('@agentopia/sdk');

// Create web search tool
const searchTool = new Tool({
  name: 'web_search',
  description: 'Search the web for information',
  parameters: {
    query: {
      type: 'string',
      description: 'The search query'
    },
    num_results: {
      type: 'integer',
      description: 'Number of results to return',
      default: 5
    }
  },
  execute: async ({ query, num_results }) => {
    // In a real app, use a search API
    return `Search results for: ${query} (${num_results} results)`;
  }
});

// Create webpage reader tool
const readPageTool = new Tool({
  name: 'read_webpage',
  description: 'Read the content of a webpage',
  parameters: {
    url: {
      type: 'string',
      description: 'The URL of the webpage to read'
    }
  },
  execute: async ({ url }) => {
    // In a real app, fetch and parse the webpage
    return `Content from: ${url}`;
  }
});

// Create the research agent
const researchAgent = new Agent({
  name: 'Research Assistant',
  description: 'I help with web research and summarization',
  model: 'gpt-4',
  tools: [searchTool, readPageTool],
  systemPrompt: `You are a research assistant.
  When asked to research a topic:
  1. Search the web for relevant information
  2. Read the most promising webpages
  3. Synthesize the information into a comprehensive summary
  4. Cite your sources`
});

// Start a research task
const response = await researchAgent.chat({
  messages: [
    { role: 'user', content: 'Research the latest developments in quantum computing' }
  ]
});

Authentication Issues

// Check if your API key is properly set
console.log(agentopia.getConfig().apiKey.substring(0, 5) + '...');

// Ensure you're using the latest SDK version
npm list @agentopia/sdk

const { retryWithBackoff } = require('@agentopia/sdk/utils');

const response = await retryWithBackoff(
  () => agent.chat({ messages: [...] }),
  {
    maxRetries: 5,
    initialDelay: 1000,
    maxDelay: 10000
  }
);

Tool Execution Issues

// Make tool descriptions more specific
const tool = new Tool({
  name: 'search_database',
  description: 'Search the product database for specific product information including price, availability, and specifications',
  // Rest of tool definition
});

// Explicitly tell the agent to use the tool
const response = await agent.chat({
  messages: [...],
  toolChoice: 'search_database'  // Or 'auto' to let the agent decide
});

const tool = new Tool({
  // Tool definition
  execute: async (params) => {
    try {
      // Tool implementation
      return result;
    } catch (error) {
      // Return a user-friendly error message
      return `Unable to complete operation: ${error.message}`;
    }
  }
});

Memory Issues

// Check if memory is properly configured
console.log(agent.memory.getStats());

// Implement conversation summarization for long interactions
const memory = new ConversationMemory({
  maxMessages: 20,
  summarizeThreshold: 15,
  summarizeFunction: async (messages) => {
    // Create a summary of the conversation
    return summary;
  }
});

// Adjust vector memory settings
const memory = new VectorMemory({
  collection: 'knowledge-base',
  embedModel: 'text-embedding-ada-002',
  similarity: 'cosine',
  minSimilarity: 0.75,  // Increase threshold for better matches
  maxResults: 5
});

Getting Help

If you're still experiencing issues, you can:

• Check our comprehensive documentation
• Join our community Discord for real-time support
• Open an issue on GitHub
• Contact our support team for enterprise customers

// JavaScript
const { diagnose } = require('@agentopia/sdk/utils');

// Run diagnostics
const report = await diagnose({
  checkAuth: true,
  checkConnectivity: true,
  checkModels: true,
  verbose: true
});

console.log(report);