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

<Info>
  VisionAgent provides dedicated methods for image understanding tasks like analysis, description, comparison, and text extraction.
</Info>

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

<Steps>
  <Step title="Install">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install praisonaiagents litellm
    export OPENAI_API_KEY="your-key"
    ```
  </Step>

  <Step title="Create Agent">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import VisionAgent

    agent = VisionAgent()
    ```
  </Step>

  <Step title="Analyze Image">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    result = agent.analyze("https://example.com/image.jpg")
    print(result)
    ```
  </Step>
</Steps>

***

## Methods

<AccordionGroup>
  <Accordion title="analyze()" icon="magnifying-glass">
    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?"
    )
    ```

    <ParamField path="image" type="str" required>
      Image URL or local file path
    </ParamField>

    <ParamField path="prompt" type="str">
      Custom analysis prompt
    </ParamField>

    <ParamField path="detail" type="str" default="auto">
      Detail level: `low`, `high`, or `auto`
    </ParamField>
  </Accordion>

  <Accordion title="describe()" icon="file-lines">
    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>

  <Accordion title="compare()" icon="code-compare">
    Compare multiple images.

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    comparison = agent.compare([
        "before.jpg",
        "after.jpg"
    ], prompt="What changed?")
    ```

    <ParamField path="images" type="List[str]" required>
      List of image URLs or paths (minimum 2)
    </ParamField>
  </Accordion>

  <Accordion title="extract_text()" icon="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.</Tip>
  </Accordion>
</AccordionGroup>

***

## Configuration

<Tabs>
  <Tab title="Basic">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import VisionAgent

    agent = VisionAgent(
        name="MyVision",
        llm="gpt-4o",
        verbose=True
    )
    ```
  </Tab>

  <Tab title="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>

  <Tab title="Dict Config">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    agent = VisionAgent(
        vision={
            "detail": "high",
            "max_tokens": 4096
        }
    )
    ```
  </Tab>
</Tabs>

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

<CardGroup cols={3}>
  <Card title="OpenAI" icon="robot">
    * `gpt-4o` (default)
    * `gpt-4o-mini`
    * `gpt-4-turbo`
  </Card>

  <Card title="Anthropic" icon="a">
    * `claude-3-5-sonnet-20241022`
    * `claude-3-opus-20240229`
  </Card>

  <Card title="Google" icon="google">
    * `gemini/gemini-1.5-pro`
    * `gemini/gemini-1.5-flash`
  </Card>
</CardGroup>

***

## 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**.
</Note>

| 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

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="Reach for ImageAgent to generate, not analyse">
    VisionAgent understands existing images. To create new images from a text prompt, use the ImageAgent instead.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card icon="image" href="/docs/agents/image">
    Generate images from text prompts.
  </Card>

  <Card icon="text" href="/docs/agents/image-to-text">
    Extract text from images with OCR.
  </Card>
</CardGroup>