> ## 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.

# PraisonAI Agents

> Guide for using PraisonAI Agents framework, a lightweight package for creating and managing AI agents with advanced capabilities

A lightweight package dedicated to creating and managing AI agents with advanced capabilities.

<Note>
  This is now the default framework. Running `praisonai agents.yaml` without any framework flag uses this adapter.
</Note>

<Note>
  Need a framework that isn't listed here? See [Framework Adapter Plugins](/docs/features/framework-adapter-plugins) to register your own via Python entry points.
</Note>

## Installation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonaiagents
export OPENAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxx
```

## Quick Start

<Steps>
  <Step title="Single agent (minimal)">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(instructions="Research the latest AI trends and summarise them")
    result = agent.start()
    print(result)
    ```
  </Step>

  <Step title="Single agent (with prompt)">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="Assistant",
        instructions="You are a helpful research assistant",
    )
    result = agent.start("What are the latest AI developments?")
    print(result)
    ```
  </Step>

  <Step title="Multi-agent workflow">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent, AgentTeam

    research_agent = Agent(instructions="Research about AI trends")
    summary_agent = Agent(instructions="Summarise the research findings")

    agents = AgentTeam(agents=[research_agent, summary_agent])
    result = agents.start()
    print(result)
    ```
  </Step>
</Steps>

### Advanced: With Tasks and Context

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, Task, AgentTeam

# Create agents
researcher = Agent(
    name="Researcher",
    role="Senior Research Analyst",
    goal="Uncover cutting-edge developments in AI and data science",
    backstory="""You are an expert at a technology research group, 
    skilled in identifying trends and analyzing complex data.""",
    llm="gpt-4o"
)

writer = Agent(
    name="Writer",
    role="Tech Content Strategist",
    goal="Craft compelling content on tech advancements",
    backstory="""You are a content strategist known for 
    making complex tech topics interesting and easy to understand.""",
    llm="gpt-4o"
)

# Create tasks
research_task = Task(
    description="Research the latest developments in AI and data science",
    expected_output="A comprehensive report on recent AI trends and breakthroughs",
    agent=researcher
)

writing_task = Task(
    description="Create an engaging blog post about the research findings",
    expected_output="A well-structured blog post explaining AI developments",
    agent=writer,
    context=[research_task]  # This task depends on research_task output
)

# Create and run the agents
agents = AgentTeam(
    agents=[researcher, writer],
    tasks=[research_task, writing_task]
)

result = agents.start()
print(result)
```

## Execution Methods

| Method     | Default Behavior                   | Use Case             |
| ---------- | ---------------------------------- | -------------------- |
| `.start()` | Verbose in TTY (shows Rich panels) | Interactive/beginner |
| `.run()`   | Silent (no output)                 | Production/scripts   |

### Output Control

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Verbose output (default in terminal)
result = agent.start()

# Force silent mode
result = agent.start(output="silent")

# For production scripts, use .run()
result = agent.run()  # Always silent
```

## Agent Configuration

### Core Attributes

