Problemas comuns e como resolver

Esta seção reúne os erros que mais aparecem na preparação do ambiente no Windows. Procure a mensagem de erro que você recebeu.

python não é reconhecido como nome de cmdlet

python : O termo 'python' não é reconhecido como nome de cmdlet, função, arquivo de script ou programa operável.

Causa: o Python não está instalado, ou foi instalado sem marcar Add python.exe to PATH.

Solução:

1. Feche e reabra o PowerShell. O terminal só enxerga alterações no PATH depois de reiniciado — este é o motivo mais comum, e o mais fácil de resolver.
2. Se persistir, teste o lançador do Windows: py --version. Se ele responder, o Python existe mas está fora do PATH; use py no lugar de python em todos os comandos, ou reinstale marcando a caixa.
3. Se nem py responder, o Python não está instalado. Volte para o Passo 2 da instalação.

Abre a Microsoft Store ao digitar python

Causa: o Windows vem com um atalho falso (App Execution Alias) que redireciona python para a loja.

Solução: instale o Python de verdade. Depois, se o problema continuar, desligue o atalho: Configurações → Aplicativos → Configurações Avançadas de Aplicativos → Aliases de execução de aplicativo e desative python.exe e python3.exe.

A execução de scripts foi desabilitada neste sistema

.\.venv\Scripts\Activate.ps1 : O arquivo ... não pode ser carregado porque a execução de scripts foi desabilitada neste sistema.

Causa: política de execução padrão do Windows (Restricted).

Solução:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Confirme com S. A explicação do que esse comando faz está no Passo 6 da instalação.

Se a TI bloqueou a mudança por política de grupo

Rode Get-ExecutionPolicy -List. Se a linha MachinePolicy mostrar algo diferente de Undefined, a configuração da máquina sobrepõe a sua e o comando acima não vai funcionar. Abra um chamado para a TI.

Enquanto isso, você pode trabalhar sem ativar o ambiente virtual. Ativar é uma conveniência: o que ela faz é colocar a pasta .venv\Scripts no início do PATH, para que python e pip apontem para o ambiente. Você consegue o mesmo efeito chamando os executáveis pelo caminho completo:

.\.venv\Scripts\python.exe -m pip install "smolagents[litellm,mcp]" "mcp<2" websockets python-dotenv
.\.venv\Scripts\python.exe meu_script.py

Funciona igual, sem depender de script nenhum. Só é mais verboso.

Only one usage of each socket address... ao rodar ollama serve

Error: listen tcp 127.0.0.1:11434: bind: Only one usage of each socket address (protocol/network address/port) is normally permitted.

Causa: o Ollama já está rodando. No Windows, o instalador o configura para iniciar junto com o sistema — diferente do Linux, onde o curso original assume que você precisa subir o servidor à mão.

Solução: não faça nada. Ignore o ollama serve e siga o curso. Para confirmar que está tudo certo:

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

Se retornar um JSON com a versão, está funcionando.

sudo ou lsof não encontrado

sudo : O termo 'sudo' não é reconhecido...

Causa: sudo e lsof são comandos do Linux. O curso original é escrito para Linux/macOS.

Solução: use os equivalentes do PowerShell.

O pip install trava ou dá erro de SSL

Could not fetch URL https://pypi.org/... : There was a problem confirming the ssl certificate

ou

WARNING: Retrying (Retry(total=4, ...)) after connection broken by 'ConnectTimeoutError'

Causa: o proxy da rede corporativa está entre você e o repositório de pacotes.

Solução: peça o endereço do proxy à TI e use:

pip install --proxy http://usuario:senha@proxy.tjrj.jus.br:8080 "smolagents[litellm,mcp]" "mcp<2" websockets python-dotenv

Se o erro for especificamente de certificado, pode ser que o proxy faça inspeção de tráfego com um certificado próprio. A solução correta é apontar o pip para o certificado da instituição, que a TI fornece:

pip config set global.cert C:\caminho\para\certificado-tjrj.crt

O ollama pull fica parado em 0%

Causa: normalmente também é o proxy — o Ollama não lê as configurações de proxy do pip.

Solução: informe o proxy pelas variáveis de ambiente e reinicie o Ollama:

[Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://proxy.tjrj.jus.br:8080", "User")

Depois saia do Ollama pelo ícone na bandeja do sistema e abra-o de novo pelo menu Iniciar, para que ele leia a variável nova.

O modelo responde muito devagar

Causa: o modelo está rodando na CPU. É o comportamento normal em uma estação de trabalho sem placa de vídeo dedicada.

O que ajuda:

1. Feche o navegador antes de rodar os exercícios. Ele costuma ser o maior consumidor de RAM da máquina.
2. Use um modelo menor: ollama pull qwen2.5:3b ocupa cerca de 2 GB no lugar de 4,4 GB e responde bem mais rápido.
3. Mantenha o modelo carregado. A primeira pergunta sempre demora mais, porque o modelo está sendo lido do disco para a memória. Depois de 5 minutos ocioso, o Ollama o descarrega. Para manter carregado por uma hora:

powershell $env:OLLAMA_KEEP_ALIVE = "1h"

Essa variável precisa estar definida antes de o Ollama iniciar, então reinicie-o depois.

ModuleNotFoundError: No module named 'smolagents'

Causa: quase sempre é o ambiente virtual não estar ativo. Você instalou a biblioteca dentro do .venv, mas está rodando o Python de fora dele.

Solução: confira se o seu cursor mostra o prefixo (.venv):

(.venv) PS C:\Users\seu.nome\agentes>

Se não mostrar, ative:

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

Para ter certeza de qual Python está sendo usado:

(Get-Command python).Source

O caminho tem que terminar em \.venv\Scripts\python.exe. Se apontar para outro lugar, o ambiente não está ativo.

O ambiente virtual não ativa e a pasta .venv não tem Scripts

Causa: o ambiente virtual foi criado dentro do WSL (Linux), e não no Windows. Um ambiente virtual guarda caminhos absolutos para o interpretador que o criou — ele não é portável entre sistemas.

Como reconhecer: abra a pasta .venv. Se ela tem bin/ e lib64/ em vez de Scripts/ e Lib/, é um ambiente Linux. O arquivo .venv\pyvenv.cfg confirma — vai mostrar home = /usr/bin.

Solução: apague a pasta e recrie pelo PowerShell.

Remove-Item -Recurse -Force .venv
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install "smolagents[litellm,mcp]" "mcp<2" websockets python-dotenv

TypeError: string indices must be integers, not 'str'

File "...\smolagents\models.py", line 388, in get_clean_message_list
    content = message.content[0]["text"]
TypeError: string indices must be integers, not 'str'

Causa: mudança de API do smolagents. Até a versão 1.19, o campo content de uma mensagem era uma string simples. A partir da 1.20, passou a ser uma lista de blocos tipados. Muito exemplo que circula na internet — inclusive material do curso original escrito antes da mudança — ainda usa o formato antigo.

Formato antigo (quebra nas versões atuais):

mensagem = {"role": "user", "content": "Qual é a capital da França?"}

Formato atual:

mensagem = {
    "role": "user",
    "content": [{"type": "text", "text": "Qual é a capital da França?"}],
}

A lista existe porque uma mensagem pode misturar tipos de conteúdo — texto e imagem, por exemplo. Cada elemento declara o seu type.

Para conferir sua versão:

python -c "import smolagents; print(smolagents.__version__)"

Erros do MCP na Unidade 3

Os três erros abaixo aparecem só quando você chega na Unidade 3, e os três são a mesma doença: versão. Estão aqui porque, quando acontecerem, é nesta página que você vai procurar.

cannot import name 'streamablehttp_client'

ImportError: cannot import name 'streamablehttp_client' from 'mcp.client.streamable_http'

Causa: você tem o mcp 2.x instalado. O mcpadapt — a peça que o smolagents usa para falar MCP — só funciona com o 1.x, e não existe versão dele que funcione com o 2.x. A mensagem não diz nada disso.

Solução:

pip install "mcp<2"

As aspas são obrigatórias no PowerShell: sem elas, o < vira redirecionamento de arquivo.

Please install 'mcp' extra to use MCPClient

ModuleNotFoundError: Please install 'mcp' extra to use MCPClient: `pip install "smolagents[mcp]"`

Causa: a mensagem está errada. O extra [mcp] pode estar instalado; o que falta é o websockets, que o mcpadapt importa sem declarar como dependência.

Solução:

pip install websockets

No module named 'mcp.server.fastmcp'

Causa: de novo o mcp 2.x, que renomeou FastMCP para MCPServer. O código do curso usa o nome 1.x.

Solução: a mesma — pip install "mcp<2".

pip list | Select-String "mcp|smolagents|litellm|websockets"

Nada acima resolveu

Junte estas informações antes de pedir ajuda — elas respondem 90% das perguntas de diagnóstico:

python --version
(Get-Command python).Source
pip list
curl http://127.0.0.1:11434/api/version
ollama list
Get-ExecutionPolicy -List

Copie a saída dos seis comandos junto com a mensagem de erro completa — não apenas a última linha.