1. Configuração e Primeiro Sucesso

Bem-vindo à sua jornada para construir agentes de IA com Python! Ao final deste capítulo, você terá feito sua primeira chamada bem-sucedida a um Large Language Model (LLM) e entendido exatamente o que aconteceu nos bastidores. Esta é a sua base para tudo o que vem a seguir.

Pré-requisitos

Público-alvo e Premissas

Este livro foi escrito para desenvolvedores Python que querem construir agentes de IA, mas não têm experiência prévia com LLMs ou frameworks de IA. Partimos do pressuposto de que você está confortável com:

• Fundamentos de Python: funções, classes, imports, estruturas de dados básicas
• Python 3.10+: Você deve ter Python 3.10 ou superior instalado no seu sistema
• Ambientes virtuais: criação e ativação de venvs com python -m venv
• Gerenciamento de pacotes: instalação de pacotes com pip
• Variáveis de ambiente: definir e ler variáveis de ambiente no seu shell
• Chaves de API: entender o que são chaves de API e como obtê-las de provedores de serviço

Se algum desses conceitos não for familiar, recomendamos revisá-los separadamente antes de continuar. A documentação do Python e tutoriais sobre ambientes virtuais e pip são excelentes pontos de partida.

O que NÃO presumimos: Você não precisa de nenhum conhecimento em aprendizado de máquina, redes neurais, transformers ou teoria de IA. Vamos explicar conceitos específicos de LLM à medida que os encontrarmos, sempre conectando-os a padrões de programação familiares.

Convenção de Modelo

Ao longo deste livro, usaremos GPT-5-mini como nosso modelo padrão para exemplos. Eis o porquê:

• Amplamente disponível: A API da OpenAI é acessível globalmente com um cadastro simples
• Velocidade razoável: Com esforço mínimo de raciocínio, as respostas chegam rápido o suficiente para desenvolvimento iterativo
• Custo-benefício: A $0.25 por milhão de tokens de entrada e $2.00 por milhão de tokens de saída (a partir de 2026), é acessível para aprendizado e experimentação
• Capacidade suficiente: Ele lida bem com a grande maioria das tarefas práticas de agentes de IA

Quando você vir exemplos de código sem um modelo explicitamente especificado, presuma que estamos usando GPT-5-mini. No Capítulo 2, vamos explorar todo o panorama de modelos disponíveis (Claude, Gemini e outras variantes de GPT) e discutir quando você pode escolher alternativas com base no tamanho da janela de contexto, custo ou capacidades especializadas.

1.1) O que é um LLM?

Antes de escrever qualquer código, vamos estabelecer com o que estamos realmente trabalhando. Um Large Language Model (LLM) é uma rede neural treinada com quantidades massivas de dados de texto para prever qual texto deve vir em seguida em uma sequência.

Pense nisso como um sistema de autocompletar extremamente sofisticado. Quando você digita no seu celular e ele sugere a próxima palavra, isso é uma versão simples do que LLMs fazem. Mas LLMs operam em uma escala e sofisticação que permite que eles:

• Gerem respostas coerentes e contextualmente apropriadas a perguntas
• Escrevam código, redações, e-mails e outros conteúdos estruturados
• Traduza entre idiomas
• Resuma documentos longos
• Extraia informações de texto não estruturado
• E muito mais

Como LLMs Diferem de Software Tradicional

Software tradicional segue regras explícitas que você programa:

def calculate_discount(price, customer_type):
    if customer_type == "premium":
        return price * 0.8  # 20% de desconto
    elif customer_type == "regular":
        return price * 0.95  # 5% de desconto
    else:
        return price

Essa função sempre produz a mesma saída para as mesmas entradas. A lógica é determinística e transparente.

LLMs funcionam de forma diferente. Em vez de regras explícitas, eles usam padrões aprendidos a partir de dados de treinamento para gerar respostas. Você fornece texto de entrada (chamado de prompt), e o modelo gera texto de saída (chamado de completion ou response).

# Exemplo conceitual - vamos escrever código real em breve
response = llm.generate("Qual é um bom desconto para clientes premium?")
# Exemplo de saída: "Clientes premium normalmente recebem descontos de 15-25%..."

O LLM não tem uma porcentagem de desconto codificada. Ele gera uma resposta com base em padrões que aprendeu durante o treinamento. Isso significa:

1. As respostas podem variar: O mesmo prompt pode produzir respostas ligeiramente diferentes a cada vez
2. O comportamento é aprendido, não programado: Você guia o modelo com prompts em vez de escrever lógica explícita
3. As capacidades emergem da escala: o modelo consegue lidar com tarefas para as quais não foi explicitamente treinado

