Configuration

Constructor parameters

The ExuluAgent constructor accepts a configuration object with the following parameters:

const agent = new ExuluAgent({
  id: string,
  name: string,
  type: "agent",
  description: string,
  provider: string,
  config?: ExuluAgentConfig,
  capabilities?: Capabilities,
  maxContextLength?: number,
  authenticationInformation?: string,
  queue?: ExuluQueueConfig,
  workflows?: WorkflowConfig,
  rateLimit?: RateLimiterRule
});

Required parameters

id

string

required

Unique identifier for the agent. Must start with a letter or underscore, contain only alphanumeric characters and underscores, 5-80 characters long.

id: "customer_support_agent"

The ID should not change after creation as it’s used for database references and routing.

name

string

required

Human-readable name displayed in UI and logs

name: "Customer Support Agent"

type

'agent'

required

Must be set to "agent"

type: "agent"

description

string

required

Description of what the agent does. Used when the agent is called as a tool by other agents.

description: "Handles customer support inquiries and provides product information"

provider

string

required

LLM provider name (e.g., “openai”, “anthropic”, “google”)

provider: "openai"

Optional parameters

config

ExuluAgentConfig

Configuration object containing model details and instructions

config: {
  name: "gpt-4o",
  model: {
    create: ({ apiKey }) => createOpenAI({ apiKey })("gpt-4o")
  },
  instructions: "You are a helpful assistant..."
}

Config properties

config.name

string

Model name (e.g., “gpt-4o”, “claude-opus-4”)

config.model

ModelFactory

Factory function that creates a LanguageModel instance from the AI SDK

model: {
  create: ({ apiKey }: { apiKey?: string }) => LanguageModel
}

config.instructions

string

System instructions that define the agent’s behavior, personality, and capabilities

instructions: `You are a customer support agent for Acme Corp.

Guidelines:
- Be friendly and professional
- Answer questions clearly and concisely
- Escalate complex technical issues to engineering
- Always verify customer identity for account changes

Company information:
- Founded in 2020
- 10,000+ customers worldwide
- 24/7 support available`

Instructions are critical for agent performance. Include guidelines, examples, company information, and edge cases to handle.

capabilities

Capabilities

Define what types of input the agent can process

capabilities: {
  text: boolean,
  images: imageTypes[],
  files: fileTypes[],
  audio: audioTypes[],
  video: videoTypes[]
}

Capability types

type imageTypes = '.png' | '.jpg' | '.jpeg' | '.gif' | '.webp';
type fileTypes = '.pdf' | '.docx' | '.xlsx' | '.xls' | '.csv' |
                 '.pptx' | '.ppt' | '.txt' | '.md' | '.json';
type audioTypes = '.mp3' | '.wav' | '.m4a' | '.mp4' | '.mpeg';
type videoTypes = '.mp4' | '.m4a' | '.mp3' | '.mpeg' | '.wav';

Example:

capabilities: {
  text: true,
  images: [".png", ".jpg", ".jpeg"],
  files: [".pdf", ".docx", ".txt"],
  audio: [],
  video: []
}

maxContextLength

number

Maximum number of tokens in the conversation context

maxContextLength: 128000 // GPT-4o context window

authenticationInformation

string

Authentication details for API access

authenticationInformation: "Use OPENAI_API_KEY environment variable"

queue

ExuluQueueConfig

Queue configuration for background job processing

queue: await ExuluQueues.register("agent_queue")

workflows

WorkflowConfig

Enable background workflow processing

workflows: {
  enabled: true,
  queue: await ExuluQueues.register("workflows")
}

rateLimit

RateLimiterRule

Rate limiting configuration for API access

rateLimit: {
  points: 100,      // Number of requests
  duration: 60,     // Time window in seconds
  blockDuration: 60 // Block duration after exceeding limit
}

Configuration examples

OpenAI agent

import { ExuluAgent } from "@exulu/backend";
import { createOpenAI } from "@ai-sdk/openai";

