Verificando a instalação

Você instalou quatro coisas: Python, ambiente virtual, bibliotecas e o Ollama com um modelo. Cada uma delas funcionando isoladamente não garante que conversam entre si — e é justamente aí que aparecem os problemas.

Vamos verificar tudo de uma vez, antes da primeira aula prática.

Passo 1: conferências rápidas

Com o ambiente virtual ativo (o cursor mostrando (.venv)), rode um comando de cada vez:

python --version

Esperado: Python 3.12.x.

(Get-Command python).Source

Esperado: um caminho que termina em \.venv\Scripts\python.exe. Se apontar para outro lugar, o ambiente virtual não está ativo — e tudo o que você instalou foi parar no lugar errado.

curl http://127.0.0.1:11434/api/version

Esperado: um JSON como {"version":"0.33.2"}.

ollama list

Esperado: uma linha com qwen2:7b.

Passo 2: o teste que importa

As conferências acima checam as peças. Este script checa o conjunto — inclusive uma pergunta de verdade ao modelo, pelo mesmo caminho que os agentes da Unidade 1 vão usar.

Copie o arquivo verificar_ambiente.py (distribuído junto com esta apostila) para a sua pasta agentes e rode:

python verificar_ambiente.py

O script confere, nesta ordem:

A versão do Python.
Se o ambiente virtual está de fato ativo.
Se smolagents e litellm estão instalados.
Se o SDK do mcp está na versão certa — a 1.x. Só é usado na Unidade 3.
Se o servidor do Ollama responde.
Se o modelo qwen2:7b foi baixado.
Se o modelo responde a uma pergunta real via LiteLLMModel.

Ele para na primeira falha e explica o que fazer. Saída esperada quando está tudo certo:

Verificando o ambiente do curso...

[ OK ] Python 3.12.10
[ OK ] Ambiente virtual ativo em C:\Users\seu.nome\agentes\.venv
[ OK ] smolagents 1.26.0 e litellm instalados
[ OK ] mcp 1.29.1 (1.x, como o curso exige)
[ OK ] Servidor Ollama respondendo (versão 0.33.2)
[ OK ] Modelo qwen2:7b disponível

   Enviando uma pergunta ao modelo (a primeira demora — ele está carregando)...
[ OK ] O modelo respondeu: 'funcionando'

Tudo pronto. Você pode começar a Unidade 1.

Nota

A linha do mcp é a única que aceita ausência. Se você pulou esse pacote na instalação, ela aparece assim, e o script segue:

[ -- ] mcp não instalado (só é preciso na Unidade 3)

O que não passa é o mcp instalado na versão 2.x, que quebra o cliente do smolagents lá na Unidade 3 com uma mensagem que não fala em versão nenhuma. Aí o script para:

[FALHA] mcp 2.1.1 é incompatível com o mcpadapt, que o smolagents usa.

   Como resolver: Rode: pip install "mcp<2" (com aspas — sem elas o PowerShell lê o '<' como redirecionamento).

Nota

O passo 6 pode levar de 10 a 60 segundos na primeira execução — o modelo está sendo carregado do disco para a memória. Não é travamento. Se passar de 2 minutos, veja problemas comuns.

Se aparecer [FALHA] em algum ponto, leia a linha "Como resolver" logo abaixo e consulte a seção de problemas comuns.

Passo 3: entendendo a ponte entre as peças

Vale entender o que o passo 6 do script fez, porque é o mecanismo central do curso inteiro.

from smolagents import LiteLLMModel

modelo = LiteLLMModel(
    model_id="ollama_chat/qwen2:7b",
    api_base="http://127.0.0.1:11434",
    num_ctx=8192,
)

Cada parâmetro:

model_id="ollama_chat/qwen2:7b" — o prefixo ollama_chat/ diz ao LiteLLM qual "tradutor" usar. Depois da barra vem o nome exato do modelo, como aparece em ollama list. Se você baixou o qwen2.5:3b, é ele que entra aqui.
api_base="http://127.0.0.1:11434" — o endereço do servidor local do Ollama. É a linha que mantém tudo dentro da sua máquina.
num_ctx=8192 — a janela de contexto: quantos tokens o modelo consegue considerar de uma vez, somando pergunta e resposta. Agentes consomem contexto rápido, porque o histórico de pensamentos, ações e observações vai se acumulando a cada passo. O padrão do Ollama (2048) é pequeno demais para isso. Se você aumentar muito esse número, o consumo de memória sobe junto.

Por que essa troca funciona sem mudar mais nada

O curso original usa InferenceClientModel, que fala com os servidores da Hugging Face. Nós usamos LiteLLMModel apontado para o Ollama. Só isso muda. Todo o resto do código de Agents — Tools, prompts, o ciclo de raciocínio — permanece idêntico.

Isso é possível porque o Ollama expõe uma API no mesmo formato da API da OpenAI, que virou o padrão de fato do setor. O smolagents não precisa saber onde o modelo está rodando; ele só precisa de um objeto que saiba receber mensagens e devolver respostas.

Guarde esse desenho — ele é o motivo de você conseguir trocar o modelo depois sem reescrever seus agentes.

Checklist final

Antes de seguir para a Unidade 1, confirme:

[ ] python --version responde 3.10 a 3.13
[ ] O cursor do terminal mostra (.venv)
[ ] (Get-Command python).Source termina em \.venv\Scripts\python.exe
[ ] ollama list mostra o modelo baixado
[ ] python verificar_ambiente.py chega ao final sem nenhum [FALHA]
[ ] Você sabe reativar o ambiente amanhã, em um terminal novo:

powershell cd C:\Users\$env:USERNAME\agentes .\.venv\Scripts\Activate.ps1

Ambiente pronto. A partir daqui é conteúdo: Unidade 1 — Introdução aos Agentes.