Quick Start

Create your first PraisonAI agent in minutes — install, set an API key, run agent.start(), and scale to teams, tools, and production workflows.

Create an Agent, set one API key, and run it in three lines of code.

python

from praisonaiagents import Agent

agent = Agent(instructions="Summarise Photosynthesis")
agent.start()

Diagram

The fastest way to get the CLI is the one-line installer (isolated managed env, PATH wired for you):

bash

curl -fsSL https://raw.githubusercontent.com/MervinPraison/PraisonAI/main/install.sh | sh

Pick the provider whose key you already have — PraisonAI selects the matching model automatically.

Diagram

Basic

Code

Install Package
Install the PraisonAI Agents package:
bash
```
pip install praisonaiagents
```
Set API Key
Set the key for whichever provider you use — PraisonAI picks the right model automatically:
OpenAI
bash
```
export OPENAI_API_KEY="${OPENAI_API_KEY:?Set OPENAI_API_KEY in your shell}"
praisonai "hello"
```
Anthropic
bash
```
export ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY:?Set ANTHROPIC_API_KEY in your shell}"
praisonai "hello"
```
Gemini
bash
```
export GEMINI_API_KEY="${GEMINI_API_KEY:?Set GEMINI_API_KEY in your shell}"
praisonai "hello"
```
Groq
bash
```
export GROQ_API_KEY="${GROQ_API_KEY:?Set GROQ_API_KEY in your shell}"
praisonai "hello"
```
Ollama
bash
```
export OLLAMA_HOST=http://localhost:11434
praisonai "hello"
```
Tip
If Ollama is running on the default 127.0.0.1:11434, you can skip export OLLAMA_HOST entirely — PraisonAI auto-detects it when no cloud key is set. See Keyless local-first fallback.
Note
No --model flag needed — the matching provider’s default model is selected automatically. See Provider Auto-Detection for the full list.

No cloud key at all? If Ollama is running locally, PraisonAI will use it. See Keyless Local-First Run.

Create Agents

Create app.py:

Single Agent

from praisonaiagents import Agent, AgentTeam

# Create a simple agent
summarise_agent = Agent(instructions="Summarise Photosynthesis")

# Run the agent
team = AgentTeam(agents=[summarise_agent])
team.start()

Multiple Agents

from praisonaiagents import Agent, AgentTeam

# Create agents with specific roles
diet_agent = Agent(
    instructions="Give me 5 healthy food recipes",
)

blog_agent = Agent(
    instructions="Write a blog post about the food recipes",
)

# Run multiple agents
team = AgentTeam(agents=[diet_agent, blog_agent])
team.start()

Run Agents
Execute your script:
bash
```
python app.py
```
You’ll see: – Agent initialization – Task execution progress – Final results

Tip
You have successfully CreatedAI Agents and made them work for you!

No Code

Install Package
Install the No Code PraisonAI Package:
bash
```
pip install praisonaiagents
```

Set API Key

bash

export OPENAI_API_KEY="${OPENAI_API_KEY:?Set OPENAI_API_KEY in your shell}"

Create Config

Create agents.yaml:

Single Agent

agents:  # Canonical
  summarise_agent:
    instructions: Summarise Photosynthesis

Multiple Agents

agents:  # Canonical
  diet_agent:
    instructions: Give me 5 healthy food recipes
  blog_agent:
    instructions: Write a blog post about the food recipes

Note

You can automatically create agents.yaml using:

bash

praisonai --init "your task description"

First time? Run praisonai setup to pick a provider and save your API key — --init will print provider guidance if no key is configured.

Run Agents
Execute your config:
bash
```
praisonai agents.yaml
```
Tip
The same --continue, --session, --output, and permission flags documented for praisonai run also work here — praisonai agents.yaml --continue --output json resumes the last session and emits machine-parseable output.

JavaScript

Install Package
bash
```
npm install praisonai
```

Set API Key

bash

export OPENAI_API_KEY="${OPENAI_API_KEY:?Set OPENAI_API_KEY in your shell}"

Create File

Create app.js file

## Code Example

Single Agent

const { Agent } = require('praisonai');
const agent = new Agent({ instructions: 'You are a helpful AI assistant' });
agent.start('Write a movie script about a robot in Mars');

