<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/2.1-agent-class -->

# Agent Class

- src/praisonai-agents/praisonaiagents/agent/agent.py
- src/praisonai-agents/praisonaiagents/llm/llm.py

The `Agent` class is the foundational building block of the PraisonAI framework. It provides a simple, unified interface for creating AI agents with LLM capabilities, tool access, memory, knowledge retrieval, and safety controls. This page documents the Agent class initialization, configuration parameters, core methods, and request processing lifecycle.

**Related Pages:**

- Specialized Agent Types - Pre-configured agent variants for specific tasks
- LLM Integration - Details on LLM class and provider support
- Task System - Task definition and execution
- Multi-Agent Orchestration - Coordinating multiple agents
- Memory Management - Persistent memory backends
- Tool Integration - Tool system details

## Agent Class Structure

The `Agent` class is implemented in [src/praisonai-agents/praisonaiagents/agent/agent.py155-2453](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L155-L2453) It encapsulates all functionality needed for an autonomous AI agent including LLM interaction, tool execution, memory management, and safety controls.

### Performance-Optimized Architecture

The Agent class employs **lazy loading** throughout to minimize initialization overhead:

- Startup time: ~20ms in silent mode (down from ~420ms with eager loading)
- Heavy dependencies ( rich , display utilities, LLM clients) load only when needed
- Class-level caching for environment variables and model defaults
- Zero overhead for unused features

**Key optimization techniques:**

1. Lazy imports - Display functions loaded only when output=verbose src/praisonai-agents/praisonaiagents/agent/agent.py 16-94
2. Module-level param resolution imports - Lightweight imports moved to module level src/praisonai-agents/praisonaiagents/agent/agent.py 125-135
3. Class-level caching - Environment variables cached once per class src/praisonai-agents/praisonaiagents/agent/agent.py 158-201
4. Lazy property initialization - Hook runners, stream emitters, telemetry initialized on first access src/praisonai-agents/praisonaiagents/agent/agent.py 164-180

### Agent Class Components

```

```

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py155-457](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L155-L457) [src/praisonai-agents/praisonaiagents/agent/agent.py1457-1537](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L1457-L1537) [src/praisonai-agents/praisonaiagents/agent/agent.py1800-2113](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L1800-L2113)

## Initialization and Configuration

The `Agent.__init__()` method follows an **agent-centric API design** using consolidated parameters. Each feature can be configured via simple presets, dictionaries, or config objects.

### Core Identity Parameters

**Note:** At least one of `name`, `role`, `goal`, `backstory`, or `instructions` must be provided.

**Instructions vs. Traditional Parameters:**

- With instructions: Simplified interface - instructions sets goal/backstory, self_reflect defaults to False , name remains None unless explicitly provided
- Traditional mode: Explicit role/goal/backstory with self_reflect=True by default

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py399-406](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L399-L406) [src/praisonai-agents/praisonaiagents/agent/agent.py1108-1137](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L1108-L1137)

### LLM Configuration Parameters

**Model Resolution:**

1. Check model= parameter (preferred)
2. Check llm= parameter (shows deprecation warning)
3. Check OPENAI_MODEL_NAME environment variable (cached at class level)
4. Default to "gpt-4o-mini"

**LLM Instance Creation:**

- With base_url : Always creates custom LLM instance (even if model is string) src/praisonai-agents/praisonaiagents/agent/agent.py 1180-1210
- Dict config: Creates LLM(**dict_config) src/praisonai-agents/praisonaiagents/agent/agent.py 1212-1228
- Provider/model string: Creates LLM(model=llm) for provider-specific models src/praisonai-agents/praisonaiagents/agent/agent.py 1230-1255
- Otherwise: Uses simple string name with OpenAI client (lazy-loaded) src/praisonai-agents/praisonaiagents/agent/agent.py 1257-1258

For provider-specific configuration details, see [LLM Integration](/MervinPraison/PraisonAI/2.3-llm-integration).

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py408-410](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L408-L410) [src/praisonai-agents/praisonaiagents/agent/agent.py1139-1258](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L1139-L1258) [src/praisonai-agents/praisonaiagents/agent/agent.py195-201](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L195-L201)

### Tool Configuration Parameters

