0Pricing
AI Agents · Lezione

Agenti multimodali di immagini e testo con Claude Vision e GPT-4V

Invio di immagini nelle chiamate API, grounding visivo e uso di strumenti sensibile alle immagini.

Agenti multimodali di immagini e testo con Claude Vision e GPT-4V è una lezione AI Agents gratuita su CoddyKit. Questa è la lezione 1 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento AI Agents, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Agents include 4 lezioni in totale.

Agenti multimodali: immagini + testo

Un agente multimodale può vedere oltre che leggere. Inviando immagini insieme al testo nella stessa chiamata API, l'agente può rispondere a domande sulle foto, analizzare grafici, leggere screenshot e descrivere diagrammi, tutto all'interno dello stesso ciclo conversazionale.

Inviare immagini con l'API OpenAI

I modelli di visione di OpenAI (GPT-4o, GPT-4V) accettano un array content invece di una semplice stringa. Ogni elemento è un oggetto text oppure un oggetto image_url. L'immagine può essere un URL pubblico oppure un data URL codificato in base64.

from openai import OpenAI

client = OpenAI(api_key='YOUR_OPENAI_API_KEY')

# Using a public URL
response = client.chat.completions.create(
    model='gpt-4o',
    messages=[
        {
            'role': 'user',
            'content': [
                {
                    'type': 'image_url',
                    'image_url': {
                        'url': 'https://example.com/chart.png'
                    }
                },
                {
                    'type': 'text',
                    'text': 'What trend does this chart show?'
                }
            ]
        }
    ],
    max_tokens=512
)
print(response.choices[0].message.content)

Codifica delle immagini in Base64

Per le immagini che non sono accessibili pubblicamente (file locali, screenshot, caricamenti degli utenti), le codifichi in base64 e le incorpori direttamente nella chiamata API utilizzando lo schema di URL data:image/jpeg;base64,....

import base64
from pathlib import Path

Path('screenshot.png').write_bytes(b'\x89PNG\r\n\x1a\n' + bytes(range(40)))

def encode_image_to_base64(image_path: str) -> str:
    with open(image_path, 'rb') as f:
        return base64.b64encode(f.read()).decode('utf-8')

def build_image_message(image_path: str, question: str, mime: str = 'jpeg') -> dict:
    b64 = encode_image_to_base64(image_path)
    data_url = f'data:image/{mime};base64,{b64}'
    return {
        'role': 'user',
        'content': [
            {'type': 'image_url', 'image_url': {'url': data_url}},
            {'type': 'text', 'text': question}
        ]
    }

message = build_image_message('screenshot.png', 'What error is shown?', mime='png')
print('Message built, image size:', len(message['content'][0]['image_url']['url']))

API Claude Vision

Anche i modelli Claude di Anthropic supportano la visione. Il blocco di contenuto utilizza un campo source con type: base64 e media_type. La struttura è leggermente diversa da quella di OpenAI, ma altrettanto potente.

import anthropic
import base64

client = anthropic.Anthropic(api_key='YOUR_ANTHROPIC_API_KEY')

with open('diagram.png', 'rb') as f:
    image_data = base64.standard_b64encode(f.read()).decode('utf-8')

response = client.messages.create(
    model='claude-opus-4-5',
    max_tokens=512,
    messages=[
        {
            'role': 'user',
            'content': [
                {
                    'type': 'image',
                    'source': {
                        'type': 'base64',
                        'media_type': 'image/png',
                        'data': image_data
                    }
                },
                {
                    'type': 'text',
                    'text': 'Describe the architecture shown in this diagram.'
                }
            ]
        }
    ]
)
print(response.content[0].text)

Rilevare il tipo MIME dall'estensione del file

Formati di immagine diversi (JPEG, PNG, GIF, WebP) utilizzano tipi MIME diversi. Rilevi automaticamente il tipo MIME dall'estensione del file, così non dovrà mai inserirlo manualmente nel codice dell'agente.

import os
import base64

with open('photo.jpg', 'wb') as f:
    f.write(b'\xff\xd8\xff' + bytes(range(30)))

MIME_MAP = {
    '.jpg': 'image/jpeg',
    '.jpeg': 'image/jpeg',
    '.png': 'image/png',
    '.gif': 'image/gif',
    '.webp': 'image/webp'
}

def get_mime_type(image_path: str) -> str:
    ext = os.path.splitext(image_path)[1].lower()
    mime = MIME_MAP.get(ext)
    if not mime:
        raise ValueError(f'Unsupported image format: {ext}')
    return mime

def load_image_as_base64(image_path: str) -> tuple:
    """Returns (base64_string, mime_type)"""
    mime = get_mime_type(image_path)
    with open(image_path, 'rb') as f:
        b64 = base64.b64encode(f.read()).decode('utf-8')
    return b64, mime