Terminologia-chave

Vamos definir termos que você encontrará constantemente:

• Prompt: O texto de entrada que você envia ao modelo. Pense nisso como a "pergunta" ou "instrução"
• Completion/Response: O texto que o modelo gera em resposta ao seu prompt
• Token: A unidade básica com a qual LLMs trabalham. Aproximadamente, 1 token ≈ 4 caracteres ou ¾ de uma palavra. "Hello world" tem cerca de 2 tokens
• Janela de contexto: A quantidade máxima de texto (em tokens) que o modelo pode processar de uma vez. O GPT-5-mini tem uma janela de contexto de 400K tokens
• Temperature: Um parâmetro que controla aleatoriedade. Baixa (0.0-0.3) = mais focada e determinística. Alta (0.7-1.0) = mais criativa e variada

O que LLMs Podem e Não Podem Fazer

Entender o que LLMs fazem de forma confiável — e o que eles apenas parecem fazer — é essencial para construir agentes de IA robustos.

LLMs são excelentes em:

• Entender e gerar linguagem natural: Eles conseguem interpretar intenção, gerar respostas coerentes e lidar com redações complexas

"Quero um reembolso" → Reconhece intenção: refund_request
"Resuma este documento" → Produz um resumo conciso

• Seguir instruções em prompts: Quando recebem direções claras, conseguem produzir saídas estruturadas como JSON ou texto formatado

"Converta para JSON: John Smith, 32, mora em Boston"
→ {"name": "John Smith", "age": 32, "city": "Boston"}

• Reconhecer padrões em texto: análise de sentimento, categorização e extração de informações funcionam de forma confiável

• Gerar código e conteúdo estruturado: Podem escrever Python, SQL ou outra saída formatada válida quando bem instruídos por prompt

• Raciocínio passo a passo: Quando instruídos explicitamente a "pensar passo a passo", eles decompõem problemas de forma metódica

Limitações de LLM:

• Não é um banco de dados: Eles não recuperam fatos — eles geram texto estatisticamente plausível. Podem afirmar com confiança informações incorretas que soam autoritativas.

"Quando o Python 4.0 foi lançado?" 
→ Pode gerar "Python 4.0 foi lançado em 2023" (falso, mas plausível)

• Não é uma calculadora: Eles preveem como uma resposta deveria parecer em vez de calculá-la. Aritmética simples costuma funcionar; matemática complexa falha de forma imprevisível.

"Quanto é 8,247 × 6,839?" → Pode produzir um resultado errado que parece razoável

• Não é determinístico: O mesmo prompt pode produzir saídas diferentes a cada vez. Essa variabilidade é controlada pelo parâmetro temperature.

• Nem sempre é preciso: Eles geram texto que soa plausível independentemente da correção factual. "Alucinações" — informações detalhadas, confiantes, porém completamente fabricadas — ocorrem com frequência.

O insight-chave: Construa agentes que combinem LLMs (para compreensão e tomada de decisão) com ferramentas tradicionais (para cálculo, recuperação de dados e operações factuais). Vamos implementar esse padrão a partir do Capítulo 13, em que o LLM decide quando usar uma calculadora em vez de tentar fazer matemática por conta própria.

O que Você Vai Aprender

Neste livro, você aprenderá a construir agentes de IA - sistemas em que o LLM decide autonomamente quais ações executar para atingir objetivos, em vez de seguir uma lógica predeterminada. Vamos explorar esse paradigma em profundidade no Capítulo 2.

1.2) Instalar Dependências

Vamos configurar seu ambiente de desenvolvimento. Vamos criar uma estrutura de projeto limpa e instalar o LangChain, o framework que usaremos para construir agentes de IA.

Verificar a Instalação do Python

Primeiro, garanta que o Python esteja instalado no seu sistema. Recomendamos Python 3.10 ou superior (a partir de 2026, Python 3.13 ou 3.14 são boas escolhas).

Verifique sua versão do Python:

python --version
# or
python3 --version

Você deve ver uma saída como Python 3.13.x ou Python 3.14.x.

Se o Python não estiver instalado:

• macOS:

  • Baixe em python.org
  • Ou use Homebrew: brew install python@3.14

• Windows:

  • Baixe em python.org
  • Marque "Add Python to PATH" durante a instalação

• Linux:

  • Ubuntu/Debian: sudo apt update && sudo apt install python3.14
  • Fedora: sudo dnf install python3.14