For details on tool system and MCP integration, see [Tool Integration](/MervinPraison/PraisonAI/5.1-tool-integration) and [MCP Protocol](/MervinPraison/PraisonAI/5.2-mcp-protocol).

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py414-419](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L414-L419)

### Consolidated Feature Parameters

PraisonAI uses a **unified parameter resolution system** implemented in [src/praisonai-agents/praisonaiagents/config/param_resolver.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/config/param_resolver.py) Each feature follows the precedence:

```
Instance > Config > Array > Dict > String > Bool > Default
```

**Resolution Flow:**

1. Instance check - If value is already a feature instance (e.g., Memory , ContextManager ), passthrough directly
2. Config check - If value is a config object (e.g., MemoryConfig ), extract/convert
3. Array mode - List values processed based on ArrayMode enum (see below)
4. Dict - Create config from dictionary
5. String - Lookup in preset dict or handle URL schemes
6. Bool - True -> defaults, False -> disabled
7. Default - Fallback value

**ArrayMode Enum Options:**

- PASSTHROUGH - Pass list directly (e.g., hooks)
- PRESET_OVERRIDE - Array of presets merged (e.g., output modes)
- SOURCES - List of source paths (e.g., skills directories)
- SOURCES_WITH_CONFIG - Sources + optional config dict (e.g., knowledge)
- SINGLE_OR_LIST - Support both single value and list (e.g., memory backends)

Each consolidated parameter accepts multiple input forms for flexibility with **fast-path optimization** to skip full resolution for common cases.

#### Memory Parameter

**Resolution Flow (Fast Path):**

1. None/False -> No memory, skip resolution src/praisonai-agents/praisonaiagents/agent/agent.py 847-849
2. True -> MemoryConfig() defaults src/praisonai-agents/praisonaiagents/agent/agent.py 850-851
3. MemoryConfig -> Direct passthrough src/praisonai-agents/praisonaiagents/agent/agent.py 852-853
4. Instance check -> Memory or db() instance passthrough src/praisonai-agents/praisonaiagents/agent/agent.py 854-857
5. Complex -> Full resolver with URL scheme support src/praisonai-agents/praisonaiagents/agent/agent.py 859-868

**Available presets:** `file`, `sqlite`, `redis`, `postgres`, `mem0`, `mongodb`, `history`

**Special handling:**

- If learn=True in MemoryConfig , converts to dict to trigger full Memory class initialization src/praisonai-agents/praisonaiagents/agent/agent.py 887-888
- db() instances detected via hasattr(memory, 'database_url') check src/praisonai-agents/praisonaiagents/agent/agent.py 872-875

For memory backend details, see [Memory Management](/MervinPraison/PraisonAI/4.1-memory-management).

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py426](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L426-L426) [src/praisonai-agents/praisonaiagents/agent/agent.py845-900](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L845-L900)

#### Output Parameter

**Available presets:** `silent`, `actions`, `verbose`, `json`, `stream`, `status`, `trace`, `debug`

**Default:** `silent` mode (zero overhead, fastest performance)

**Resolution Flow (Fast Path Optimization):**

1. None (default) -> Check PRAISONAI_OUTPUT env var (cached) -> Default to "silent" src/praisonai-agents/praisonaiagents/agent/agent.py 623-629
2. String preset -> Fast lookup in OUTPUT_PRESETS dict src/praisonai-agents/praisonaiagents/agent/agent.py 634-642
3. File path detection -> String with / , \ , or file extension -> OutputConfig(output_file=path) src/praisonai-agents/praisonaiagents/agent/agent.py 99-119
4. OutputConfig instance -> Direct passthrough src/praisonai-agents/praisonaiagents/agent/agent.py 645-646
5. Complex types -> Full resolver with ArrayMode.PRESET_OVERRIDE src/praisonai-agents/praisonaiagents/agent/agent.py 648-655

**Output Mode Configuration:**

- Status trace mode -> Enables enable_trace_output() with timestamps and duration src/praisonai-agents/praisonaiagents/agent/agent.py 677-685
- Actions trace mode -> Enables enable_status_output() with tool call/response callbacks src/praisonai-agents/praisonaiagents/agent/agent.py 688-703

