AI Agents · Aula

Agentes de imagem + texto com Claude Vision e GPT-4V

Enviando imagens em chamadas de API, fundamentação visual e uso de ferramentas com reconhecimento de imagens.

Aula 1 de 413 etapas

Agentes de imagem + texto com Claude Vision e GPT-4V é uma aula grátis de AI Agents no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Agents, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Agents inclui 4 aulas no total.

Agentes multimodais: imagens + texto

Um agente multimodal pode ver e também ler. Ao enviar imagens junto com texto na mesma chamada de API, o agente pode responder a perguntas sobre fotos, analisar gráficos, ler capturas de tela e descrever diagramas — tudo no mesmo ciclo de conversa.

Enviando imagens com a API da OpenAI

Os modelos de visão da OpenAI (GPT-4o, GPT-4V) aceitam uma matriz content em vez de uma cadeia de caracteres simples. Cada elemento é um objeto text ou um objeto image_url. A imagem pode ser uma URL pública ou uma URL de dados codificada em 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ção de imagens em base64

Para imagens que não estão acessíveis publicamente (arquivos locais, capturas de tela e carregamentos de usuários), codifique-as em base64 e incorpore-as diretamente na chamada da API usando o esquema de 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 de visão do Claude

Os modelos Claude da Anthropic também oferecem suporte à visão. O bloco de conteúdo usa um campo source com type: base64 e media_type. A estrutura é um pouco diferente da da OpenAI, mas é igualmente poderosa.

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)

Detectando o tipo MIME pela extensão do arquivo

Diferentes formatos de imagem (JPEG, PNG, GIF, WebP) usam tipos MIME diferentes. Detecte automaticamente o tipo MIME pela extensão do arquivo para nunca precisar defini-lo diretamente no código do 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')

Análise de imagens em um ciclo de agente

Em um ciclo de agente, a análise de imagens é uma ferramenta. O agente decide quando invocá-la, assim como qualquer outra ferramenta. Defina-a no esquema da ferramenta e retorne dados estruturados (JSON) para que o agente possa raciocinar sobre eles de forma programática.

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)

Controlando o nível de detalhe das imagens (OpenAI)

A API de visão da OpenAI aceita um parâmetro detail: low (rápido, barato, 85 tokens), high (detalhado, divide a imagem em blocos, até 1105 tokens) ou auto (o modelo decide). Use low para perguntas simples de sim ou não e high para análises minuciosas, como a leitura de textos pequenos.

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

Conversas com várias imagens

Você pode enviar várias imagens em uma única mensagem ou ao longo dos turnos de uma conversa. Isso permite tarefas de comparação: 'Compare estas duas capturas de tela e descreva o que mudou.'

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 de imagens: leitor de capturas de tela

Um caso de uso prático: um agente que lê capturas de tela de aplicativos para extrair valores de campos de formulário, mensagens de erro ou o estado da interface. Isso é útil para automação de testes e monitoramento de fluxos.

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)

Otimização de custos em chamadas de visão

As chamadas à API de visão são significativamente mais caras do que as chamadas somente de texto. Otimize os custos: redimensione as imagens antes da codificação (a maioria dos modelos aceita 512×512–2048×2048), use detail=low para tarefas simples, armazene em cache os resultados da análise para imagens inalteradas e agrupe várias perguntas em uma única chamada.

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'

Limitações da visão e alternativas

Os modelos de visão têm limitações: não conseguem ler textos muito pequenos de forma confiável, têm dificuldade com imagens muito comprimidas e podem inventar detalhes. Sempre valide os dados extraídos importantes (por exemplo, números de gráficos) com uma instrução alternativa que solicite pontuações de confiança.

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ção de conhecimento

Qual parâmetro controla o nível de detalhe e o custo da análise de imagens na API de visão da OpenAI?

Responda na aula interativa

Recapitulação: agentes de imagem e texto

Muito bem! Eis o que você aprendeu:

Visão da OpenAI: matriz content com objetos image_url + text; oferece suporte a URL e base64
Visão do Claude: source.type: base64 com media_type
Codificação em base64: ler o arquivo → codificar em base64 → incorporar como URL de dados
Nível de detalhe: use low para análises rápidas e baratas e high para análises minuciosas
Otimização de custos: redimensionar imagens, agrupar perguntas e armazenar resultados em cache

A seguir: fluxos de trabalho de agentes de áudio e texto com transcrição pelo Whisper e respostas em TTS.

Grátis para começar

Aprenda AI Agents com um tutor de IA — grátis

Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.

Cursos: 60
Aulas: 239

Começar a aprender grátis Ver o curso completo

Perguntas Frequentes

A aula “Agentes de imagem + texto com Claude Vision e GPT-4V” é grátis?

Sim — o texto completo de “Agentes de imagem + texto com Claude Vision e GPT-4V” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Agents, atualize para CoddyKit PRO. O curso de AI Agents inclui 4 aulas no total.

O que vou aprender em “Agentes de imagem + texto com Claude Vision e GPT-4V”?

Enviando imagens em chamadas de API, fundamentação visual e uso de ferramentas com reconhecimento de imagens. Você pratica AI Agents com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar AI Agents?

Nenhuma experiência prévia é necessária. AI Agents no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Quanto tempo leva a aula “Agentes de imagem + texto com Claude Vision e GPT-4V”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de AI Agents?

Sim. Cada aula de AI Agents inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

Agentes de imagem + texto com Claude Vision e GPT-4V
Fluxos de trabalho de agentes de áudio + texto
Compreensão de vídeo em agentes
Padrões de raciocínio entre modalidades

← Voltar para AI Agents