Após a instalação, verifique novamente com python --version.

Observação: Em alguns sistemas, pode ser necessário usar python3 em vez de python. Ao longo deste livro, se python não funcionar, tente python3.

Criar Seu Projeto

Abra seu terminal e crie um novo diretório para seu projeto:

mkdir agentic-ai-project
cd agentic-ai-project

Crie um ambiente virtual para isolar dependências:

python -m venv venv

Ative o ambiente virtual:

# On macOS/Linux:
source venv/bin/activate
 
# On Windows:
venv\Scripts\activate

Você deve ver (venv) aparecer no prompt do seu terminal, indicando que o ambiente virtual está ativo.

Instalar LangChain e OpenAI

Vamos instalar a integração da OpenAI do LangChain, que inclui tudo o que é necessário para trabalhar com os modelos da OpenAI:

pip install langchain-openai

Isso instala langchain-openai junto com suas dependências, incluindo langchain-core (as abstrações centrais do LangChain) e o cliente Python da OpenAI. Você deve ver uma saída confirmando a instalação de múltiplos pacotes.

Verifique a instalação:

pip show langchain-openai

Você deve ver detalhes sobre o pacote instalado, incluindo seu número de versão e localização. Isso confirma que a instalação foi bem-sucedida.

Obter Sua Chave de API da OpenAI

Para chamar os modelos da OpenAI, você precisa de uma chave de API:

1. Vá para platform.openai.com
2. Cadastre-se ou faça login
3. Navegue até API Keys nas configurações da sua conta
4. Clique em "Create new secret key"
5. Copie a chave (ela começa com sk-)

⚠️ Aviso de Segurança: Trate esta chave como uma senha. Nunca faça commit dela em controle de versão nem a compartilhe publicamente. Qualquer pessoa com sua chave pode fazer chamadas de API que serão cobradas na sua conta.

Definir Sua Chave de API como uma Variável de Ambiente

A forma recomendada de fornecer sua chave de API é por meio de uma variável de ambiente:

# On macOS/Linux:
export OPENAI_API_KEY='sk-your-actual-key-here'
 
# On Windows (Command Prompt):
set OPENAI_API_KEY=sk-your-actual-key-here
 
# On Windows (PowerShell):
$env:OPENAI_API_KEY='sk-your-actual-key-here'

Observação: Essa configuração é temporária e será perdida quando você fechar o terminal. Para uma solução permanente, você pode:

• Adicionar o comando export ao arquivo de configuração do seu shell (.bashrc, .zshrc, etc.)
• Usar um arquivo .env (vamos configurar isso no Capítulo 3 para melhor organização do projeto)

Por enquanto, a configuração temporária é suficiente para continuar.

Verifique se ela foi definida:

# On macOS/Linux:
echo $OPENAI_API_KEY
 
# On Windows (Command Prompt):
echo %OPENAI_API_KEY%
 
# On Windows (PowerShell):
echo $env:OPENAI_API_KEY

Você deve ver sua chave de API impressa. Se não, repita o comando export/set e garanta que não haja erros de digitação.

1.3) Sua Primeira Chamada a um LLM

Agora a parte empolgante — vamos fazer sua primeira chamada a um LLM. Crie um arquivo chamado first_call.py:

# first_call.py
from langchain_openai import ChatOpenAI
 
# Inicialize o LLM
llm = ChatOpenAI(model="gpt-5-mini")
 
# Envie um prompt e obtenha uma resposta
response = llm.invoke("What is LangChain?")
 
# Imprima a resposta
print(response.content)

Execute:

python first_call.py

Você deve ver uma saída semelhante a esta (a redação exata pode variar):

LangChain é um framework projetado para simplificar o desenvolvimento de aplicações alimentadas por modelos de linguagem grandes (LLMs). Ele fornece ferramentas e abstrações para construir cadeias de chamadas de LLM, integrar fontes de dados externas, gerenciar prompts e criar agentes que podem interagir com várias APIs e bancos de dados. O LangChain facilita a construção de aplicações de IA complexas ao fornecer componentes e padrões reutilizáveis.

Parabéns! Você acabou de fazer sua primeira chamada a um LLM. Vamos detalhar o que aconteceu neste código.

Resolução de problemas: Se você vir um erro:

• AuthenticationError: A chave de API é inválida ou não está definida → Verifique sua variável de ambiente OPENAI_API_KEY (veja a seção 1.2)
• RateLimitError: Requisições rápidas demais ou limite de uso excedido → Aguarde alguns segundos e tente novamente, ou verifique o uso em platform.openai.com/usage
• APIConnectionError: Problema de conectividade de rede → Verifique sua conexão com a internet