Multi Agents

const { Agent, AgentTeam } = require('praisonai');

const researchAgent = new Agent({ instructions: 'Research about AI' });
const summariseAgent = new Agent({ instructions: 'Summarise research agent\'s findings' });

const team = new AgentTeam({ agents: [researchAgent, summariseAgent] });
team.start();

Run Script
bash
```
node app.js
```

TypeScript

Install Package
npm
```
npm install praisonai
```
yarn
```
yarn add praisonai
```

Set API Key

bash

export OPENAI_API_KEY="${OPENAI_API_KEY:?Set OPENAI_API_KEY in your shell}"

Create File

Create app.ts file

## Code Example

Single Agent

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")

Multi Agents

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 team = new AgentTeam({
  agents: [storyAgent, summaryAgent]
});

team.start()

Run Script
bash
```
npx ts-node app.ts
```

Advanced

Providing Detailed Tasks to Agents (Optional)

Code

Install PraisonAI
Install the core package:
Terminal
```
pip install praisonaiagents
```
Configure Environment
Terminal
```
export OPENAI_API_KEY="${OPENAI_API_KEY:?Set OPENAI_API_KEY in your shell}"
```
Generate your OpenAI API key from OpenAI Use other LLM providers like Ollama, Anthropic, Groq, Google, etc. Please refer to the Models for more information.

Create Agent

Create app.py:

Single Agent

from praisonaiagents import Agent, Task, AgentTeam

# Create an agent
researcher = Agent(
    name="Researcher",
    role="Senior Research Analyst",
    goal="Uncover cutting-edge developments in AI",
    backstory="You are an expert at a technology research group",
    llm="gpt-4o"
)

# Define a task
task = Task(
    name="research_task",
    description="Analyze 2024's AI advancements",
    expected_output="A detailed report",
    agent=researcher
)

# Run the agents
team = AgentTeam(
    agents=[researcher],
    tasks=[task]
)

result = team.start()

Multiple Agents

from praisonaiagents import Agent, Task, AgentTeam

# Create multiple agents
researcher = Agent(
    name="Researcher",
    role="Senior Research Analyst",
    goal="Uncover cutting-edge developments in AI",
    backstory="You are an expert at a technology research group",
    llm="gpt-4o"
)

writer = Agent(
    name="Writer",
    role="Tech Content Strategist",
    goal="Craft compelling content on tech advancements",
    backstory="You are a content strategist",
    llm="gpt-4o"
)

# Define multiple tasks
task1 = Task(
    name="research_task",
    description="Analyze 2024's AI advancements",
    expected_output="A detailed report",
    agent=researcher
)

task2 = Task(
    name="writing_task",
    description="Create a blog post about AI advancements",
    expected_output="A blog post",
    agent=writer
)

# Run with hierarchical process
team = AgentTeam(
    agents=[researcher, writer],
    tasks=[task1, task2],
    process="hierarchical",
    manager_llm="gpt-4o"
)

result = team.start()

Start Agents
Execute your script:
Terminal
```
python app.py
```
You should see: – Agent initialization – Agents progress – Final results – Generated report

No Code

Install No Code PraisonAI
Install the No Code PraisonAI Package:
Terminal
```
pip install praisonai
```
Set API Key
Set your OpenAI API key as an environment variable in your terminal:
Terminal
```
export OPENAI_API_KEY="${OPENAI_API_KEY:?Set OPENAI_API_KEY in your shell}"
```

Create a file

Create a new file agents.yaml with the basic setup:

yaml

framework: praisonai
topic: create movie script about cat in mars
agents:  # Canonical: use 'agents' instead of 'roles'
  scriptwriter:
    instructions:  # Canonical: use 'instructions' instead of 'backstory' Expert in dialogue and script structure, translating concepts into
      scripts.
    goal: Write a movie script about a cat in Mars
    role: Scriptwriter
    tasks:
      scriptwriting_task:
        description: Turn the story concept into a production-ready movie script,
          including dialogue and scene details.
        expected_output: Final movie script with dialogue and scene details.

Note

You can automatically create agents.yaml file using

Terminal