b64, mime = load_image_as_base64('photo.jpg')
print(f'MIME: {mime}, Size: {len(b64)} bytes base64')

Analisi delle immagini in un ciclo dell'agente

In un ciclo dell'agente, l'analisi delle immagini è uno strumento. L'agente decide quando richiamarlo, proprio come farebbe con qualsiasi altro strumento. Lo definisca nello schema degli strumenti e restituisca dati strutturati (JSON), così l'agente potrà ragionarci programmaticamente.

def analyze_image_tool(image_path: str, query: str) -> dict:
    """
    Agent tool: analyse an image and return structured findings.
    """
    import anthropic, base64
    client = anthropic.Anthropic(api_key='YOUR_API_KEY')
    b64, mime = load_image_as_base64(image_path)

    structured_query = (
        query + '\n\nRespond with JSON only: '
        '{"description": str, "objects": [str], "text_found": str, "confidence": float}'
    )
    response = client.messages.create(
        model='claude-opus-4-5',
        max_tokens=512,
        messages=[{
            'role': 'user',
            'content': [
                {'type': 'image', 'source': {'type': 'base64',
                  'media_type': mime, 'data': b64}},
                {'type': 'text', 'text': structured_query}
            ]
        }]
    )
    import json
    return json.loads(response.content[0].text)

Controllare il livello di dettaglio delle immagini (OpenAI)

L'API di visione di OpenAI accetta un parametro detail: low (rapido, economico, 85 token), high (dettagliato, suddivide l'immagine in riquadri, fino a 1105 token) oppure auto (decide il modello). Utilizzi low per semplici domande con risposta sì/no e high per analisi dettagliate, ad esempio per leggere caratteri di piccole dimensioni.

def query_image_openai(
    image_path: str,
    question: str,
    detail: str = 'auto'  # 'low', 'high', or 'auto'
) -> str:
    import base64
    from openai import OpenAI
    client = OpenAI(api_key='YOUR_OPENAI_API_KEY')
    b64, mime = load_image_as_base64(image_path)
    data_url = f'data:{mime};base64,{b64}'

    response = client.chat.completions.create(
        model='gpt-4o',
        max_tokens=512,
        messages=[{
            'role': 'user',
            'content': [
                {
                    'type': 'image_url',
                    'image_url': {'url': data_url, 'detail': detail}
                },
                {'type': 'text', 'text': question}
            ]
        }]
    )
    return response.choices[0].message.content

Conversazioni con più immagini

Può inviare più immagini in un singolo messaggio oppure in turni diversi della conversazione. Questo consente di svolgere attività di confronto: 'Confronti questi due screenshot e descriva che cosa è cambiato.'

def compare_two_images(
    image_path_1: str,
    image_path_2: str,
    comparison_question: str
) -> str:
    import anthropic, base64
    client = anthropic.Anthropic(api_key='YOUR_API_KEY')
    b64_1, mime_1 = load_image_as_base64(image_path_1)
    b64_2, mime_2 = load_image_as_base64(image_path_2)

    response = client.messages.create(
        model='claude-opus-4-5',
        max_tokens=512,
        messages=[{
            'role': 'user',
            'content': [
                {'type': 'image', 'source': {'type': 'base64',
                  'media_type': mime_1, 'data': b64_1}},
                {'type': 'image', 'source': {'type': 'base64',
                  'media_type': mime_2, 'data': b64_2}},
                {'type': 'text', 'text': comparison_question}
            ]
        }]
    )
    return response.content[0].text

Agente per immagini: lettore di screenshot

Un caso d'uso pratico è un agente che legge gli screenshot delle applicazioni per estrarre i valori dei campi dei moduli, i messaggi di errore o lo stato dell'interfaccia. È utile per l'automazione dei test e per le pipeline di monitoraggio.

SCREENSHOT_READER_PROMPT = (
    'You are a UI analyser. Given this application screenshot, extract:\n'
    '1. The current page/screen name\n'
    '2. Any error messages\n'
    '3. Key UI elements visible (buttons, form fields, text)\n'
    '4. The overall app state\n\n'
    'Return JSON: {"screen": str, "errors": [str], '
    '"elements": [str], "state": str}'
)

def read_screenshot(screenshot_path: str) -> dict:
    import anthropic, base64, json
    client = anthropic.Anthropic(api_key='YOUR_API_KEY')
    b64, mime = load_image_as_base64(screenshot_path)
    response = client.messages.create(
        model='claude-opus-4-5',
        max_tokens=512,
        messages=[{
            'role': 'user',
            'content': [
                {'type': 'image', 'source': {'type': 'base64',
                  'media_type': mime, 'data': b64}},
                {'type': 'text', 'text': SCREENSHOT_READER_PROMPT}
            ]
        }]
    )
    return json.loads(response.content[0].text)