Entendendo o Código

Importe o wrapper do LLM:

from langchain_openai import ChatOpenAI

ChatOpenAI é o wrapper do LangChain em torno dos modelos de chat da OpenAI. Ele lida com autenticação da API, formatação de requisições e parsing de respostas para você.

Inicialize o modelo:

llm = ChatOpenAI(model="gpt-5-mini")

Isso cria uma instância configurada para usar GPT-5-mini. Nos bastidores, o LangChain lê sua variável de ambiente OPENAI_API_KEY para autenticação. Você também poderia passar a chave explicitamente:

llm = ChatOpenAI(model="gpt-5-mini", api_key="sk-your-key")

Mas usar variáveis de ambiente é mais seguro e flexível.

Invoque o modelo:

response = llm.invoke("What is LangChain?")

O método invoke() envia seu prompt para a API da OpenAI e aguarda a resposta completa. Esta é uma chamada síncrona — seu programa pausa até a resposta chegar.

Acesse o conteúdo da resposta:

print(response.content)

O objeto de resposta contém vários campos. O campo .content guarda o texto de fato gerado pelo modelo. Vamos explorar outros campos na próxima seção.

Experimente Prompts Diferentes

Modifique o prompt para ver como o modelo responde a entradas diferentes:

# first_call.py
from langchain_openai import ChatOpenAI
 
llm = ChatOpenAI(model="gpt-5-mini")
 
# Experimente prompts diferentes
prompts = [
    "Explique decorators de Python em uma frase.",
    "Quanto é 15 * 23?",
    "Liste três benefícios de usar type hints em Python.",
]
 
for prompt in prompts:
    response = llm.invoke(prompt)
    print(f"Prompt: {prompt}")
    print(f"Resposta: {response.content}\n")

O modelo lida com diferentes tipos de pedidos — explicações, cálculos e listas estruturadas. Você vai notar que as respostas podem variar um pouco se você executar o mesmo prompt várias vezes. Isso é um comportamento normal — vamos explorar por que isso acontece e como controlar isso no Capítulo 2.

1.4) O Que Acabou de Acontecer? (Fluxo Request → Model → Response)

Vamos examinar exatamente o que aconteceu quando você chamou llm.invoke(). Entender esse fluxo é crucial para construir agentes de IA confiáveis.

O Ciclo Completo de Request-Response

Vamos rastrear cada etapa:

Etapa 1: Seu Código Chama invoke()

response = llm.invoke("What is LangChain?")

O método invoke() é sua interface principal com o LLM. Você passa uma string de prompt e ele retorna um objeto de resposta contendo a resposta do modelo. Por trás dessa chamada simples, várias etapas acontecem automaticamente.

Etapa 2: LangChain Formata a Requisição

O LangChain transforma sua string em uma requisição de API estruturada. Nos bastidores, ele cria um payload JSON como este:

{
  "model": "gpt-5-mini",
  "messages": [
    {
      "role": "user",
      "content": "What is LangChain?"
    }
  ],
  "temperature": 1.0
}

O array messages é como os modelos de chat recebem entrada. Cada mensagem tem um role (user, assistant ou system) e content (o texto). Vamos explorar papéis de mensagem no Capítulo 4.

Etapa 3: Chamada de API para a OpenAI

O LangChain envia uma requisição HTTPS POST para o endpoint da API da OpenAI:

POST https://api.openai.com/v1/chat/completions
Authorization: Bearer sk-your-api-key
Content-Type: application/json
 
{request payload}

Sua chave de API autentica a requisição. Os servidores da OpenAI recebem a requisição e a encaminham para o modelo especificado.

Etapa 4: O Modelo Processa o Prompt

O GPT-5-mini recebe seu prompt e gera uma resposta token por token. O modelo:

1. Converte seu texto em tokens (representações numéricas)
2. Processa os tokens através de suas camadas de rede neural
3. Prediz o próximo token mais provável
4. Repete até gerar uma resposta completa ou atingir uma condição de parada

Isso acontece nos servidores da OpenAI — seu código apenas espera pelo resultado.

Etapa 5: A API Retorna a Resposta

A API da OpenAI envia de volta uma resposta JSON:

{
  "id": "chatcmpl-8x7y9z",
  "object": "chat.completion",
  "created": 1704067200,
  "model": "gpt-5-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "LangChain é um framework projetado para simplificar..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 58,
    "total_tokens": 70
  }
}