const gpt4Agent = new ExuluAgent({
  id: "gpt4_assistant",
  name: "GPT-4 Assistant",
  type: "agent",
  description: "General-purpose AI assistant powered by GPT-4",
  provider: "openai",
  config: {
    name: "gpt-4o",
    model: {
      create: ({ apiKey }) => createOpenAI({
        apiKey: apiKey || process.env.OPENAI_API_KEY
      })("gpt-4o")
    },
    instructions: `You are a helpful AI assistant. Answer questions clearly,
    concisely, and accurately. If you don't know something, say so.`
  },
  capabilities: {
    text: true,
    images: [".png", ".jpg", ".jpeg", ".gif", ".webp"],
    files: [".pdf", ".docx", ".txt"],
    audio: [],
    video: []
  },
  maxContextLength: 128000
});

Anthropic Claude agent

import { ExuluAgent } from "@exulu/backend";
import { createAnthropic } from "@ai-sdk/anthropic";

const claudeAgent = new ExuluAgent({
  id: "claude_opus_4",
  name: "Claude Opus 4",
  type: "agent",
  description: "Advanced reasoning agent powered by Claude Opus 4",
  provider: "anthropic",
  config: {
    name: "claude-opus-4-20250514",
    model: {
      create: ({ apiKey }) => createAnthropic({
        apiKey: apiKey || process.env.ANTHROPIC_API_KEY
      })("claude-opus-4-20250514")
    },
    instructions: `You are Claude, an AI assistant created by Anthropic.
    You are thoughtful, nuanced, and detailed in your responses.`
  },
  capabilities: {
    text: true,
    images: [".png", ".jpg", ".jpeg", ".gif", ".webp"],
    files: [".pdf", ".txt"],
    audio: [],
    video: []
  },
  maxContextLength: 200000
});

Google Gemini agent

import { ExuluAgent } from "@exulu/backend";
import { createGoogleGenerativeAI } from "@ai-sdk/google";

const geminiAgent = new ExuluAgent({
  id: "gemini_2_5_pro",
  name: "Gemini 2.5 Pro",
  type: "agent",
  description: "Multi-modal AI agent powered by Google Gemini",
  provider: "google",
  config: {
    name: "gemini-2.5-pro",
    model: {
      create: ({ apiKey }) => createGoogleGenerativeAI({
        apiKey: apiKey || process.env.GOOGLE_API_KEY
      })("gemini-2.5-pro")
    },
    instructions: "You are Gemini, Google's most capable AI model."
  },
  capabilities: {
    text: true,
    images: [".png", ".jpg", ".jpeg", ".gif", ".webp"],
    files: [".pdf", ".docx", ".txt"],
    audio: [".mp3", ".wav"],
    video: [".mp4"]
  },
  maxContextLength: 1000000
});

Specialist agent with memory

import { ExuluAgent } from "@exulu/backend";
import { createOpenAI } from "@ai-sdk/openai";

const supportAgent = new ExuluAgent({
  id: "support_specialist",
  name: "Support Specialist",
  type: "agent",
  description: "Customer support agent with memory of past interactions",
  provider: "openai",
  config: {
    name: "gpt-4o",
    model: {
      create: ({ apiKey }) => createOpenAI({ apiKey })("gpt-4o")
    },
    instructions: `You are a customer support specialist for Acme Corp.

    Guidelines:
    - Always be friendly, patient, and professional
    - Use past conversation history to provide personalized help
    - Verify customer identity before sharing account information
    - Escalate billing issues to the finance team
    - Document all interactions in the memory system

    Product knowledge:
    - Acme Pro: $99/month, includes all features
    - Acme Basic: $29/month, limited to 100 projects
    - All plans include 24/7 support`,
    memory: "customer_interactions" // Context ID for memory
  },
  capabilities: {
    text: true,
    images: [".png", ".jpg"],
    files: [".pdf", ".txt"],
    audio: [],
    video: []
  },
  maxContextLength: 128000
});

When memory is configured, the agent automatically searches relevant past interactions before responding and can create new memory items.

Agent with workflows

import { ExuluAgent, ExuluQueues } from "@exulu/backend";
import { createOpenAI } from "@ai-sdk/openai";