* `name`: Agent's identifier
* `role`: Agent's function/expertise
* `goal`: Individual objective
* `backstory`: Context and personality
* `llm`: Language model (default: OpenAI's GPT-4)
* `instructions`: Agent instructions/system prompt
* `tools`: List of tools available to the agent

### Optional Attributes

* `tools`: List of available tools
* `memory`: Enable memory capabilities
* `knowledge`: Knowledge base configuration
* `planning`: Enable planning mode (default: False)
* `reflection`: Enable self-reflection
* `allow_delegation`: ⚠️ Deprecated — use `handoffs=` instead (default: False)
* `handoffs`: List of agents for handoff

## Task Configuration

### Core Attributes

* `description`: Task details
* `expected_output`: Desired outcome
* `agent`: Assigned agent

### Optional Attributes

* `context`: Dependencies on other tasks
* `tools`: Task-specific tools
* `async_execution`: Run asynchronously (default: False)
* `output_file`: Save output to file
* `callback`: Post-task function

## YAML `config:` Block

The PraisonAI adapter supports a top-level `config:` block in YAML that automatically wires InteractiveRuntime (ACP + LSP + agent-centric tools) into the agent execution.

| YAML Key | Type | Default | Effect                                                                                                                                                                               |
| -------- | ---- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `acp`    | bool | `False` | Initializes InteractiveRuntime with ACP enabled. Agent-centric tools are loaded and merged into `tools_dict` before agents start. Runtime is torn down after `team.start()` returns. |
| `lsp`    | bool | `False` | Same as above but with LSP enabled. Can be combined with `acp: true`.                                                                                                                |

The approval mode is read from the `PRAISONAI_APPROVAL_MODE` environment variable (default: `"prompt"`).

### Example: YAML with ACP/LSP

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
framework: praisonai
topic: Refactor the auth module

config:
  acp: true
  lsp: true

roles:
  refactorer:
    role: Code Refactorer
    goal: Tighten auth.py for readability and safety
    backstory: Staff engineer, security-minded.
    tasks:
      refactor:
        description: Refactor the auth module in {topic}
        expected_output: Diff applied via the agent-centric tools.
```

<Info>
  `config.acp` and `config.lsp` only take effect for `framework: praisonai`. Other adapters (`crewai`, `autogen`, `ag2`, `autogen_v4`) ignore them.
</Info>

### AgentOps Integration

When `agentops` is installed, the PraisonAI adapter automatically calls `agentops.end_session("Success")` after agent execution completes. No configuration required.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install agentops
# AgentOps tracking is automatically enabled
```

## Advanced Features

### Tool Integration

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from duckduckgo_search import DDGS

def search_tool(query: str) -> list:
    """
    Perform a web search using DuckDuckGo and return relevant results.

    Args:
        query (str): The search query string to look up information about.

    Returns:
        list: A list of dictionaries containing search results with the following keys:
            - title (str): The title of the search result
            - url (str): The URL of the search result
            - snippet (str): A brief excerpt or description of the search result
    """
    results = []
    ddgs = DDGS()
    for result in ddgs.text(keywords=query, max_results=10):
        results.append({
            "title": result.get("title", ""),
            "url": result.get("href", ""),
            "snippet": result.get("body", ""),
        })
    return results

agent = Agent(
    name="Researcher",
    tools=[search_tool]
)
```

### Custom Callbacks

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
def task_completed(output):
    print(f"Task completed: {output.description}")
    print(f"Output: {output.raw}")

task = Task(
    description="Analysis task",
    callback=task_completed
)
```

## Error Handling

The framework includes built-in error handling for:

* API rate limits
* Token limits
* Task timeouts
* Tool execution failures

## Best Practices

1. **Agent Design**
   * Give clear, specific roles and goals
   * Provide detailed backstories
   * Use appropriate tools for tasks

2. **Task Management**
   * Break complex tasks into subtasks
   * Set clear dependencies
   * Use async execution for independent tasks

3. **Resource Optimization**
   * Enable caching when appropriate
   * Set reasonable max\_iter limits
   * Use rate limiting for API calls

4. **Error Handling**
   * Implement task callbacks
   * Set appropriate timeouts
   * Monitor execution logs

### Parallel Execution (Upcoming)

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
task1 = Task(
    description="Research task 1",
    async_execution=True
)

task2 = Task(
    description="Research task 2",
    async_execution=True
)

final_task = Task(
    description="Compile results",
    context=[task1, task2]  # Waits for both tasks
)
```

### Memory Management (Upcoming)

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent = Agent(
    name="Analyst",
    memory=True,  # Enable memory
    memory={
        "type": "short_term",
        "max_tokens": 4000
    }
)
```

## Troubleshooting

**Unsupported framework error**: If you see `Unsupported framework: praisonai. Registered: ['ag2', 'autogen', 'autogen_v4', 'crewai', 'praisonai']`, check spelling — frameworks are registered via the adapter registry.

**Missing installation error**: If the framework is not installed, PraisonAI now fails fast at CLI entry with:

```
Framework 'praisonai' was requested but is not installed.
Install it with:
    pip install praisonaiagents
```

The error appears **immediately**, before YAML parsing — so a typo in `--framework` is caught before any expensive setup runs.