Skip to main content

Agent

The Agent class is the primary entry point for PraisonAI TypeScript SDK. It provides a simple, unified API for creating AI agents with instructions, tools, and optional persistence.

Quickstart

import { Agent } from 'praisonai';

// 3 lines - Hello Agent
const agent = new Agent({ instructions: "You are a helpful assistant" });
const response = await agent.chat("Hello!");
console.log(response);

Installation

npm install praisonai

Basic Usage

Simple Agent

import { Agent } from 'praisonai';

const agent = new Agent({
  instructions: "You are a helpful AI assistant that provides concise answers."
});

const response = await agent.chat("What is the capital of France?");
console.log(response); // "Paris is the capital of France."

Agent with Custom Name

const agent = new Agent({
  name: "ResearchBot",
  instructions: "You are a research assistant specializing in scientific topics."
});

Agent with Model Selection

const agent = new Agent({
  instructions: "You are helpful",
  llm: "gpt-4o-mini"  // or "gpt-4o", "claude-3-sonnet", etc.
});

Agent with Tools

Pass plain JavaScript functions as tools - schemas are auto-generated:
import { Agent } from 'praisonai';

// Define a simple tool function
const getWeather = (city: string) => `Weather in ${city}: 22°C, Sunny`;

const agent = new Agent({
  instructions: "You are a weather assistant. Use the getWeather tool to answer weather questions.",
  tools: [getWeather]
});

const response = await agent.chat("What's the weather in Paris?");
console.log(response); // Uses the tool and responds with weather info

Multiple Tools

const getWeather = (city: string) => `Weather in ${city}: 22°C`;
const getTime = (timezone: string) => `Current time in ${timezone}: 14:30`;
const calculate = (expression: string) => eval(expression).toString();

const agent = new Agent({
  instructions: "You can check weather, time, and do calculations.",
  tools: [getWeather, getTime, calculate]
});

Agent with Persistence

Use the db() factory for easy database setup:
import { Agent, db } from 'praisonai';

const agent = new Agent({
  instructions: "You are a helpful assistant with memory.",
  db: db("sqlite:./conversations.db"),
  sessionId: "user-123"
});

// Conversations are automatically persisted
await agent.chat("My name is Alice");
await agent.chat("What's my name?"); // Remembers: "Your name is Alice"

Database URL Formats

// SQLite
db("sqlite:./data.db")
db("sqlite::memory:")

// PostgreSQL
db("postgres://user:pass@host:5432/dbname")

// Redis
db("redis://localhost:6379")

// In-memory (default)
db("memory:")
db(":memory:")

Agent Configuration

Full Configuration Options

interface SimpleAgentConfig {
  // Required
  instructions: string;           // System prompt / agent instructions
  
  // Optional - Identity
  name?: string;                  // Agent name (auto-generated if not provided)
  
  // Optional - LLM
  llm?: string;                   // Model: "gpt-4o-mini", "claude-3-sonnet", etc.
  
  // Optional - Behavior
  verbose?: boolean;              // Enable logging (default: true)
  pretty?: boolean;               // Pretty output formatting
  markdown?: boolean;             // Markdown in responses (default: true)
  stream?: boolean;               // Streaming responses (default: true)
  
  // Optional - Tools
  tools?: Function[];             // Array of tool functions
  toolFunctions?: Record<string, Function>;  // Named tool implementations
  
  // Optional - Persistence
  db?: DbAdapter;                 // Database adapter for persistence
  sessionId?: string;             // Session ID (auto-generated if not provided)
  runId?: string;                 // Run ID for tracing
  
  // Optional - Advanced Mode (role/goal/backstory)
  role?: string;                  // Agent role
  goal?: string;                  // Agent goal
  backstory?: string;             // Agent backstory
}

Advanced Mode (Role/Goal/Backstory)

For more structured agent definitions:
const agent = new Agent({
  role: "Senior Research Analyst",
  goal: "Analyze market trends and provide investment insights",
  backstory: "You have 20 years of experience in financial markets..."
});

// Equivalent to:
const agent2 = new Agent({
  instructions: `You are a Senior Research Analyst.
Your goal is: Analyze market trends and provide investment insights
Background: You have 20 years of experience in financial markets...`
});

Session Management

const agent = new Agent({
  instructions: "You are helpful",
  sessionId: "custom-session-id"
});

// Get session and run IDs
console.log(agent.getSessionId()); // "custom-session-id"
console.log(agent.getRunId());     // Auto-generated UUID

Methods

chat(prompt: string)

Send a message and get a response:
const response = await agent.chat("Hello!");

start(prompt: string)

Alias for chat():
const response = await agent.start("Begin the task");

execute()

Execute without a new prompt (uses existing context):
const response = await agent.execute();

Environment Variables

# Model selection
OPENAI_MODEL_NAME=gpt-4o-mini
PRAISONAI_MODEL=gpt-4o

# Behavior
PRAISON_VERBOSE=true
PRAISON_PRETTY=true

# API Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...

Examples

Research Agent

const researcher = new Agent({
  name: "Researcher",
  instructions: `You are a research assistant. 
  - Search for information on topics
  - Summarize findings concisely
  - Cite sources when possible`,
  llm: "gpt-4o"
});

const findings = await researcher.chat("Research the latest AI developments in 2024");

Code Assistant

const coder = new Agent({
  name: "CodeHelper",
  instructions: `You are a coding assistant.
  - Write clean, well-documented code
  - Explain your solutions
  - Follow best practices`,
  tools: [runCode, searchDocs]
});

const code = await coder.chat("Write a function to sort an array");

See Also