Ottimizzare i costi delle chiamate di visione

Le chiamate alle API di visione sono significativamente più costose delle chiamate che utilizzano solo testo. Ottimizzi i costi ridimensionando le immagini prima della codifica (la maggior parte dei modelli accetta immagini da 512×512 a 2048×2048), utilizzando detail=low per le attività semplici, memorizzando nella cache i risultati dell'analisi per le immagini non modificate e raggruppando più domande in un'unica chiamata.

from PIL import Image
import io, base64

def resize_and_encode(
    image_path: str,
    max_dim: int = 1024
) -> tuple:
    img = Image.open(image_path)
    # Resize maintaining aspect ratio
    ratio = min(max_dim / img.width, max_dim / img.height)
    if ratio < 1.0:
        new_w = int(img.width * ratio)
        new_h = int(img.height * ratio)
        img = img.resize((new_w, new_h), Image.LANCZOS)
        print(f'Resized to {new_w}x{new_h} (from {img.width}x{img.height})')

    # Convert to JPEG for smaller size
    buf = io.BytesIO()
    img.save(buf, format='JPEG', quality=85)
    b64 = base64.b64encode(buf.getvalue()).decode('utf-8')
    return b64, 'image/jpeg'

Limiti della visione e strategie di fallback

I modelli di visione presentano alcuni limiti: non riescono a leggere in modo affidabile testi molto piccoli, hanno difficoltà con immagini fortemente compresse e possono inventare dettagli. Convalidi sempre i dati estratti che sono fondamentali (ad esempio, i numeri nei grafici) utilizzando un prompt di fallback che richieda punteggi di affidabilità.

def analyze_with_confidence(
    image_path: str,
    question: str,
    confidence_threshold: float = 0.7
) -> dict:
    import anthropic, json
    client = anthropic.Anthropic(api_key='YOUR_API_KEY')
    b64, mime = load_image_as_base64(image_path)

    prompt = (
        question + '\n\nAlso rate your confidence (0.0-1.0) in the answer.\n'
        'Return JSON: {"answer": str, "confidence": float, '
        '"uncertainty_reason": str}'
    )
    response = client.messages.create(
        model='claude-opus-4-5', max_tokens=256,
        messages=[{'role': 'user', 'content': [
            {'type': 'image', 'source': {'type': 'base64',
              'media_type': mime, 'data': b64}},
            {'type': 'text', 'text': prompt}
        ]}]
    )
    result = json.loads(response.content[0].text)
    if result['confidence'] < confidence_threshold:
        result['action'] = 'human_review_needed'
    return result

Verifica delle conoscenze

Quale parametro controlla il livello di dettaglio e il costo dell'analisi delle immagini nell'API di visione di OpenAI?

Riepilogo: agenti immagine-testo

Ottimo lavoro! Ecco gli argomenti trattati:

  • Visione di OpenAI: array content con oggetti image_url e text; supporta URL e base64
  • Visione di Claude: source.type: base64 con media_type
  • Codifica Base64: leggere il file → codificarlo in base64 → incorporarlo come data URL
  • Livello di dettaglio: utilizzare low per analisi rapide ed economiche, high per analisi dettagliate
  • Ottimizzazione dei costi: ridimensionare le immagini, raggruppare le domande, memorizzare i risultati nella cache

Prossimo argomento: flussi di lavoro per agenti audio-testo con la trascrizione Whisper e le risposte TTS.

Domande Frequenti

La lezione «Agenti multimodali di immagini e testo con Claude Vision e GPT-4V» è gratuita?

Sì — il testo completo di «Agenti multimodali di immagini e testo con Claude Vision e GPT-4V» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso AI Agents, passa a CoddyKit PRO. Il corso AI Agents include 4 lezioni in totale.

Cosa imparerò in «Agenti multimodali di immagini e testo con Claude Vision e GPT-4V»?

Invio di immagini nelle chiamate API, grounding visivo e uso di strumenti sensibile alle immagini. Eserciti AI Agents con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare AI Agents?

Non è richiesta alcuna esperienza precedente. AI Agents su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 1 di 4.

Quanto tempo richiede la lezione «Agenti multimodali di immagini e testo con Claude Vision e GPT-4V»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione AI Agents?

Sì. Ogni lezione AI Agents include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

  1. Agenti multimodali di immagini e testo con Claude Vision e GPT-4V
  2. Workflow per agenti audio e testo
  3. Comprensione dei video negli agenti
  4. Pattern di ragionamento cross-modale
← Torna a AI Agents