> ## 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.
# Agents
> Create AI agents that understand instructions, use tools, and complete tasks
An Agent is an AI that follows your instructions, uses tools, and completes tasks through conversation.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Agent Flow"
Input[💬 User Input] --> Agent[🤖 Agent]
Agent --> Tools[🔧 Tools]
Tools --> Agent
Agent --> Response[✅ Response]
end
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef tools fill:#189AB4,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class Input input
class Agent agent
class Tools tools
class Response output
```
## Quick Start
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(instructions="You are a helpful assistant.")
response = agent.start("Explain machine learning in one paragraph.")
print(response)
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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?")
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Agent
participant LLM
participant Tools
User->>Agent: Message
Agent->>LLM: Format + send prompt
LLM-->>Agent: Response or tool call
opt Tool call needed
Agent->>Tools: Execute tool
Tools-->>Agent: Tool result
Agent->>LLM: Continue with result
LLM-->>Agent: Final response
end
Agent-->>User: Response
```
| 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
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, MemoryConfig, ExecutionConfig
agent = Agent(
name="ProductionAgent",
instructions="You are a reliable production assistant.",
memory=MemoryConfig(backend="redis", 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
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.
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.
`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.
Always set `name` when using multiple agents. Names appear in logs, hooks callbacks, and help diagnose which agent produced which output in complex workflows.
***
## Related
Tools — add capabilities like web search and code execution
Memory — give agents persistent memory across sessions