> ## 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 core Agent class for building AI agents in TypeScript

# 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

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
npm install praisonai
```

## Basic Usage

### Simple Agent

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
const agent = new Agent({
  name: "ResearchBot",
  instructions: "You are a research assistant specializing in scientific topics."
});
```

### Agent with Model Selection

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
// 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

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
const response = await agent.chat("Hello!");
```

### start(prompt: string)

Alias for `chat()`:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
const response = await agent.start("Begin the task");
```

### execute()

Execute without a new prompt (uses existing context):

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
const response = await agent.execute();
```

## Environment Variables

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

* [Agents (Multi-Agent)](/docs/js/agents) - Orchestrate multiple agents
* [Workflow](/docs/js/workflows) - Step-based workflows
* [Tools](/docs/js/tools) - Custom tool development
* [Database](/docs/js/database) - Persistence options