Documentation Index
Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
Use this file to discover all available pages before exploring further.
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
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.
});
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
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"
// 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