Skip to main content

​
Create Agent

Create an autonomous AI agent with custom tools and capabilities.

​
Constructor

new Agent(config: AgentConfig)

​
Parameters

​
config
AgentConfig
required
Configuration object for the agent
​
config.name
string
required
Name of the agent
​
config.description
string
required
Description of the agent’s purpose and capabilities
​
config.systemPrompt
string
System prompt that defines the agent’s behavior and personality
​
config.tools
AgentTool[]
default:"[]"
Array of tools available to the agent
​
config.memory
Memory
Memory instance for persistent storage
​
config.chat
Chat
Chat instance for AI interactions
​
config.maxIterations
number
default:"10"
Maximum number of iterations for task execution
​
config.timeout
number
default:"300000"
Timeout for agent execution in milliseconds

​
Response

Returns an Agent instance that can execute tasks autonomously.

​
Examples

import { Agent, Chat, Memory } from 'nebula-sdk';

const chat = new Chat({ apiKey: 'your-api-key' });
const memory = new Memory({ storageKey: 'agent-memory' });

const agent = new Agent({
  name: 'Assistant',
  description: 'A helpful AI assistant that can perform various tasks',
  systemPrompt: `You are a helpful AI assistant. You can use tools to help users accomplish their goals. 
                 Always be polite and explain what you're doing.`,
  chat,
  memory,
  maxIterations: 5
});

​
Tool Definition

​
AgentTool Interface

interface AgentTool {
  name: string;
  description: string;
  parameters?: JSONSchema;
  execute: (params?: any) => Promise<any> | any;
}
​
name
string
required
Unique name for the tool
​
description
string
required
Description of what the tool does (used by AI to decide when to use it)
​
parameters
JSONSchema
JSON Schema defining the tool’s parameters
​
execute
function
required
Function that executes the tool’s functionality

​
Built-in Tool Examples

​
File System Tools

const fileSystemTools = [
  {
    name: 'readFile',
    description: 'Read the contents of a file',
    parameters: {
      type: 'object',
      properties: {
        path: { type: 'string', description: 'File path to read' }
      },
      required: ['path']
    },
    execute: async ({ path }) => {
      const fs = require('fs').promises;
      return await fs.readFile(path, 'utf8');
    }
  },
  {
    name: 'writeFile',
    description: 'Write content to a file',
    parameters: {
      type: 'object',
      properties: {
        path: { type: 'string', description: 'File path to write' },
        content: { type: 'string', description: 'Content to write' }
      },
      required: ['path', 'content']
    },
    execute: async ({ path, content }) => {
      const fs = require('fs').promises;
      await fs.writeFile(path, content, 'utf8');
      return 'File written successfully';
    }
  }
];

​
API Integration Tools

const apiTools = [
  {
    name: 'httpRequest',
    description: 'Make an HTTP request to an API',
    parameters: {
      type: 'object',
      properties: {
        url: { type: 'string', description: 'URL to request' },
        method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'DELETE'], default: 'GET' },
        headers: { type: 'object', description: 'Request headers' },
        body: { type: 'string', description: 'Request body' }
      },
      required: ['url']
    },
    execute: async ({ url, method = 'GET', headers = {}, body }) => {
      const fetch = require('node-fetch');
      const response = await fetch(url, {
        method,
        headers,
        body: body ? JSON.stringify(body) : undefined
      });
      return await response.json();
    }
  }
];

​
Database Tools

const databaseTools = [
  {
    name: 'queryDatabase',
    description: 'Execute a SQL query on the database',
    parameters: {
      type: 'object',
      properties: {
        query: { type: 'string', description: 'SQL query to execute' },
        params: { type: 'array', description: 'Query parameters' }
      },
      required: ['query']
    },
    execute: async ({ query, params = [] }) => {
      // Implement database query logic
      // This is a placeholder - use your actual database client
      console.log('Executing query:', query, 'with params:', params);
      return { rows: [], rowCount: 0 };
    }
  }
];

​
Agent Specializations

​
Code Assistant Agent

function createCodeAssistant() {
  return new Agent({
    name: 'Code Assistant',
    description: 'An AI agent that helps with software development',
    systemPrompt: `You are an expert software developer. You can help with:
                   - Writing and reviewing code
                   - Debugging issues
                   - Explaining programming concepts
                   - Suggesting best practices
                   
                   Always provide clear explanations and working code examples.`,
    tools: [
      {
        name: 'analyzeCode',
        description: 'Analyze code for potential issues and improvements',
        parameters: {
          type: 'object',
          properties: {
            code: { type: 'string', description: 'Code to analyze' },
            language: { type: 'string', description: 'Programming language' }
          },
          required: ['code']
        },
        execute: ({ code, language = 'javascript' }) => {
          // Implement code analysis logic
          return {
            issues: [],
            suggestions: [],
            complexity: 'medium'
          };
        }
      },
      {
        name: 'formatCode',
        description: 'Format code according to best practices',
        parameters: {
          type: 'object',
          properties: {
            code: { type: 'string', description: 'Code to format' },
            language: { type: 'string', description: 'Programming language' }
          },
          required: ['code']
        },
        execute: ({ code, language }) => {
          // Implement code formatting logic
          return code; // Placeholder
        }
      }
    ],
    chat,
    memory
  });
}

​
Research Agent

function createResearchAgent() {
  return new Agent({
    name: 'Research Agent',
    description: 'An AI agent specialized in research and information gathering',
    systemPrompt: `You are a thorough research assistant. Your goals are to:
                   - Find accurate and up-to-date information
                   - Analyze and synthesize findings
                   - Provide well-sourced conclusions
                   - Store research for future reference`,
    tools: [
      {
        name: 'searchAcademicPapers',
        description: 'Search for academic papers on a topic',
        execute: async ({ topic }) => {
          // Implement academic search
          return [];
        }
      },
      {
        name: 'summarizeFindings',
        description: 'Summarize research findings',
        execute: ({ findings }) => {
          // Implement summarization
          return 'Summary of findings';
        }
      }
    ],
    chat,
    memory,
    maxIterations: 20
  });
}

​
Error Handling

try {
  const agent = new Agent({
    name: 'Test Agent',
    description: 'A test agent',
    tools: [
      {
        name: 'faultyTool',
        description: 'A tool that might fail',
        execute: () => {
          throw new Error('Tool execution failed');
        }
      }
    ],
    chat,
    memory
  });
} catch (error) {
  console.error('Failed to create agent:', error.message);
}

​
Best Practices

​
Tool Design

  1. Clear descriptions: Make tool descriptions specific and actionable
  2. Proper parameters: Use JSON Schema to define clear parameter requirements
  3. Error handling: Implement proper error handling in tool execution
  4. Async operations: Use async/await for tools that perform I/O operations

​
Agent Configuration

  1. Focused purpose: Give agents specific, well-defined roles
  2. Appropriate limits: Set reasonable maxIterations and timeout values
  3. Memory integration: Use memory for persistent state and learning
  4. Tool selection: Only include tools relevant to the agent’s purpose