Controls: `verbose`, `markdown`, `stream`, `metrics`, `reasoning_steps`, `actions_trace`, `status_trace`, `json_output`, `output_file`, `output_template`, `simple_output`

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py435](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L435-L435) [src/praisonai-agents/praisonaiagents/agent/agent.py619-703](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L619-L703)

#### Execution Parameter

**Available presets:** `fast`, `balanced`, `thorough`, `unlimited`

Controls: `max_iter`, `max_rpm`, `max_execution_time`, `max_retry_limit`

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py436](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L436-L436) [src/praisonai-agents/praisonaiagents/agent/agent.py665-694](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L665-L694) [examples/consolidated_params/basic_execution.py1-19](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/examples/consolidated_params/basic_execution.py#L1-L19)

#### Planning Parameter

**Available presets:** `reasoning`, `read_only`, `auto`

For planning system details, see [Planning System](/MervinPraison/PraisonAI/3.3-planning-system).

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py428](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L428-L428) [examples/consolidated_params/basic_planning.py1-19](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/examples/consolidated_params/basic_planning.py#L1-L19)

#### Reflection Parameter

**Available presets:** `minimal`, `standard`, `thorough`

Controls: `self_reflect`, `max_reflect`, `min_reflect`, `reflect_llm`, `reflect_prompt`

For reflection system details, see [Reflection System](/MervinPraison/PraisonAI/3.4-reflection-system).

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py429](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L429-L429) [examples/consolidated_params/basic_reflection.py1-19](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/examples/consolidated_params/basic_reflection.py#L1-L19)

#### Guardrails Parameter

**Available presets:** `strict`, `permissive`, `safety`

Controls: `guardrail`, `max_guardrail_retries`

For guardrails details, see [Guardrails](/MervinPraison/PraisonAI/6.1-guardrails).

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py430](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L430-L430) [examples/consolidated_params/basic_guardrails.py1-22](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/examples/consolidated_params/basic_guardrails.py#L1-L22)

#### Web Parameter

**Available presets:** `duckduckgo`, `tavily`, `google`, `bing`, `serper`

Controls: `web_search`, `web_fetch`

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py431](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L431-L431) [examples/consolidated_params/basic_web.py1-19](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/examples/consolidated_params/basic_web.py#L1-L19)

#### Context Parameter

**Smart Default Logic:**

```

```

[src/praisonai-agents/praisonaiagents/agent/agent.py1437-1442](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L1437-L1442)

**Lazy Initialization:**

- Property context_manager returns None until first access when enabled
- Zero overhead when context=False or context=None with no tools
- Auto-wires LLM summarization function via _create_llm_summarize_fn() src/praisonai-agents/praisonaiagents/agent/agent.py 1637-1680
- Shares session deduplication cache from workflow via _session_dedup_cache src/praisonai-agents/praisonaiagents/agent/agent.py 1577

**ContextConfig -> ManagerConfig Conversion:**
YAML `ContextConfig` converted to `ManagerConfig` with field mapping:

- tool_output_max -> default_tool_output_max
- protected_tools -> list conversion
- Monitor settings extracted from nested monitor object src/praisonai-agents/praisonaiagents/agent/agent.py 1591-1615

For context management details, see [Context Management](/MervinPraison/PraisonAI/4.4-context-management).

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py432](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L432-L432) [src/praisonai-agents/praisonaiagents/agent/agent.py1437-1636](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L1437-L1636)

#### Autonomy Parameter

**Available presets:** `suggest`, `auto_edit`, `full_auto`

For autonomy system details, see [Autonomy and Handoff](/MervinPraison/PraisonAI/2.6-autonomy-and-handoff).

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py433](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L433-L433) [examples/consolidated_params/basic_autonomy.py1-19](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/examples/consolidated_params/basic_autonomy.py#L1-L19)

#### Knowledge Parameter

For knowledge (RAG) system details, see [RAG System](/MervinPraison/PraisonAI/4.3-rag-system).

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py427](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L427-L427) [examples/consolidated_params/basic_knowledge.py1-19](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/examples/consolidated_params/basic_knowledge.py#L1-L19)

#### Caching Parameter

**Available presets:** `enabled`, `disabled`, `prompt`

Controls: `cache`, `prompt_caching`

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py438](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L438-L438) [examples/consolidated_params/basic_caching.py1-24](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/examples/consolidated_params/basic_caching.py#L1-L24)

#### Hooks Parameter

**Valid keys:** `on_step`, `on_tool_call`, `middleware`

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py439](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L439-L439) [examples/consolidated_params/basic_hooks.py1-29](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/examples/consolidated_params/basic_hooks.py#L1-L29)

#### Skills Parameter

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py440](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L440-L440) [src/praisonai-agents/praisonaiagents/agent/agent.py778-802](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L778-L802)