praisonai --init create movie script about cat in mars

First time? Run praisonai setup to pick a provider and save your API key — --init will print provider guidance if no key is configured.

Start Agents
Execute your script:
Terminal
```
praisonai agents.yaml
```

Creating Custom Tool for Agents (Optional)

More information about tools can be found in the Tools section.

Code

Install PraisonAI
Install the core package and duckduckgo_search package:
Terminal
```
pip install praisonai duckduckgo_search
```

Create Tools and Agents

python

from praisonaiagents import Agent, Task, AgentTeam
from duckduckgo_search import DDGS
from typing import List, Dict

# 1. Tool
def internet_search_tool(query: str) -> List[Dict]:
    """
    Perform Internet Search
    """
    results = []
    ddgs = DDGS()
    for result in ddgs.text(keywords=query, max_results=5):
        results.append({
            "title": result.get("title", ""),
            "url": result.get("href", ""),
            "snippet": result.get("body", "")
        })
    return results

# 2. Agent
data_agent = Agent(
    name="DataCollector",
    role="Search Specialist",
    goal="Perform internet searches to collect relevant information.",
    backstory="Expert in finding and organising internet data.",
    tools=[internet_search_tool],
    reflection=False
)

# 3. Tasks
collect_task = Task(
    description="Perform an internet search using the query: 'AI job trends in 2024'. Return results as a list of title, URL, and snippet.",
    expected_output="List of search results with titles, URLs, and snippets.",
    agent=data_agent,
    name="collect_data",
)

# 4. Start Agents
team = AgentTeam(
    agents=[data_agent],
    tasks=[collect_task],
    process="sequential"
)

team.start()

Start Agents
Run your script:
Terminal
```
python app.py
```

No Code

Install PraisonAI
Install the core package and duckduckgo_search package:
Terminal
```
pip install praisonai duckduckgo_search
```

Create Custom Tool

Create a new file tools.py with the following content:

python

from duckduckgo_search import DDGS
from typing import List, Dict

# 1. Tool
def internet_search_tool(query: str) -> List[Dict]:
    """
    Perform Internet Search
    """
    results = []
    ddgs = DDGS()
    for result in ddgs.text(keywords=query, max_results=5):
        results.append({
            "title": result.get("title", ""),
            "url": result.get("href", ""),
            "snippet": result.get("body", "")
        })
    return results

Create Agent

Create a new file agents.yaml with the following content:

yaml

framework: praisonai
topic: create movie script about cat in mars
agents:  # Canonical: use 'agents' instead of 'roles'
  scriptwriter:
    instructions:  # Canonical: use 'instructions' instead of 'backstory' Expert in dialogue and script structure, translating concepts into
      scripts.
    goal: Write a movie script about a cat in Mars
    role: Scriptwriter
    tools:
      - internet_search_tool # <-- Tool assigned to Agent here
    tasks:
      scriptwriting_task:
        description: Turn the story concept into a production-ready movie script,
          including dialogue and scene details.
        expected_output: Final movie script with dialogue and scene details.

Start Agents
Execute your script:
Terminal
```
praisonai agents.yaml
```

How It Works

An Agent takes your instructions, calls the LLM behind the scenes, and returns the result.

Diagram

Best Practices

Set keys in your shell, never inline

Export OPENAI_API_KEY (or your provider’s key) in your shell or a .env file. Never paste the raw string into Agent(llm=...).

Start with the shortest shape

Agent(instructions="…").start() is the shortest working agent. Add name, role, tools, or a full Task only when you need them.

Skip –model on first runs

PraisonAI picks the right default for whichever provider credential you set. See Provider Auto-Detection.

Add tools progressively

Give an agent a plain Python function via tools=[...] when it needs to search, fetch, or compute. Keep tool functions small and typed.

Models

Choose an LLM provider and model.

Tools

Extend agents with functions and integrations.

Quick Start

Basic

Code

OpenAI

Anthropic

Gemini

Groq

Ollama

No Code

JavaScript

TypeScript

Advanced

Providing Detailed Tasks to Agents (Optional)

Code

No Code

Creating Custom Tool for Agents (Optional)

Code

No Code

How It Works

Best Practices

Related