<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/12.2-typescriptjavascript-sdk -->

# TypeScript/JavaScript SDK

- README.md
- src/praisonai/README.md

## Purpose and Scope

This page documents the TypeScript/JavaScript SDK for PraisonAI, which provides a JavaScript interface for creating and running AI agents. The SDK is a lightweight wrapper that enables Node.js and JavaScript/TypeScript developers to use PraisonAI's agent capabilities programmatically.

For Python-based agent development with the full feature set, see [Python API Reference](/MervinPraison/PraisonAI/12.1-python-api-reference). For CLI usage without coding, see [CLI Interface](/MervinPraison/PraisonAI/7.1-cli-interface).

**Note:** The JavaScript SDK currently provides basic agent functionality. Many advanced features documented in the Python SDK (workflows, memory, planning, etc.) are primarily available through the Python API or CLI.

## Installation and Setup

### Package Installation

The PraisonAI JavaScript SDK is available as an npm package:

```

```

**Sources:** [README.md188-192](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L188-L192) [README.md2345-2358](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L2345-L2358)

### Environment Configuration

The SDK requires an LLM provider API key to function. Set the appropriate environment variable before using the SDK:

```

```

For local model usage with Ollama:

```

```

**Sources:** [README.md194-216](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L194-L216) [README.md2718-2731](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L2718-L2731)

*At least one LLM provider API key is required.

**Sources:** [README.md194-203](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L194-L203)

## Architecture Overview

### JavaScript SDK in the PraisonAI Ecosystem

```

```

**Architecture Notes:**

The JavaScript SDK acts as a wrapper layer that interfaces with the Python-based PraisonAI core. When you create an `Agent` in JavaScript and call `start()`, the SDK communicates with the underlying Python implementation which handles:

- LLM provider communication via LiteLLM
- Tool execution and management
- Agent state and lifecycle
- Output generation and formatting

**Sources:** [README.md2345-2358](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L2345-L2358) [README.md1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L1-L47)

## Agent Class

### Basic Usage

The primary interface in the JavaScript SDK is the `Agent` class:

```

```

**Sources:** [README.md2345-2358](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L2345-L2358)

### Agent Constructor Options

Based on the example provided, the `Agent` constructor accepts a configuration object:

```

```

**Note:** The full parameter set for the JavaScript SDK is not extensively documented. The Python SDK supports many additional parameters (name, role, goal, tools, memory, etc.) which may or may not be available in the JavaScript wrapper.

**Sources:** [README.md2352-2356](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L2352-L2356)

### Agent Methods

#### start(prompt)

Executes the agent with a given prompt:

```

```

**Returns:** The method's return type is not documented in the available sources.

**Sources:** [README.md2356](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L2356-L2356)

## Basic Agent Flow

```

```

**Sources:** [README.md2345-2358](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L2345-L2358)

## Complete Example

### Single Agent Example

This is the primary documented example for the JavaScript SDK:

```

```

**Expected Output:** The agent will generate a response based on the provided prompt, using the configured LLM provider.

**Sources:** [README.md2345-2358](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L2345-L2358)

### With Environment Configuration

```

```

**Sources:** [README.md2345-2358](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L2345-L2358) [README.md206-216](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L206-L216)

## Comparison: JavaScript SDK vs Python SDK

The JavaScript SDK provides a simplified interface compared to the full-featured Python SDK:

**Legend:**

- ok = Documented and available
- ? = Not documented (may or may not be available)

For advanced features, developers should use the Python SDK ([Python API Reference](/MervinPraison/PraisonAI/12.1-python-api-reference)) or the CLI ([CLI Interface](/MervinPraison/PraisonAI/7.1-cli-interface)).

**Sources:** [README.md2345-2358](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L2345-L2358) [README.md520-1524](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L520-L1524)

## Feature Parity Diagram

```

```

The JavaScript SDK currently provides documented access to basic agent functionality. Many advanced features available in the Python SDK are not documented for JavaScript usage.

**Sources:** [README.md2345-2358](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L2345-L2358) [README.md220-479](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L220-L479)

## Provider Configuration

### Supported LLM Providers

The JavaScript SDK inherits provider support from the underlying Python implementation, which supports 100+ LLM providers through LiteLLM integration:

**Sources:** [README.md482-516](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L482-L516)

### Provider Configuration Examples

```

```

**Sources:** [README.md2718-2731](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L2718-L2731) [README.md206-216](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L206-L216)

