> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript AI Agents Framework

> A production-ready Multi AI Agents framework for TypeScript

PraisonAI is a production-ready Multi AI Agents framework for TypeScript, designed to create AI Agents to automate and solve problems ranging from simple tasks to complex challenges. It provides a low-code solution to streamline the building and management of multi-agent LLM systems, emphasising simplicity, customisation, and effective human-agent collaboration.

> [!NOTE]
>
> **Supported runtimes:** The TypeScript SDK runs in any JavaScript runtime — Node, Bun, Deno, browser bundles, Tauri, React Native, Cloudflare Workers. Pass the API key through the `Agent` config on runtimes that lack `process.env`. See [Browser & Mobile Runtimes](https://praison.ai/docs/docs/js/browser-runtime) for the patterns.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    %% Define the main flow
    Start([▶ Start]) --> Agent1
    Agent1 --> Process[⚙ Process]
    Process --> Agent2
    Agent2 --> Output([✓ Output])
    Process -.-> Agent1
    
    %% Define subgraphs for agents and their tasks
    subgraph Agent1[ ]
        Task1[📋 Task]
        AgentIcon1[🤖 AI Agent]
        Tools1[🔧 Tools]
        
        Task1 --- AgentIcon1
        AgentIcon1 --- Tools1
    end
    
    subgraph Agent2[ ]
        Task2[📋 Task]
        AgentIcon2[🤖 AI Agent]
        Tools2[🔧 Tools]
        
        Task2 --- AgentIcon2
        AgentIcon2 --- Tools2
    end

    classDef input fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef tools fill:#2E8B57,stroke:#7C90A0,color:#fff
    classDef transparent fill:none,stroke:none

    class Start,Output,Task1,Task2 input
    class Process,AgentIcon1,AgentIcon2 process
    class Tools1,Tools2 tools
    class Agent1,Agent2 transparent
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff
```

> [tab] TypeScript
>
> ## Quick Start
>
> **1. Simple Usage**
>
> ```bash npm theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> npm install praisonai@latest
> ```
>
> ```bash yarn theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> yarn add praisonai@latest
> ```
>
> > [!NOTE]
> >
> > As of **v1.7.4**, praisonai requires **Node.js 18 or later** (`openai@4` needs Node 18+). Importing the package no longer requires `OPENAI_API_KEY` — the key is only checked when an OpenAI client is created, so Anthropic and Google users can `import { Agent } from 'praisonai'` without one.
> >
> > **v-next (from PR #4416):** `praisonai-ts` no longer runs `dotenv.config()` on import, and no longer reads `process.env.LOGLEVEL` at import. The package is safe to import in any JavaScript runtime (browser, Electron renderer, webview, React Native). If you relied on the automatic `.env` load, install `dotenv` yourself and call `dotenv.config()` at the top of your entrypoint — see [JS Import Safety & Runtimes](https://praison.ai/docs/features/js-import-safety.md).
>
> > [!NOTE]
> >
> > **Building for mobile or a webview (Tauri, Electron renderer, React Native, iOS/Android WebView)?** Import from the `praisonai/mobile` entry:
> >
> > ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> > import { Agent } from 'praisonai/mobile';
> > ```
> >
> > The package root is not webview-safe by design (it re-exports the CLI and MCP server). See [Browser & Webview Runtimes](https://praison.ai/docs/js/browser-runtimes.md).
>
> **2. With Configuration**
>
> ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> export OPENAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxx
> ```
>
> **3. Create File**
>
> Create `app.ts` file
>
> ## Code Example
>
> ```javascript Single Agent theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> import { Agent } from 'praisonai';
>
> const agent = new Agent({ 
>   instructions: `You are a creative writer who writes short stories with emojis.`,
>   name: "StoryWriter"
> });
>
> agent.start("Write a story about a time traveler")
> ```
>
> ```javascript Multi Agents theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> import { Agent, AgentTeam } from 'praisonai';
>
> const storyAgent = new Agent({
>   instructions: "Generate a very short story (2-3 sentences) about artificial intelligence with emojis.",
>   name: "StoryAgent"
> });
>
> const summaryAgent = new Agent({
>   instructions: "Summarize the provided AI story in one sentence with emojis.",
>   name: "SummaryAgent"
> });
>
> const agents = new AgentTeam({
>   agents: [storyAgent, summaryAgent]
> });
>
> agents.start()
> ```
>
> **4. Run Script**
>
> ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> npx ts-node app.ts
> ```

> [!NOTE]
>
> **Source & contributing:** the TypeScript/JavaScript SDK is developed in [`MervinPraison/PraisonAI`](https://github.com/MervinPraison/PraisonAI) at `src/praisonai-ts/`. The [`praisonai-js`](https://github.com/MervinPraison/praisonai-js) repo is only the npm mirror — file issues and PRs against the main monorepo. See [Contributing](https://praison.ai/docs/contributing.md).

## Usage Examples

> [accordion] Single Agent Example
>
> Create and run a single agent to perform a specific task:
>
> ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> import { Agent } from 'praisonai';
>
> // Single agent example - Science Explainer
> const agent = new Agent({ 
>   instructions: `You are a science expert who explains complex phenomena in simple terms.
> Provide clear, accurate, and easy-to-understand explanations.`,
>   name: "ScienceExplainer",
>   verbose: true
> });
>
> agent.start("Why is the sky blue?")
>   .then(response => {
>     console.log('\nExplanation:');
>     console.log(response);
>   })
>   .catch(error => {
>     console.error('Error:', error);
>   });
>
> ```

> [accordion] Multi-Agent Example
>
> Create and run multiple agents working together:
>
> ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> import { Agent, AgentTeam } from 'praisonai';
>
> // Create story agent
> const storyAgent = new Agent({
>   instructions: "You are a storyteller. Write a very short story (2-3 sentences) about a given topic.",
>   name: "StoryAgent",
>   verbose: true
> });
>
> // Create summary agent
> const summaryAgent = new Agent({
>   instructions: "You are an editor. Create a one-sentence summary of the given story.",
>   name: "SummaryAgent",
>   verbose: true
> });
>
> // Create and start agents
> const agents = new AgentTeam({
>   agents: [storyAgent, summaryAgent],
>   tasks: [
>     "Write a short story about a cat",
>     "{previous_result}"  // This will be replaced with the story
>   ],
>   verbose: true
> });
>
> agents.start()
>   .then(results => {
>     console.log('\nStory:', results[0]);
>     console.log('\nSummary:', results[1]);
>   })
>   .catch(error => console.error('Error:', error));
> ```

> [accordion] Task-Based Agent Example
>
> Create agents with specific tasks and dependencies:
>
> ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> import { Agent, AgentTeam } from 'praisonai';
>
> // Create recipe agent
> const recipeAgent = new Agent({
>   instructions: `You are a professional chef and nutritionist. Create 5 healthy food recipes that are both nutritious and delicious.
> Each recipe should include:
> 1. Recipe name
> 2. List of ingredients with quantities
> 3. Step-by-step cooking instructions
> 4. Nutritional information
> 5. Health benefits
>
> Format your response in markdown.`,
>   name: "RecipeAgent",
>   verbose: true
> });
>
> // Create blog agent
> const blogAgent = new Agent({
>   instructions: `You are a food and health blogger. Write an engaging blog post about the provided recipes.
> The blog post should:
> 1. Have an engaging title
> 2. Include an introduction about healthy eating
> 3. Discuss each recipe and its unique health benefits
> 4. Include tips for meal planning and preparation
> 5. End with a conclusion encouraging healthy eating habits
>
> Here are the recipes to write about:
> {previous_result}
>
> Format your response in markdown.`,
>   name: "BlogAgent",
>   verbose: true
> });
>
> // Create Agents instance with tasks
> const agents = new AgentTeam({
>   agents: [recipeAgent, blogAgent],
>   tasks: [
>     "Create 5 healthy and delicious recipes",
>     "Write a blog post about the recipes"
>   ],
>   verbose: true
> });
>
> // Start the agents
> agents.start()
>   .then(results => {
>     console.log('\nFinal Results:');
>     console.log('\nRecipe Task Results:');
>     console.log(results[0]);
>     console.log('\nBlog Task Results:');
>     console.log(results[1]);
>   })
>   .catch(error => {
>     console.error('Error:', error);
>   });
>
> ```

## Running the Examples

**1. Set Environment Variables**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export OPENAI_API_KEY='your-api-key'
```

**2. Create Example File**

Create a new TypeScript file (e.g., `app.ts`) with any of the above examples.

**3. Run the Example**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
npx ts-node app.ts
```

## Tool Calls Examples

> [accordion] Direct Function Tools
>
> Create an agent with directly registered function tools:
>
> ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> import { Agent } from 'praisonai';
>
> async function getWeather(location: string) {
>   console.log(`Getting weather for ${location}...`);
>   return `${Math.floor(Math.random() * 30)}°C`;
> }
>
> async function getTime(location: string) {
>   console.log(`Getting time for ${location}...`);
>   const now = new Date();
>   return `${now.getHours()}:${now.getMinutes()}`;
> }
>
> const agent = new Agent({ 
>   instructions: `You provide the current weather and time for requested locations.`,
>   name: "DirectFunctionAgent",
>   tools: [getWeather, getTime]
> });
>
> agent.start("What's the weather and time in Paris, France and Tokyo, Japan?");
> ```

## Package Structure

PraisonAI ships two entry points from one package.

* `praisonai` — the full framework: agents, tools, MCP, CLI, and everything else. Import this in Node and server builds.
* `praisonai/mobile` — a webview-safe subpath export (\~77 kB bundle). Import `Agent` and its types from here in phone, browser, or Tauri builds. See [Mobile Entry](https://praison.ai/docs/js/mobile-entry.md) for details.

## Parity Notices

A few Python names resolve differently in the TypeScript SDK. Reach for the runtime entry point below.

| Python name | In TypeScript | Use instead |
| - | - | - |
| `LLM` | Type only — no runtime constructor. `new LLM()` throws. | Configure the model on the agent: `new Agent({ llm: 'gpt-4o' })`. |
| `Task` | Workflow-step class (`{ name, execute }`). | Pass a plain task object or string to `Team` — see [Tasks](https://praison.ai/docs/js/tasks.md). |
| `FunctionTool` | Not user-constructible. | Wrap a function with `tool(fn)` — see [Custom Tools](https://praison.ai/docs/js/customtools.md). |

> [!NOTE]
>
> Some Python methods on `Agent`, `Team`, and `Session` have no TypeScript counterpart yet. The pages below flag the gaps; the full list lives in the SDK [parity baseline](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai/praisonai/_dev/parity/signatures/inventory-baseline.json).

## Related

> [card] [TypeScript Async](https://praison.ai/docs/js/typescript-async.md)
>
> TypeScript Async overview

> [card] [Mobile Entry](https://praison.ai/docs/js/mobile-entry.md)
>
> Webview-safe bundle from praisonai/mobile

> [card] [Agent](https://praison.ai/docs/js/agent.md)
>
> Agent overview

> [card] [Browser & Mobile](https://praison.ai/docs/docs/js/browser-runtime)
>
> Run in Tauri, React Native, browser, and edge runtimes


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.