> ## 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](/docs/docs/js/browser-runtime) for the patterns.
</Note>

```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
```

<Tabs>
  <Tab title="TypeScript">
    ## Quick Start

    <Steps>
      <Step title="Simple Usage">
        <CodeGroup>
          ```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
          ```
        </CodeGroup>

        <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](/docs/features/js-import-safety).
        </Note>

        <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](/docs/js/browser-runtimes).
        </Note>
      </Step>

      <Step title="With Configuration">
        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        export OPENAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxx
        ```
      </Step>

      <Step title="Create File">
        Create `app.ts` file

        ## Code Example

        <CodeGroup>
          ```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()
          ```
        </CodeGroup>
      </Step>

      <Step title="Run Script">
        ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        npx ts-node app.ts
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

<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](/docs/contributing).
</Note>

## Usage Examples

<AccordionGroup>
  <Accordion title="Single Agent Example" icon="user" defaultOpen>
    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>

  <Accordion title="Multi-Agent Example" icon="users" defaultOpen>
    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>

  <Accordion title="Task-Based Agent Example" icon="list-check" defaultOpen>
    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);
      });

    ```
  </Accordion>
</AccordionGroup>

## Running the Examples

<Steps>
  <Step title="Set Environment Variables">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    export OPENAI_API_KEY='your-api-key'
    ```
  </Step>

  <Step title="Create Example File">
    Create a new TypeScript file (e.g., `app.ts`) with any of the above examples.
  </Step>

  <Step title="Run the Example">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    npx ts-node app.ts
    ```
  </Step>
</Steps>

## Tool Calls Examples

<AccordionGroup>
  <Accordion title="Direct Function Tools" icon="code" defaultOpen>
    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?");
    ```
  </Accordion>
</AccordionGroup>

## 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](/docs/js/mobile-entry) 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](/docs/js/tasks). |
| `FunctionTool` | Not user-constructible.                                 | Wrap a function with `tool(fn)` — see [Custom Tools](/docs/js/customtools). |

<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).
</Note>

## Related

<CardGroup cols={2}>
  <Card title="TypeScript Async" icon="book" href="/docs/js/typescript-async">TypeScript Async overview</Card>
  <Card title="Mobile Entry" icon="mobile" href="/docs/js/mobile-entry">Webview-safe bundle from praisonai/mobile</Card>
  <Card title="Agent" icon="robot" href="/docs/js/agent">Agent overview</Card>
  <Card title="Browser & Mobile" icon="globe" href="/docs/docs/js/browser-runtime">Run in Tauri, React Native, browser, and edge runtimes</Card>
</CardGroup>