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

# Vision Agent

> Specialized agent for image analysis, description, comparison, and text extraction using AI vision models.

Analyse, describe, compare, and read text from images with the `VisionAgent` and its dedicated methods.

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

agent = VisionAgent()

result = agent.analyze("https://example.com/image.jpg")
print(result)
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Vision Agent"
        User[📋 Image] --> Agent[🤖 VisionAgent]
        Agent --> Model[🧠 Vision Model]
        Model --> Result[✅ Analysis]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class User,Agent input
    class Model process
    class Result output
```

> [!NOTE]
>
> VisionAgent provides dedicated methods for image understanding tasks like analysis, description, comparison, and text extraction.

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant VisionAgent
    participant Model as Vision Model

    User->>VisionAgent: analyze(image_url)
    VisionAgent->>Model: Send image + prompt
    Model-->>VisionAgent: Description / comparison / text
    VisionAgent-->>User: Analysis result
```

***

## Quick Start

**1. Install**

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

**2. Create Agent**

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

agent = VisionAgent()
```

**3. Analyze Image**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
result = agent.analyze("https://example.com/image.jpg")
print(result)
```

***

## Methods

> [accordion] analyze()
>
> Analyze an image with optional custom prompt.
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import VisionAgent
>
> agent = VisionAgent()
>
> # Basic analysis
> result = agent.analyze("image.jpg")
>
> # With custom prompt
> result = agent.analyze(
>     "chart.png",
>     prompt="What data does this chart show?"
> )
> ```
>
> **image** `str` *required*
>
> Image URL or local file path
>
> **prompt** `str`
>
> Custom analysis prompt
>
> **detail** `str` (default: auto)
>
> Detail level: `low`, `high`, or `auto`

> [accordion] describe()
>
> Generate detailed description of an image.
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> description = agent.describe("photo.jpg")
> print(description)
> ```
>
> Returns comprehensive description including:
>
> * Main subject and composition
> * Colors, lighting, mood
> * Background and setting
> * Text, symbols, notable details

> [accordion] compare()
>
> Compare multiple images.
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> comparison = agent.compare([
>     "before.jpg",
>     "after.jpg"
> ], prompt="What changed?")
> ```
>
> **images** `List[str]` *required*
>
> List of image URLs or paths (minimum 2)

> [accordion] extract\_text()
>
> Extract text from images (OCR-like).
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> text = agent.extract_text("document.png", detail="high")
> print(text)
> ```
>
> > [!TIP]
> >
> > Use `detail="high"` for better text extraction accuracy.

***

## Configuration

> [tab] Basic
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import VisionAgent
>
> agent = VisionAgent(
>     name="MyVision",
>     llm="gpt-4o",
>     verbose=True
> )
> ```

> [tab] With Config
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> from praisonaiagents import VisionAgent, VisionConfig
>
> config = VisionConfig(
>     detail="high",
>     max_tokens=8192,
>     timeout=120
> )
>
> agent = VisionAgent(vision=config)
> ```

> [tab] Dict Config
>
> ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> agent = VisionAgent(
>     vision={
>         "detail": "high",
>         "max_tokens": 4096
>     }
> )
> ```

### VisionConfig Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `detail` | str | `"auto"` | Detail level: `low`, `high`, `auto` |
| `max_tokens` | int | `4096` | Maximum response tokens |
| `timeout` | int | `60` | Request timeout in seconds |

***

## Supported Models

> [card] OpenAI
>
> * `gpt-4o` (default)
> * `gpt-4o-mini`
> * `gpt-4-turbo`

> [card] Anthropic
>
> * `claude-3-5-sonnet-20241022`
> * `claude-3-opus-20240229`

> [card] Google
>
> * `gemini/gemini-1.5-pro`
> * `gemini/gemini-1.5-flash`

***

## Examples

### Analyze Chart Data

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

agent = VisionAgent(llm="gpt-4o")

result = agent.analyze(
    "https://example.com/sales-chart.png",
    prompt="Extract all data points and trends from this chart"
)
print(result)
```

### Compare Product Images

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent = VisionAgent()

comparison = agent.compare([
    "product_v1.jpg",
    "product_v2.jpg",
    "product_v3.jpg"
], prompt="Describe the design evolution across these versions")
```

### Extract Document Text

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent = VisionAgent()

# High detail for better OCR
text = agent.extract_text(
    "scanned_document.png",
    detail="high"
)
print(text)
```

### Async Usage

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import asyncio
from praisonaiagents import VisionAgent

async def main():
    agent = VisionAgent()
    result = await agent.aanalyze("image.jpg")
    print(result)

asyncio.run(main())
```

***

## Comparison with ImageAgent

> [!NOTE]
>
> **VisionAgent** is for image **analysis/understanding**.\
> **ImageAgent** is for image **generation**.

| Feature | VisionAgent | ImageAgent |
| - | - | - |
| Purpose | Analyze images | Generate images |
| Input | Image URL/path | Text prompt |
| Output | Text description | Image file/URL |
| Models | GPT-4o, Claude, Gemini | DALL-E, Stable Diffusion |

***

## Best Practices

> [accordion] Pick the method that matches the task
>
> Use `analyze` for open-ended questions, `describe` for captions, `compare` for two images, and text extraction for OCR. The dedicated methods prompt the model more precisely than a raw call.

> [accordion] Use a vision-capable model
>
> VisionAgent needs a multimodal model (GPT-4o, Claude, Gemini). Point it at a text-only model and it cannot see the image.

> [accordion] Give a specific prompt for analysis
>
> `analyze(image, prompt="Count the people")` beats a bare `analyze(image)`. A focused question yields a focused, useful answer.

> [accordion] Reach for ImageAgent to generate, not analyse
>
> VisionAgent understands existing images. To create new images from a text prompt, use the ImageAgent instead.

## Related

> [card]
>
> Generate images from text prompts.
>
> [Open](https://praison.ai/docs/agents/image.md)

> [card]
>
> Extract text from images with OCR.
>
> [Open](https://praison.ai/docs/agents/image-to-text.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.