### Session Management Parameters

**History Injection:**
When `memory="history"` preset or `MemoryConfig(history=True)`:

- _history_enabled = True
- _history_limit = 10 (default)
- _history_session_id = auto_save if provided
- Agent auto-injects last N conversation turns into context src/praisonai-agents/praisonaiagents/agent/agent.py 905-917

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py420-421](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L420-L421) [src/praisonai-agents/praisonaiagents/agent/agent.py1168](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L1168-L1168) [src/praisonai-agents/praisonaiagents/agent/agent.py1329](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L1329-L1329)

## Core Methods

The Agent class provides several methods for interaction and execution. Methods are organized by functional area.

### Primary Execution Methods

#### Agent.start()

Main method for executing a prompt with optional structured output. Performs complete task execution including tool calling loop, guardrails, and reflection.

```

```

**Parameters:**

- prompt : Input prompt for the agent
- output_json : Pydantic model for JSON schema-based output (deprecated, use output_pydantic )
- output_pydantic : Pydantic model for structured output validation
- **kwargs : Additional parameters (temperature, tools, etc.)

**Returns:** `TaskOutput` object with attributes:

- description - Original task prompt
- raw - Raw LLM response text
- agent - Reference to executing agent
- output_format - Output format type ( RAW , JSON , PYDANTIC )
- json_dict - Parsed JSON if output_json specified
- pydantic - Parsed Pydantic model if output_pydantic specified

**Execution Flow:**

1. Build system prompt with tools src/praisonai-agents/praisonaiagents/agent/agent.py 2489-2544
2. Initialize messages list
3. Tool execution loop (max 10 iterations) src/praisonai-agents/praisonaiagents/agent/agent.py 2551-2679
4. Apply guardrails with retry src/praisonai-agents/praisonaiagents/agent/agent.py 2689-2712
5. Self-reflection validation loop (if enabled) src/praisonai-agents/praisonaiagents/agent/agent.py 2714-2774
6. Update chat history src/praisonai-agents/praisonaiagents/agent/agent.py 2779-2798
7. Create and return TaskOutput src/praisonai-agents/praisonaiagents/agent/agent.py 2812-2826

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py2452-2826](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L2452-L2826)

#### Agent.chat()

Conversational interface with chat history management. Simplified interface compared to `start()` - returns string response instead of `TaskOutput`.

```

```

**Parameters:**

- prompt : User message
- temperature : Sampling temperature (0.0-2.0)
- tools : Override agent tools for this call (defaults to self.tools )
- output_json : Structured JSON output (deprecated, use output_pydantic )
- output_pydantic : Structured Pydantic output
- reasoning_steps : Enable reasoning step display (OpenAI o1-preview style)
- stream : Enable streaming output (defaults to self.stream )
- **kwargs : Additional LLM parameters

**Returns:** String response from the agent

**Key Differences from start():**

- Returns string directly (not TaskOutput )
- Automatically uses self.chat_history for context
- Thread-safe history updates via _history_lock src/praisonai-agents/praisonaiagents/agent/agent.py 2978-2979
- Invokes _chat_completion() internal method src/praisonai-agents/praisonaiagents/agent/agent.py 2874-3076

**Thread Safety:**
History access protected by lazy-loaded `_history_lock` property [src/praisonai-agents/praisonaiagents/agent/agent.py1470-1475](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L1470-L1475)

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py2828-3076](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L2828-L3076)

#### Agent.run()

Simplified execution method. Wrapper around `start()` that returns string response instead of `TaskOutput`.

```

```

**Returns:** String response (equivalent to `start(prompt, **kwargs).raw`)

**Usage:** Convenient for scripts and simple use cases where `TaskOutput` metadata is not needed.

Sources: [api.md65](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L65-L65)

