Instalando Python e criando o ambiente virtual (Windows)

Esta seção não existe no curso original — lá se assume que o Python já está instalado e que você está no Linux. Aqui vamos do zero, no Windows, sem WSL e sem precisar de acesso de administrador.

Ao final desta seção você terá:

1. Python instalado e reconhecido pelo terminal.
2. Uma pasta de trabalho para o curso.
3. Um ambiente virtual (.venv) ativo dentro dela.
4. As bibliotecas do curso instaladas — sem bagunçar o resto da máquina.

Passo 0: abrir o PowerShell

Todo o curso usa o PowerShell, não o Prompt de Comando antigo (cmd).

Pressione a tecla Windows, digite PowerShell e abra o Windows PowerShell.

Você verá um cursor assim:

PS C:\Users\seu.nome>

O PS no início confirma que é PowerShell. Esse trecho antes do > é a pasta atual — ele muda conforme você navega.

Passo 1: verificar se o Python já existe

Antes de instalar, confira. Rode:

python --version

Três resultados possíveis:

Se apareceu uma versão 3.14 ou superior, ela é muito nova e várias bibliotecas do curso ainda não têm suporte. Instale a 3.12 seguindo o Passo 2 — as duas versões convivem sem conflito.

Passo 2: instalar o Python

Escolha um dos caminhos abaixo. O caminho A é o mais rápido; o B é o mais confiável em máquina corporativa travada.

Caminho A — pelo winget (linha de comando)

O winget já vem no Windows 11. Rode:

winget install --id Python.Python.3.12 --scope user

O --scope user instala na sua conta de usuário, sem pedir senha de administrador.

Caminho B — pelo instalador oficial

1. Acesse python.org/downloads/windows.
2. Baixe o instalador Windows installer (64-bit) da versão 3.12.x.
3. Execute o arquivo baixado.
4. Na primeira tela, marque a caixa Add python.exe to PATH. Ela fica no rodapé da janela e vem desmarcada. Se você esquecer, o terminal não vai encontrar o Python e você terá que reinstalar.
5. Clique em Install Now.

Confirmar a instalação

Feche o PowerShell e abra de novo — o terminal só enxerga o PATH novo depois de reiniciar. Então rode:

python --version

Deve responder Python 3.12.x.

Passo 3: criar a pasta do curso

Vamos manter tudo do curso em uma pasta só:

mkdir C:\Users\$env:USERNAME\agentes

E entrar nela:

cd C:\Users\$env:USERNAME\agentes

$env:USERNAME é uma variável do PowerShell que já contém o seu nome de usuário — não precisa digitá-lo.

Repare que o cursor mudou:

PS C:\Users\seu.nome\agentes>

Passo 4: o que é um ambiente virtual e por que ele importa

Se você instalar bibliotecas direto no Python do sistema, todos os projetos passam a compartilhar as mesmas versões. Um projeto que precisa da versão 1 e outro que precisa da versão 2 entram em conflito — e a máquina fica em um estado em que nada funciona direito.

Um ambiente virtual é uma pasta que contém uma cópia isolada do Python e das bibliotecas daquele projeto. Vantagens:

• O que você instala para o curso não afeta nada mais na máquina.
• Se der errado, você apaga a pasta .venv e começa de novo. Sem resíduo.
• Não exige administrador.

É a prática padrão em Python. Todo projeto tem o seu.

Passo 5: criar o ambiente virtual

Dentro da pasta agentes:

python -m venv .venv

Isso cria uma pasta oculta .venv. Leva alguns segundos e não imprime nada quando dá certo.

Passo 6: liberar a execução de scripts no PowerShell

Por padrão, o Windows bloqueia a execução de qualquer script do PowerShell. O script que ativa o ambiente virtual é um deles — então, sem este passo, o próximo comando falha com:

não pode ser carregado porque a execução de scripts foi desabilitada neste sistema

Para liberar, rode:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Responda S (ou Y) quando ele pedir confirmação.

O que este comando faz, exatamente: ele passa a permitir que scripts criados na sua própria máquina sejam executados. Scripts baixados da internet continuam bloqueados, a menos que tenham assinatura digital válida. O -Scope CurrentUser limita a mudança à sua conta de usuário — nenhuma configuração da máquina ou de outros usuários é alterada, e por isso não é pedida senha de administrador.

RemoteSigned é a configuração recomendada pela Microsoft para estações de desenvolvimento. Não use Unrestricted nem Bypass — essas desligam a proteção contra scripts baixados, que é justamente a que interessa aqui.

Para conferir como ficou:

Get-ExecutionPolicy -List

A linha CurrentUser deve mostrar RemoteSigned.

Passo 7: ativar o ambiente virtual

.\.venv\Scripts\Activate.ps1

Se funcionou, o cursor ganha um prefixo (.venv):

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

Esse (.venv) é a sua confirmação visual de que está no ambiente certo. Sempre confira se ele está lá antes de instalar qualquer coisa ou rodar qualquer código do curso.

Para desativar, quando quiser: deactivate.

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

Passo 8: instalar as bibliotecas do curso

Com o (.venv) visível, primeiro atualize o instalador de pacotes:

python -m pip install --upgrade pip

Depois instale o que o curso usa:

pip install "smolagents[litellm,mcp]" "mcp<2" websockets python-dotenv

O que veio junto:

• smolagents — a biblioteca de agentes da Hugging Face, usada a partir da Unidade 1.
• [litellm] — o extra que permite ao smolagents conversar com o Ollama. Sem ele, o smolagents só fala com a nuvem da Hugging Face.
• [mcp] — o extra que permite ao smolagents usar Tools que moram fora do script, pelo protocolo MCP. Só entra em cena na Unidade 3, mas instalar tudo de uma vez poupa uma segunda briga com o proxy.
• "mcp<2" — a versão do SDK do MCP. As aspas são obrigatórias: sem elas o PowerShell lê o < como redirecionamento de arquivo. O porquê do limite está logo abaixo.
• websockets — dependência que o adaptador de MCP importa sem declarar. Sem ela, o erro que aparece fala de outra coisa (ver a Unidade 3).
• python-dotenv — para guardar configurações fora do código.

A instalação baixa algumas centenas de megabytes e pode levar alguns minutos.

Se a instalação falhar por causa do proxy da rede

Em rede corporativa, o pip costuma travar com Connection timed out ou erro de certificado SSL. Peça ao setor de TI o endereço do proxy e use:

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

Passo 9: registrar as dependências

Boa prática: gravar em um arquivo exatamente quais versões você instalou. Assim, outra pessoa (ou você mesmo em outra máquina) reproduz o mesmo ambiente.

pip freeze > requirements.txt

Para recriar o ambiente em outro computador, bastaria repetir os passos 5 a 7 e rodar pip install -r requirements.txt.

Resumo dos comandos

Instalação, uma única vez:

mkdir C:\Users\$env:USERNAME\agentes
cd C:\Users\$env:USERNAME\agentes
python -m venv .venv
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install "smolagents[litellm,mcp]" "mcp<2" websockets python-dotenv

Todo dia, ao começar a trabalhar:

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

Ambiente pronto. Agora falta o modelo de linguagem: siga para Instalando o Ollama.