Campos-chave:

• message.content: O texto gerado
• usage: Contagens de tokens para cobrança e monitoramento
• finish_reason: Por que a geração parou ("stop" = conclusão natural, "length" = atingiu limite de tokens)

Etapa 6: LangChain Faz o Parsing da Resposta

O LangChain converte o JSON em um objeto Python com o qual você pode trabalhar:

from langchain_openai import ChatOpenAI
 
llm = ChatOpenAI(model="gpt-5-mini")
response = llm.invoke("What is LangChain?")
 
# Explore o objeto de resposta
print(f"Conteúdo: {response.content}")
print(f"Tipo: {type(response)}")
print(f"Metadados da resposta: {response.response_metadata}")

Saída:

Conteúdo: LangChain é um framework projetado para simplificar...
Tipo: <class 'langchain_core.messages.ai.AIMessage'>
Metadados da resposta: {'token_usage': {'completion_tokens': 58, 'prompt_tokens': 12, 'total_tokens': 70}, 'model_name': 'gpt-5-mini', 'finish_reason': 'stop'}

A resposta é um objeto AIMessage com vários atributos úteis:

• content: O texto gerado (o que você normalmente quer)
• response_metadata: Uso de tokens, nome do modelo, motivo de término
• id: Identificador único para esta resposta
• usage_metadata: Detalhamento de tokens mais detalhado

Entendendo o Uso de Tokens

Antes de olhar as contagens de tokens, uma nota rápida: tokens são as unidades básicas que LLMs processam. Em inglês, o texto normalmente usa um pouco mais de 1 token por palavra (por exemplo, "explain quantum computing" = 3 palavras, 4-5 tokens), mas idiomas não ingleses como coreano ou chinês exigem significativamente mais tokens para representar o mesmo texto. Vamos explorar tokens em mais detalhes no Capítulo 2.

Vamos examinar o consumo de tokens mais de perto:

from langchain_openai import ChatOpenAI
 
llm = ChatOpenAI(model="gpt-5-mini")
response = llm.invoke("Explique computação quântica em termos simples.")
 
usage = response.response_metadata['token_usage']
print(f"Tokens de entrada: {usage['prompt_tokens']}")
print(f"Tokens de saída: {usage['completion_tokens']}")
print(f"Tokens totais: {usage['total_tokens']}")

Saída:

Tokens de entrada: 11
Tokens de saída: 95
Tokens totais: 106

Observação: prompt_tokens = tokens de entrada (seu prompt), completion_tokens = tokens de saída (resposta do modelo), total_tokens = soma de ambos.

O consumo de tokens varia com base em:

• Tamanho do prompt: Prompts mais longos usam mais tokens de entrada
• Detalhamento da resposta: Respostas detalhadas geram mais tokens de saída
• Complexidade do idioma: Termos técnicos e código podem tokenizar de forma diferente

Por exemplo, um prompt curto como "What's 2+2?" (em português: "Quanto é 2+2?") pode usar apenas 5-6 tokens de entrada e 8-10 tokens de saída, enquanto "Write a detailed essay about the history of Python programming language" poderia usar 15-20 tokens de entrada e 500+ tokens de saída.

Cálculo de custo para o exemplo acima:

No preço do GPT-5-mini ($0.25 por milhão de tokens de entrada, $2.00 por milhão de tokens de saída):

• Entrada: 11 tokens × $0.25 / 1,000,000 = $0.00000275
• Saída: 95 tokens × $2.00 / 1,000,000 = $0.00019
• Total: ~$0.0002 (dois centésimos de centavo)

Você paga por tokens de entrada e de saída, mas tokens de saída custam mais (8× neste caso).

O que Você Aprendeu

Agora você entende o ciclo de vida completo de uma chamada a um LLM:

1. Seu código fornece uma string de prompt
2. LangChain a formata em uma requisição de API com autenticação
3. A API da OpenAI encaminha a requisição para o modelo
4. O modelo gera uma resposta token por token
5. A API retorna JSON estruturado com a resposta e metadados
6. LangChain faz o parsing disso em um objeto Python
7. Seu código acessa o conteúdo e os metadados

Você também aprendeu:

• Como inspecionar objetos de resposta e extrair metadados
• Como o uso de tokens afeta custos

Esta base prepara você para o Capítulo 2, em que vamos explorar como LLMs realmente funcionam por baixo do capô, comparar diferentes modelos e aprender técnicas de prompt engineering para obter resultados melhores.