#### Agent.execute()

Execute a `Task` object with optional context from previous tasks. Used by multi-agent orchestration systems.

```

```

**Parameters:**

- task : Task object to execute (see Task System )
- context : Optional context from previous tasks (string or structured data)

**Returns:** `TaskOutput` object

**Task Execution Flow:**

1. Extract prompt from task.description
2. Combine with context if provided
3. Apply task-specific tools if task.tools specified
4. Call start() with combined prompt
5. Store result in task.output attribute
6. Return TaskOutput

**Context Handling:**

- String context -> Appended to task description
- Structured context -> Converted to string representation
- Used by AgentTeam for sequential task execution with cumulative context

Sources: [api.md38](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L38-L38) [src/praisonai-agents/praisonaiagents/task/task.py](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/task/task.py)

### Autonomous Execution Methods

#### Agent.run_autonomous()

Run agent autonomously with progressive escalation, doom loop detection, and completion promise support.

```

```

**Parameters:**

- prompt : Initial task prompt (re-injected each iteration)
- max_iterations : Override max iterations (default from autonomy_config )
- timeout_seconds : Timeout in seconds (default: no timeout)
- completion_promise : String that signals completion when wrapped in <promise>TEXT</promise> tags
- clear_context : Clear chat history between iterations (forces reliance on external state)

**Returns:** `AutonomyResult` with:

- success - Whether task completed successfully
- output - Final response text
- completion_reason - "promise" , "goal" , "timeout" , "doom_loop" , "max_iterations" , "error"
- iterations - Number of iterations executed
- stage - Execution stage ( "direct" , "heuristic" , "planned" , "autonomous" )
- actions - List of actions taken with iteration/response
- duration_seconds - Total execution time
- error - Error message if failed
- started_at - ISO timestamp

**Execution Stages:**
Automatically determined by analyzing prompt signals [src/praisonai-agents/praisonaiagents/agent/agent.py1861-1875](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L1861-L1875):

1. Direct - Simple query, complete after first response
2. Heuristic - Tool-based, limited iterations
3. Planned - Requires planning, structured approach
4. Autonomous - Complex multi-step, full autonomy

**Doom Loop Detection:**
Tracks repeated actions and prevents infinite loops via `DoomLoopTracker` [src/praisonai-agents/praisonaiagents/agent/agent.py1877-1902](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L1877-L1902)

For full autonomy details, see [Autonomy and Handoff](/MervinPraison/PraisonAI/2.6-autonomy-and-handoff).

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py1904-2113](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L1904-L2113)

### Memory Management Methods

#### Agent.store_memory()

Store content in agent memory.

```

```

Sources: [api.md70](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L70-L70)

#### Agent.get_memory_context()

Retrieve relevant memory context.

```

```

Sources: [api.md45](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L45-L45)

### History Management Methods

Sources: [api.md30-58](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L30-L58)

### Agent-to-Agent Handoff Methods

#### Agent.handoff_to()

Delegate task to another agent.

```

```

For handoff system details, see [Autonomy and Handoff](/MervinPraison/PraisonAI/2.6-autonomy-and-handoff).

Sources: [api.md49](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L49-L49)

### Template-based Creation

#### Agent.from_template()

Create agent from a template URI.

```

```

**Parameters:**

- uri : Template URI (local path, package ref, or GitHub ref) "./my-template" - Local path "transcript-generator" - Default recipes repo "github:owner/repo/template@v1.0.0" - GitHub with version
- config : Optional configuration overrides
- offline : If True, only use cached templates
- **kwargs : Additional Agent constructor arguments

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py217-266](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L217-L266) [api.md41](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L41-L41)

### Tool Execution Methods

#### Agent.execute_tool()

Internal method that executes tools during LLM tool calling loop. Handles multiple tool formats with safety controls.

```

```

**Tool Execution Pipeline:**

```

```

**Tool Discovery Order:**

1. Memory tools - Check _is_memory_tool_call() for Claude Memory src/praisonai-agents/praisonaiagents/agent/agent.py 3101-3105
2. Handoff functions - Match handoff_to_* pattern src/praisonai-agents/praisonaiagents/agent/agent.py 3108-3133
3. Self.tools list - Linear search by function name src/praisonai-agents/praisonaiagents/agent/agent.py 3136-3149

