Agents

An Agent is an AI that follows your instructions, uses tools, and completes tasks through conversation.

from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="You are a helpful research assistant. Answer questions accurately and concisely.",
)

agent.start("What are the main benefits of solar energy?")

The user asks a question; the agent runs a single turn and returns the answer.

Quick Start

Simple Agent

from praisonaiagents import Agent

agent = Agent(instructions="You are a helpful assistant.")
response = agent.start("Explain machine learning in one paragraph.")
print(response)

Agent with Tools

from praisonaiagents import Agent
from praisonaiagents.tools import duckduckgo

agent = Agent(
    name="Researcher",
    instructions="You are a research agent. Use web search for current information.",
    tools=[duckduckgo],
)
agent.start("What are the latest developments in quantum computing?")

Tool failures don’t stop the run. If a tool raises an exception or returns something that isn’t JSON-serializable (datetime, set, bytes, custom classes), the sync and async loops both convert it to {"error": "<message>"} or {"result": "<str(value)>"} and feed it back to the model. agent.start() / agent.chat() continues so the model can recover or apologise (PR #3855).

from praisonaiagents import Agent

def flaky_tool(x: int) -> str:
    if x == 0:
        raise ValueError("bad input")
    return f"got {x}"

agent = Agent(
    name="Resilient",
    instructions="Call flaky_tool, recover from errors, and answer the user.",
    tools=[flaky_tool],
)

# After PR #3855: the error is fed back to the model, and the agent responds.
agent.start("Use flaky_tool with x=0 and tell me what happened.")

Agent with Features

from praisonaiagents import Agent

agent = Agent(
    name="SmartAssistant",
    instructions="You are a smart assistant that remembers and plans.",
    memory=True,
    planning=True,
    reflection=True,
)
agent.start("Help me plan a comprehensive study schedule for learning Python.")

How It Works

Phase	What happens
1. Receive	Agent receives user input
2. Think	LLM decides whether to respond or call a tool
3. Act	If tool needed, executes it and feeds result back
4. Respond	Final answer returned to user

Key Parameters

Parameter	Type	Description
`name`	`str`	Agent name (shown in logs and multi-agent setups)
`instructions`	`str`	System prompt — what the agent does and how
`llm`	`str`	Model name (e.g., `"gpt-4o"`, `"claude-3-5-sonnet"`)
`tools`	`list`	List of tools the agent can use
`memory`	`bool \| MemoryConfig`	Enable conversation memory
`planning`	`bool \| PlanningConfig`	Enable pre-execution planning
`reflection`	`bool \| ReflectionConfig`	Enable self-review of responses
`caching`	`bool \| CachingConfig`	Enable response caching
`output`	`str \| OutputConfig`	Control response verbosity
`execution`	`str \| ExecutionConfig`	Control iteration and budget limits

Common Patterns

Pattern 1 — Simple Q&A agent

from praisonaiagents import Agent

agent = Agent(instructions="Answer questions clearly and accurately.")
response = agent.start("What is the difference between RAM and storage?")
print(response)

Pattern 2 — Specialized domain agent

from praisonaiagents import Agent

agent = Agent(
    name="LegalAnalyst",
    instructions="""You are a legal document analyst.
    Identify key clauses, risks, and obligations.
    Always recommend consulting a qualified attorney.""",
    llm="gpt-4o",
)
agent.start("Analyze this software license agreement for unusual terms.")

Pattern 3 — Fully-featured production agent

from praisonaiagents import Agent, MemoryConfig, ExecutionConfig

agent = Agent(
    name="ProductionAgent",
    instructions="You are a reliable production assistant.",
    memory=MemoryConfig(backend="sqlite", user_id="user_123"),
    execution=ExecutionConfig(max_iter=30, max_budget=0.25),
    caching=True,
)
response = agent.start("Summarize our Q3 performance metrics.")
print(response)

Best Practices

Write clear instructions

The instructions parameter is your agent’s personality and purpose. Be specific: “You are a customer support agent for Acme Corp. Answer questions about orders, returns, and products. Escalate billing disputes to a human.” Clear instructions outperform vague ones every time.

Add features progressively

Start with just Agent(instructions="...") and add features (memory, planning, reflection) one at a time. Each feature has a cost — only add what your use case actually needs.

Use the right model

gpt-4o-mini handles simple Q&A and extraction cheaply and fast. Use gpt-4o or claude-3-5-sonnet for complex reasoning, code generation, and nuanced writing tasks.

Name agents in multi-agent setups

Always set name when using multiple agents. Names appear in logs, hooks callbacks, and help diagnose which agent produced which output in complex workflows.

AgentTeam is the canonical multi-agent class; AgentManager, Agents, and PraisonAIAgents are silent aliases for the same class — see Back-compat class aliases.

Tools — add capabilities like web search and code execution

Memory — give agents persistent memory across sessions

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

How It Works

Key Parameters

Common Patterns

Pattern 1 — Simple Q&A agent

Pattern 2 — Specialized domain agent

Pattern 3 — Fully-featured production agent

Best Practices

​Quick Start

​How It Works

​Key Parameters

​Common Patterns

​Pattern 1 — Simple Q&A agent

​Pattern 2 — Specialized domain agent

​Pattern 3 — Fully-featured production agent

​Best Practices

​Related

Quick Start

How It Works

Key Parameters

Common Patterns

Pattern 1 — Simple Q&A agent

Pattern 2 — Specialized domain agent

Pattern 3 — Fully-featured production agent

Best Practices

Related