## Limitations and Considerations

### Current SDK State

Based on the available documentation:

1. Minimal Documentation : Only basic Agent creation and start() method are documented
2. Feature Coverage Unknown : Advanced features (workflows, memory, planning, tools) are not documented for JavaScript
3. API Surface : The full JavaScript API surface is not documented
4. Type Definitions : No TypeScript type definitions are referenced in the documentation
5. Async Support : Return types and async/await patterns are not documented

**Sources:** [README.md2345-2358](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L2345-L2358)

### Alternative Approaches

For TypeScript/JavaScript developers needing advanced features:

```

```

**Recommended Approaches:**

1. For basic agent tasks : Use the JavaScript SDK as documented
2. For advanced features : Use the Python SDK directly
3. For integration without Python : Call the CLI from Node.js using child_process
4. For microservices : Use the REST API server if deployed ( API Server Launch )

**Sources:** [README.md2345-2358](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L2345-L2358) [README.md1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L1-L47)

## Troubleshooting

### Common Issues

### Debug Checklist

```

```

**Sources:** [README.md2345-2358](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L2345-L2358) [README.md194-216](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L194-L216)

## Migration from Python SDK

If you have existing Python code and want to use JavaScript:

### Python to JavaScript Mapping

```

```

```

```

**Key Differences:**

1. Import syntax : from X import Y (Python) -> const { Y } = require('X') (JavaScript)
2. Object syntax : Agent(param=value) (Python) -> new Agent({ param: value }) (JavaScript)
3. String quotes : Python allows single or double; JavaScript typically uses single quotes

**Note:** This mapping only applies to the documented basic functionality. Advanced Python SDK features may not have JavaScript equivalents.

**Sources:** [README.md524-534](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L524-L534) [README.md2345-2358](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L2345-L2358)

## SDK Code Structure

### Exported Classes and Functions

Based on the documented examples, the SDK exports at minimum:

```

```

**Confirmed Exports:**

- Agent - Main agent class for creating and running agents

**Potential Exports (not documented):**
The Python SDK exports many other classes that may or may not be available in JavaScript:

- Agents - Multi-agent orchestration
- Workflow - Workflow management
- Task - Task definition
- tool - Tool decorator
- BaseTool - Base tool class
- MCP - Model Context Protocol client
- Various specialized agents (DeepResearchAgent, QueryRewriterAgent, etc.)

**Sources:** [README.md2352-2356](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L2352-L2356) [README.md540-546](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L540-L546)

## Future Development

### Expected SDK Evolution

As the JavaScript SDK matures, we can expect:

1. TypeScript Type Definitions : Full TypeScript support with .d.ts files
2. Multi-Agent Support : Equivalent to Python's Agents class
3. Workflow API : JavaScript interface for workflow patterns
4. Tool System : Custom tool creation and registration
5. Memory Integration : Persistent memory for agents
6. Async/Promise API : Proper async/await support
7. Comprehensive Documentation : Full API reference

### Contributing

Developers interested in expanding the JavaScript SDK can:

1. Reference the Python SDK implementation: praisonai-agents/
2. Review the Python API documentation: Python API Reference
3. Contribute via the GitHub repository: https://github.com/MervinPraison/PraisonAI

**Sources:** [README.md1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L1-L47)

## Related Documentation

- Python API Reference ( #12.1 ) - Full-featured Python SDK with all capabilities
- CLI Interface ( #7.1 ) - Command-line usage without coding
- Agent Class ( #2.1 ) - Deep dive into agent architecture (Python-focused)
- Installation ( #1.3 ) - General installation and setup
- API Server Launch ( #9.4 ) - REST API server for language-agnostic integration

**Sources:** [README.md1-2800](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L1-L2800)

## Summary

The PraisonAI JavaScript SDK provides a basic interface for creating and executing AI agents in Node.js environments. Currently, the SDK documentation covers:

- Installation via npm
- Basic Agent class creation
- Single-method execution via start()
- Environment variable configuration

For production use cases requiring advanced features (multi-agent systems, workflows, memory, planning, tools), developers should use:

- The Python SDK for full programmatic control ( #12.1 )
- The CLI for no-code automation ( #7.1 )
- The REST API for language-agnostic integration ( #9.4 )

**Sources:** [README.md2345-2358](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L2345-L2358) [README.md74-79](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L74-L79) [README.md188-192](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L188-L192)