**Human Approval Workflow:**

- Triggered for tools with trust=False attribute src/praisonai-agents/praisonaiagents/agent/agent.py 3159-3166
- Displays rich panel with function name, arguments, description src/praisonai-agents/praisonaiagents/agent/agent.py 3175-3202
- Prompt: "Approve? (yes/no): " src/praisonai-agents/praisonaiagents/agent/agent.py 3205
- Response: "Execution denied by user" on rejection src/praisonai-agents/praisonaiagents/agent/agent.py 3208

**Tool Format Compatibility:**

- MCP tools - Call via mcp_instance.call_tool() src/praisonai-agents/praisonaiagents/agent/agent.py 3225-3250
- Callables - Direct invocation tool(**arguments) src/praisonai-agents/praisonaiagents/agent/agent.py 3252-3255
- LangChain - BaseTool with _run() method src/praisonai-agents/praisonaiagents/agent/agent.py 3258-3277
- CrewAI - Tools with _run() method src/praisonai-agents/praisonaiagents/agent/agent.py 3258-3277

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py3078-3312](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L3078-L3312)

#### Agent.get_available_tools()

Get list of all available tools for the agent.

```

```

Sources: [api.md43](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L43-L43)

### Knowledge/RAG Methods

#### Agent.query()

Query knowledge base using RAG.

```

```

#### Agent.retrieve()

Retrieve context from knowledge base.

```

```

#### Agent.chat_with_context()

Chat with pre-retrieved context.

```

```

For RAG system details, see [RAG System](/MervinPraison/PraisonAI/4.3-rag-system).

Sources: [api.md59-63](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L59-L63)

### Streaming Methods

#### Agent.iter_stream()

Iterate over streaming response chunks.

```

```

Sources: [api.md51](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L51-L51)

### API Server Methods

#### Agent.launch()

Launch agent as HTTP/A2A API server.

```

```

**Parameters:**

- path : Agent endpoint path
- port : Server port
- host : Server host
- debug : Enable debug mode
- protocol : 'http' or 'a2a' (Agent2Agent)

For A2A protocol details, see [A2A Protocol](/MervinPraison/PraisonAI/5.3-a2a-protocol).

Sources: [api.md52](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L52-L52)

### Async Methods

The Agent class also provides async variants for key methods:

Sources: [api.md15-20](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L15-L20)

## Agent Request Processing Lifecycle

The complete agent request processing involves multiple stages from input to final response, with extensive optimization for performance and safety.

### Agent Processing Pipeline

```

```

**Key Pipeline Stages:**

1. Parameter Resolution - Consolidated params resolved to config objects src/praisonai-agents/praisonaiagents/agent/agent.py 619-1103
2. Planning Gate - Optional PlanningAgent generates execution plan src/praisonai-agents/praisonaiagents/agent/agent.py 2486-2487
3. System Prompt Building - Combines role/goal/backstory with tool schemas src/praisonai-agents/praisonaiagents/agent/agent.py 2489-2544
4. Tool Execution Loop - Sequential tool calling with max 10 iterations src/praisonai-agents/praisonaiagents/agent/agent.py 2551-2679
5. Human Approval - Optional gating for dangerous tools src/praisonai-agents/praisonaiagents/agent/agent.py 3159-3209
6. Guardrails - Output validation with retry src/praisonai-agents/praisonaiagents/agent/agent.py 2689-2712
7. Self-Reflection - Quality assessment loop src/praisonai-agents/praisonaiagents/agent/agent.py 2714-2774
8. Memory Persistence - Auto-save to memory/session src/praisonai-agents/praisonaiagents/agent/agent.py 2779-2798

Sources: [src/praisonai-agents/praisonaiagents/agent/agent.py2452-2826](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L2452-L2826) [src/praisonai-agents/praisonaiagents/agent/agent.py2874-3076](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L2874-L3076) [src/praisonai-agents/praisonaiagents/agent/agent.py3078-3312](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agent/agent.py#L3078-L3312)

This architecture provides a robust, extensible foundation for AI agents with comprehensive safety controls, tool integration capabilities, and support for multiple LLM providers through both direct integration and the LiteLLM wrapper.