const asyncAgent = new ExuluAgent({
  id: "async_processor",
  name: "Async Processor",
  type: "agent",
  description: "Processes long-running tasks in the background",
  provider: "openai",
  config: {
    name: "gpt-4o-mini",
    model: {
      create: ({ apiKey }) => createOpenAI({ apiKey })("gpt-4o-mini")
    },
    instructions: "Process tasks efficiently and report results."
  },
  capabilities: {
    text: true,
    images: [],
    files: [".pdf", ".docx", ".txt"],
    audio: [],
    video: []
  },
  workflows: {
    enabled: true,
    queue: await ExuluQueues.register("async_agent_queue")
  },
  queue: await ExuluQueues.register("agent_tasks")
});

Data extraction agent

import { ExuluAgent } from "@exulu/backend";
import { createOpenAI } from "@ai-sdk/openai";

const extractorAgent = new ExuluAgent({
  id: "data_extractor",
  name: "Data Extractor",
  type: "agent",
  description: "Extracts structured data from unstructured text",
  provider: "openai",
  config: {
    name: "gpt-4o-mini",
    model: {
      create: ({ apiKey }) => createOpenAI({ apiKey })("gpt-4o-mini")
    },
    instructions: `You extract structured data from text.
    Be precise and only include information that is explicitly stated.
    If information is missing, use null values.`
  },
  capabilities: {
    text: true,
    images: [],
    files: [".pdf", ".docx", ".txt", ".json"],
    audio: [],
    video: []
  },
  maxContextLength: 16000
});

// Use with outputSchema
const result = await extractorAgent.generateSync({
  prompt: "Extract contact info from this email",
  outputSchema: z.object({
    name: z.string(),
    email: z.string().email(),
    phone: z.string().optional(),
    company: z.string().optional()
  })
});

Rate-limited agent

import { ExuluAgent } from "@exulu/backend";
import { createOpenAI } from "@ai-sdk/openai";

const publicAgent = new ExuluAgent({
  id: "public_assistant",
  name: "Public Assistant",
  type: "agent",
  description: "Publicly accessible AI assistant with rate limiting",
  provider: "openai",
  config: {
    name: "gpt-4o-mini",
    model: {
      create: ({ apiKey }) => createOpenAI({ apiKey })("gpt-4o-mini")
    },
    instructions: "You are a helpful assistant for public users."
  },
  capabilities: {
    text: true,
    images: [],
    files: [],
    audio: [],
    video: []
  },
  rateLimit: {
    points: 20,        // 20 requests
    duration: 3600,    // Per hour
    blockDuration: 3600 // Block for 1 hour if exceeded
  }
});

Using default agents

Exulu IMP provides pre-configured agents for all major providers:

import { ExuluDefaultAgents } from "@exulu/backend";

// OpenAI agents
const gpt4o = ExuluDefaultAgents.GPT_4O;
const gpt5 = ExuluDefaultAgents.GPT_5;
const o1 = ExuluDefaultAgents.O1;

// Anthropic agents
const claudeOpus = ExuluDefaultAgents.CLAUDE_OPUS_4;
const claudeSonnet = ExuluDefaultAgents.CLAUDE_SONNET_4_5;

// Google agents
const geminiFlash = ExuluDefaultAgents.GEMINI_2_5_FLASH;
const geminiPro = ExuluDefaultAgents.GEMINI_2_5_PRO;

// Other providers
const llama = ExuluDefaultAgents.LLAMA_3_3;
const deepseek = ExuluDefaultAgents.DEEPSEEK_R1;

// Register with app
const app = new ExuluApp();
await app.create({
  agents: {
    gpt4o,
    claude: claudeOpus,
    gemini: geminiPro
  },
  config: { /* ... */ }
});

Agent instructions best practices

Define clear role and purpose

Start with who the agent is and what it does:

instructions: `You are a financial advisor AI assistant specializing in
personal finance and investment strategy for retail investors.

Your purpose is to:
- Provide educational information about investing
- Help users understand financial concepts
- Suggest strategies based on risk tolerance
- NOT provide specific investment advice or recommendations`

Set behavioral guidelines

Define how the agent should behave:

instructions: `Guidelines:
- Be friendly, patient, and professional
- Ask clarifying questions when requests are ambiguous
- Admit when you don't know something
- Never make up information
- Cite sources when providing factual information
- Break down complex topics into simple explanations`

Provide domain knowledge

Include relevant facts and context:

instructions: `Company information:
- Founded: 2020
- Products: SaaS platform for team collaboration
- Pricing: Basic ($29/mo), Pro ($99/mo), Enterprise (custom)
- Support: 24/7 live chat, email, phone for Pro+
- Headquarters: San Francisco, CA
- Customers: 10,000+ companies in 50 countries`

Handle edge cases

Define behavior for special situations:

instructions: `Edge cases:
- If user asks for personal information, decline politely
- If user is angry or frustrated, remain calm and empathetic
- If technical issue requires engineering, create a support ticket
- If billing question, redirect to finance team
- If medical/legal advice, disclaimer that you're not qualified`

Use examples

Show desired behavior with examples:

instructions: `Example interactions:

User: "How do I reset my password?"
You: "I can help with that! You can reset your password by clicking
'Forgot Password' on the login page. You'll receive an email with
reset instructions within a few minutes. Is there anything specific
you're having trouble with?"

User: "Why is my account not working?"
You: "I'm sorry to hear you're having trouble. To help diagnose the
issue, could you tell me: 1) What error message are you seeing?
2) When did this start? 3) What were you trying to do?"`

Memory configuration

When configuring agent memory, create a dedicated ExuluContext:

import { ExuluContext, ExuluAgent, ExuluEmbedder } from "@exulu/backend";

// Create memory context
const memoryContext = new ExuluContext({
  id: "agent_memory",
  name: "Agent Memory",
  description: "Stores agent conversation history and learnings",
  active: true,
  fields: [
    {
      name: "interaction",
      type: "longtext",
      required: true
    },
    {
      name: "user_id",
      type: "text",
      index: true
    },
    {
      name: "topic",
      type: "text",
      index: true
    }
  ],
  embedder: myEmbedder,
  sources: [],
  configuration: {
    calculateVectors: "onInsert",
    maxRetrievalResults: 10
  }
});

// Configure agent to use memory
const agent = new ExuluAgent({
  id: "assistant_with_memory",
  name: "Assistant with Memory",
  type: "agent",
  description: "AI assistant with long-term memory",
  provider: "openai",
  config: {
    name: "gpt-4o",
    model: { /* ... */ },
    instructions: "You are an assistant with memory of past conversations.",
    memory: "agent_memory" // Reference the context ID
  },
  capabilities: { text: true, images: [], files: [], audio: [], video: [] }
});

Environment variables

Agents typically require API keys from environment variables:

# OpenAI
OPENAI_API_KEY=sk-...

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

# Google
GOOGLE_API_KEY=...

# Security (required for encrypted variables)
NEXTAUTH_SECRET=your-secret-key

Getting started

Core classes

Frontend

GraphQL API

Core Types

Constructor parameters

Required parameters

id

name

type

description

provider

Optional parameters

config

Config properties

capabilities

Capability types

maxContextLength

authenticationInformation

queue

workflows

rateLimit

Configuration examples

OpenAI agent

Anthropic Claude agent

Google Gemini agent

Specialist agent with memory

Agent with workflows

Data extraction agent

Rate-limited agent

Using default agents

Agent instructions best practices

Memory configuration

Environment variables

Next steps

API reference

ExuluTool

Getting started

Core classes

Frontend

GraphQL API

Core Types

​Constructor parameters

​Required parameters

​id

​name

​type

​description

​provider

​Optional parameters

​config

​Config properties

​capabilities

​Capability types

​maxContextLength

​authenticationInformation

​queue

​workflows

​rateLimit

​Configuration examples

​OpenAI agent

​Anthropic Claude agent

​Google Gemini agent

​Specialist agent with memory

​Agent with workflows

​Data extraction agent

​Rate-limited agent

​Using default agents

​Agent instructions best practices

​Memory configuration

​Environment variables

​Next steps

API reference

ExuluTool

Constructor parameters

Required parameters

id

name

type

description

provider

Optional parameters

config

Config properties

capabilities

Capability types

maxContextLength

authenticationInformation

queue

workflows

rateLimit

Configuration examples

OpenAI agent

Anthropic Claude agent

Google Gemini agent

Specialist agent with memory

Agent with workflows

Data extraction agent

Rate-limited agent

Using default agents

Agent instructions best practices

Memory configuration

Environment variables

Next steps