Python agentes IA Windows · 2026-07-11

Python Agentes IA Windows: Ambiente Completo com Claude Code e Codex

Tutorial completo para configurar Python agentes IA Windows com WSL, venv, Django e FastAPI. Aprenda a integrar Claude Code e Codex no seu ambiente Python.

Configurar Python agentes IA Windows do zero pode parecer trivial, mas a realidade é que a combinação de WSL, ambientes virtuais, frameworks web e agentes de IA exige algumas decisões arquiteturais que fazem diferença no dia a dia. Este tutorial mostra o passo a passo para montar um ambiente Python produtivo no Windows 11 — com WSL 2, venv bem configurado, Claude Code e Codex integrados — e aplicar tudo isso em exemplos reais com Django e FastAPI.

Se você já tentou usar agentes de IA num projeto Python no Windows e esbarrou em problemas de path, permissão ou dependências conflitantes, este guia é para você. Vamos cobrir cada etapa com comandos testados e explicações do porquê cada escolha foi feita.

Sumário

O cenário: Python no Windows precisa de estratégia
Python no Windows: WSL 2 como base
venv e dependências: ambientes isolados para agentes de IA
Claude Code no ambiente Python
Codex no ambiente Python
Exemplo prático: API Django com agentes de IA
Exemplo prático: API FastAPI com agentes de IA
FAQ — Perguntas Frequentes
Monte seu ambiente Python com agentes hoje

O cenário: Python no Windows precisa de estratégia

Desenvolver projetos Python — especialmente aqueles que envolvem agentes de IA como Claude Code e Codex — no Windows apresenta desafios que no Linux simplesmente não existem. Paths com barras invertidas, diferenças de permissão, incompatibilidade de pacotes com bindings nativos e a ausência de um gerenciador de pacotes consistente são obstáculos reais.

Muitos desenvolvedores recorrem ao WSL (Windows Subsystem for Linux) como solução, e com razão: ele oferece um kernel Linux real rodando dentro do Windows, com desempenho próximo ao nativo. Mas a decisão não termina aí. Você ainda precisa definir:

Onde os agentes de IA vão rodar (dentro do WSL ou no Windows?).
Como os ambientes virtuais se comportam entre os dois sistemas de arquivos.
Qual framework web (Django, FastAPI, Flask) escolher para os exemplos com agentes.
Como garantir que Claude Code Python e Codex Python enxerguem o mesmo ambiente.

A boa notícia: com uma configuração bem pensada, você elimina esses problemas de uma vez e passa a desenvolver com agentes de IA tão naturalmente quanto faria no Linux nativo.

Imagem sugerida: Diagrama de arquitetura mostrando Windows 11 + WSL 2 + Python + agentes de IA (Claude Code e Codex) em camadas, com setas indicando comunicação entre os componentes.

Python no Windows: WSL 2 como base

O WSL 2 é a espinha dorsal de qualquer setup de Python WSL agentes. Diferente do WSL 1, que fazia tradução de chamadas de sistema, o WSL 2 roda um kernel Linux real dentro de uma VM leve gerenciada pelo Windows. Isso significa compatibilidade total com pacotes Python que dependem de bindings C nativos — como psycopg2, numpy, pandas e boa parte do ecossistema de IA/ML.

Instalação do WSL 2

Se você ainda não tem o WSL 2 configurado, abra o PowerShell como administrador e execute:

wsl --install -d Ubuntu-24.04

Esse comando instala o WSL 2 (se não estiver presente), baixa o Ubuntu 24.04 LTS e configura tudo automaticamente. Após a instalação, reinicie o computador e defina seu usuário/senha do Linux.

Verifique a versão do WSL:

wsl --list --verbose

A saída deve mostrar Ubuntu-24.04 com a versão 2. Se aparecer versão 1, converta com:

wsl --set-version Ubuntu-24.04 2

Python dentro do WSL

O Ubuntu 24.04 já vem com Python 3.12 instalado. Confirme:

python3 --version

Se precisar de uma versão específica (como Python 3.11 ou 3.13), use o deadsnakes PPA:

sudo add-apt-repository ppa:deadsnakes/ppa sudo apt update sudo apt install python3.11 python3.11-venv python3.11-dev

Sistema de arquivos: onde colocar o projeto

Essa é a decisão mais importante para quem usa Python agentes IA Windows. O WSL 2 tem acesso ao sistema de arquivos do Windows via /mnt/c/, mas a performance de leitura/escrita nesse caminho é significativamente mais lenta — especialmente para operações de pacotes Python (pip install, poetry lock, etc.).

Regra de ouro: mantenha seus projetos Python dentro do sistema de arquivos do WSL (ex.: /home/seu-usuario/projetos/), não no Windows (/mnt/c/Users/...). O ganho de performance em operações de I/O é de 3 a 5x em projetos com muitas dependências.

mkdir -p ~/projetos cd ~/projetos

Se você precisa acessar os arquivos pelo VS Code ou Explorer do Windows, use \\wsl.localhost\Ubuntu-24.04\home\seu-usuario\ no Explorer ou abra o projeto no VS Code com:

code ~/projetos/meu-projeto

Imagem sugerida: Captura de tela do terminal WSL mostrando a criação da pasta de projetos, verificação da versão do Python e instalação de dependências.

venv e dependências: ambientes isolados para agentes de IA

Ambientes virtuais são obrigatórios em qualquer projeto Python, e com agentes de IA isso não é diferente. O venv agentes IA precisa ser configurado corretamente para que Claude Code e Codex enxerguem as mesmas dependências que você.

Criando o ambiente virtual

Dentro do WSL, navegue até seu projeto e crie o venv:

cd ~/projetos/meu-projeto python3 -m venv .venv

Ative o ambiente:

source .venv/bin/activate

Você verá o prefixo (.venv) no terminal, indicando que o ambiente virtual está ativo.

Dependências essenciais para projetos com agentes

Seja qual for o framework web escolhido, algumas dependências são transversais a qualquer projeto Python que usa agentes de IA:

pip install python-dotenv httpx pydantic python-multipart

python-dotenv: carrega variáveis de ambiente de arquivos .env sem poluir o ambiente global.
httpx: cliente HTTP moderno (substituto do requests) com suporte a async — útil se o agente precisar fazer chamadas de API durante a execução.
pydantic: validação de dados via type hints, indispensável para garantir que os dados trocados entre o framework e o agente estejam no formato esperado.
python-multipart: necessário para receber uploads de arquivos em APIs web.

Congelando dependências

Mantenha um requirements.txt atualizado:

pip freeze > requirements.txt

Dica: pyproject.toml em vez de requirements.txt

Para projetos mais profissionais, use pyproject.toml com pip ou poetry. A estrutura mínima com pip é:

pip install --upgrade pip pip install build

Crie um pyproject.toml na raiz:

[build-system] requires = ["setuptools>=68.0"] build-backend = "setuptools.backends._legacy:_Backend" [project] name = "meu-projeto" version = "0.1.0" dependencies = [ "django>=5.0,<6.0", "djangorestframework>=3.15", "python-dotenv>=1.0", ]

Depois instale com:

pip install -e .

Isso torna seu projeto "instalável" e resolve conflitos de dependência de forma mais elegante que o requirements.txt puro.

.gitignore para projetos Python com agentes

.venv/ __pycache__/ *.pyc .env dist/ build/ *.egg-info/ .pytest_cache/

Por que isso importa para agentes de IA

Quando você chama Claude Code Python ou Codex Python dentro do seu projeto, o agente precisa executar código que depende dos pacotes instalados. Se o agente rodar fora do venv (ou no Python global do Windows), ele não encontrará Django, FastAPI ou qualquer dependência do projeto. Configurar o venv corretamente garante que o interpretador Python usado pelo agente seja exatamente o mesmo do seu ambiente de desenvolvimento.

Imagem sugerida: Terminal com o venv ativado, mostrando pip list com as dependências do projeto e a ativação com o prefixo (.venv).

Claude Code no ambiente Python

O Python Claude Code Windows é uma das combinações mais poderosas para desenvolvimento com agentes. Claude Code entende o ecossistema Python profundamente — desde a estrutura de pacotes até convenções de código como PEP 8.

Instalação do Claude Code

Dentro do WSL, instale o Claude Code via npm (já que ele é distribuído como pacote Node.js):

npm install -g @anthropic-ai/claude-code

Configure sua chave de API da Anthropic:

export ANTHROPIC_API_KEY="sua-chave-aqui"

Para persistir, adicione ao ~/.bashrc:

echo 'export ANTHROPIC_API_KEY="sua-chave-aqui"' >> ~/.bashrc source ~/.bashrc

Usando Claude Code num projeto Python

Com o venv ativo, navegue até a raiz do projeto e inicie o Claude Code:

claude

A partir daí, você pode pedir tarefas específicas para o contexto Python:

Crie um modelo Django chamado Project com campos: nome (CharField), descricao (TextField), criado_em (DateTimeField auto_now_add), usuario (ForeignKey para User do Django auth). Inclua o __str__ e a classe Meta com ordenação por -criado_em.

Claude Code analisa a estrutura do seu projeto — ele lê settings.py, verifica se o app está registrado, confere o modelo User importado — e gera o código consistente com o resto da base.

Por que Claude Code é bom para Python

Diferente de ferramentas de autocomplete ou geração de código rasa, Claude Code:

Entende o ecossistema Django/FastAPI: ele sabe que request no Django não é a mesma coisa que request no FastAPI.
Respeita convenções do projeto: se você usa black com linha de 88 caracteres, Claude Code gera código nesse formato.
Contextualiza com imports: ao sugerir um trecho, ele já inclui os imports necessários e verifica se não há conflito com os existentes.
Depura erros: mostre um traceback para o Claude Code e ele analisa a pilha de chamadas, identifica a causa raiz e sugere a correção.

Exemplo rápido

Com o Claude Code aberto no terminal do WSL, peça:

Leia o arquivo views.py, identifique gargalos de performance nas queries ao banco de dados e refatore usando select_related e prefetch_related onde aplicável. Explique cada mudança.

O agente lê o arquivo, identifica N+1 queries e reescreve as views com as otimizações adequadas — algo que um linter tradicional simplesmente não consegue fazer.

Imagem sugerida: Split screen mostrando o terminal com Claude Code analisando um arquivo Python à esquerda e o código original vs. refatorado à direita.

Codex no ambiente Python

O Codex Python (da OpenAI, disponível via Codex CLI) é complementar ao Claude Code. Enquanto Claude Code é excelente para entender contexto e refatorar, Codex se destaca na geração rápida de código repetitivo e bem estruturado.

Instalação do Codex CLI

Dentro do WSL:

npm install -g @openai/codex

Configure a chave da OpenAI:

export OPENAI_API_KEY="sua-chave-aqui"

Adicione ao ~/.bashrc para persistência.

Usando Codex num projeto Python

Com o venv ativo, dentro da pasta do projeto:

codex "Crie um serializer Django REST Framework para o model Project com todos os campos. Inclua validacao personalizada: o campo nome deve ter entre 3 e 100 caracteres, e a descricao e opcional mas nao pode ser apenas espacos em branco."

Codex gera o serializer completo com a classe Meta, os campos e os métodos validate_<campo>.

Diferenças práticas entre Claude Code e Codex no Python

Característica	Claude Code	Codex
Leitura de contexto do projeto	Excelente — lê arquivos vizinhos antes de agir	Boa — gera código autônomo com base no prompt
Geração de boilerplate	Boa, mas mais lenta	Excelente — muito rápida para código padronizado
Refatoração	Excelente — entende o fluxo do código	Razoável — prefere reescrever a refatorar
Depuração de erros	Excelente — analisa traceback completo	Boa — sugere correções com base no erro
Consumo de tokens	Moderado (contexto completo)	Leve (prompt direto)

Na prática, o melhor fluxo de trabalho é: use Codex para gerar serializers, schemas Pydantic, forms e validações; use Claude Code para estruturar views, refatorar queries e depurar erros.

Codex com type hints

Peça ao Codex para gerar código com type hints — essencial para projetos Python modernos:

codex "Crie uma funcao assincrona process_data que recebe uma lista de dicts, valida cada um com Pydantic, e retorna uma lista de objetos validados. Use type hints completos, docstring no estilo Google, e tratamento de erros com excecoes customizadas. Salve em src/utils/processors.py"

O resultado é código pronto para uso, com tipos, documentação e tratamento de erros.

Imagem sugerida: Terminal WSL mostrando Codex gerando um serializer Django REST Framework, com o arquivo resultante exibido ao lado.

Exemplo prático: API Django com agentes de IA

Vamos aplicar tudo que vimos até aqui num exemplo real: uma Django FastAPI agentes — ou melhor, primeiro vamos construir uma API de gerenciamento de tarefas com Django REST Framework, usando Claude Code e Codex como assistentes.

Setup do projeto Django

cd ~/projetos python3 -m venv .venv source .venv/bin/activate pip install django djangorestframework django-cors-headers python-dotenv django-admin startproject taskmanager . python manage.py startapp tasks

Criando o model com Claude Code

Abra o Claude Code no terminal:

Crie o model Task no app tasks com os campos: - titulo (CharField, max_length=200) - descricao (TextField, blank=True) - status (CharField com choices: 'pendente', 'em_andamento', 'concluida') - prioridade (IntegerField com choices: 1=baixa, 2=media, 3=alta, default=2) - criada_em (DateTimeField, auto_now_add) - concluida_em (DateTimeField, null=True, blank=True) - usuario (ForeignKey para User do django.contrib.auth)

Claude Code gera o modelo, registra no admin, cria o __str__ e a Meta com ordenação.

Serializer com Codex

codex "Crie um ModelSerializer para o model Task com todos os campos. Adicione validacao: titulo entre 5 e 200 caracteres, prioridade entre 1 e 3, e status so pode ser 'concluida' se tiver data em concluida_em. Salve em tasks/serializers.py"

ViewSet com Claude Code

De volta ao Claude Code:

Crie um ModelViewSet para Task com: - List/create sem autenticacao (para facilitar testes) - Acoes extras: POST /tasks/{id}/concluir/ que marca como concluida - Filtro por status via query param ?status=pendente - Retorno paginado (10 por pagina) Registre no arquivo urls.py do app usando DefaultRouter.

Testes gerados por Codex

codex "Crie test_tasks.py com testes para o endpoint /api/tasks/: 1. GET listar tasks retorna 200 com lista 2. POST criar task com dados validos retorna 201 3. POST criar task sem titulo retorna 400 4. GET /api/tasks/{id}/ task especifica retorna 200 5. POST /api/tasks/{id}/concluir/ marca como concluida Use APIClient do DRF e um banco de testes em memoria."

Resultado

Em menos de 30 minutos, você tem uma API Django REST completa com CRUD, filtros, validações e testes — tudo gerado e validado por agentes de IA, rodando dentro do WSL com o venv agentes IA corretamente configurado.

Imagem sugerida: Terminal mostrando python manage.py test com todos os testes passando (green OK), após geração com agentes de IA.

Exemplo prático: API FastAPI com agentes de IA

Agora vamos refazer o mesmo exemplo com FastAPI, para mostrar como o fluxo muda entre os frameworks. FastAPI é especialmente interessante para projetos com agentes de IA porque suporta async nativamente — ideal se o agente precisar fazer chamadas de API externas durante as requisições.

Setup do projeto FastAPI

cd ~/projetos python3 -m venv .venv-fastapi source .venv-fastapi/bin/activate pip install fastapi uvicorn sqlalchemy aiosqlite python-dotenv pydantic

Estrutura com Claude Code

Crie a estrutura de diretorios para uma API FastAPI de gerenciamento de tarefas: src/main.py (app FastAPI), src/models.py (SQLAlchemy), src/schemas.py (Pydantic), src/database.py (conexao async com SQLite), src/routes/tasks.py (rotas).

Claude Code cria a árvore de diretórios e os arquivos-base com imports corretos.

Model SQLAlchemy com Codex

codex "Crie src/models.py com o modelo Task usando SQLAlchemy 2.0: - id: Integer, primary_key, autoincrement - titulo: String(200), not null - descricao: Text, nullable - status: Enum('pendente', 'em_andamento', 'concluida'), default 'pendente' - prioridade: Integer, default 2 - criada_em: DateTime, server_default=func.now() - concluida_em: DateTime, nullable - usuario_id: Integer, ForeignKey('users.id') Use Mapped e mapped_column do SQLAlchemy 2.0 declarative mapping."

Schemas Pydantic com Codex

codex "Crie src/schemas.py com: - TaskCreate: titulo (str, min 3, max 200), descricao (Optional[str]), prioridade (int, ge 1, le 3, default 2) - TaskResponse: todos campos do model, id incluido, criada_em como datetime - TaskUpdate: todos campos opcionais Use ConfigDict do Pydantic v2 com from_attributes=True."

Rotas com Claude Code

Crie src/routes/tasks.py com router da FastAPI: - GET /tasks/ — lista tasks com paginacao (skip/limit) e filtro por status - POST /tasks/ — cria task, valida com schema TaskCreate - GET /tasks/{id} — busca por id, retorna 404 se não existir - PUT /tasks/{id} — atualiza parcial com TaskUpdate - DELETE /tasks/{id} — deleta, retorna 204 - POST /tasks/{id}/concluir — marca como concluida com data atual Use Session do SQLAlchemy via Depends(get_db) e tratamento de erros com HTTPException.

Servidor com Claude Code

Crie src/main.py que: - Instancia o FastAPI com title, description e version - Inclui o router de tasks com prefixo /api - Cria o evento startup que roda create_all() nas tabelas - Adiciona middleware CORS para desenvolvimento Configure o entrypoint para: uvicorn src.main:app --reload

Inicie o servidor:

uvicorn src.main:app --reload

Acesse http://localhost:8000/docs para ver a documentação interativa gerada automaticamente pelo FastAPI.

Comparação Django vs. FastAPI com agentes

Aspecto	Django + DRF	FastAPI
Tempo de setup com agentes	~15 min	~10 min
Código gerado por Claude Code	Models, Views, URLs	Rotas, eventos, middlewares
Código gerado por Codex	Serializers, testes	Schemas Pydantic, models SQLAlchemy
Async nativo	Parcial (via Django 5.0+)	Completo
Documentação automática	DRF browsable API + Swagger	OpenAPI + Swagger + Redoc
Curva de aprendizado com agentes	Claude Code precisa conhecer convenções Django	Mais direto, menos boilerplate

Ambos os frameworks funcionam muito bem com Django FastAPI agentes. A escolha depende do seu projeto: Django para aplicações maiores com admin nativo e ORM maduro; FastAPI para APIs mais enxutas com alto desempenho async.

Imagem sugerida: Navegador mostrando a documentação interativa do FastAPI (/docs) com os endpoints de Task listados e o schema Pydantic visível.

FAQ — Perguntas Frequentes

Preciso usar WSL para rodar agentes de IA com Python no Windows?

Não é obrigatório, mas é altamente recomendado. O WSL 2 oferece compatibilidade total com pacotes Python que dependem de bindings C nativos (numpy, pandas, psycopg2) e elimina problemas de path e permissão entre Windows e Linux. Sem WSL, você pode usar Git Bash ou PowerShell, mas enfrentará mais limitações com pacotes e compatibilidade de agentes.

Claude Code e Codex funcionam com qualquer versão do Python?

Sim, ambos funcionam com Python 3.8 a 3.13. O que importa é que o agente esteja configurado para usar o mesmo interpretador Python do seu venv. Verifique com which python3 dentro do venv e confirme que o agente está usando esse mesmo caminho.

Como fazer o Claude Code enxergar as dependências do meu venv?

Ative o venv com source .venv/bin/activate antes de iniciar o Claude Code. O agente herda o PATH do shell, então ele usará o Python e os pacotes do ambiente virtual. Para confirmar, dentro do Claude Code, peça execute python3 -c "import django; print(django.__version__)". Se o Django estiver instalado no venv, o comando funcionará.

É melhor desenvolver com Django ou FastAPI para projetos com agentes de IA?

Depende do seu projeto. Django é melhor para aplicações maiores que precisam de admin nativo, ORM maduro e ecossistema consolidado. FastAPI é superior para APIs mais enxutas, com alto desempenho async e documentação OpenAPI automática. Ambos funcionam bem com agentes de IA — a diferença está no volume de boilerplate que o agente precisará gerar.

Os agentes de IA consomem muitos tokens ao trabalhar com projetos Python grandes?

Depende do escopo da tarefa. Gerar um model ou serializer consome centenas de tokens. Refatorar um arquivo de 500 linhas pode consumir milhares. Para economizar, seja específico nos prompts ("crie apenas o serializer para o model X") em vez de genérico ("melhore o app todo"). O Claude Code também permite limitar o contexto com a flag --max-tokens.

Posso usar Claude Code e Codex simultaneamente no mesmo projeto Python?

Sim, e essa é a abordagem mais produtiva. Use Claude Code para tarefas que exigem contexto (refatoração, estruturação, depuração) e Codex para geração rápida de código repetitivo (serializers, schemas, testes). Com o Orquestra, você pode rodar ambos os agentes em terminais lado a lado no mesmo canvas, sincronizando o diretório do projeto.

Monte seu ambiente Python com agentes hoje

Configurar Python agentes IA Windows da forma certa faz toda a diferença entre um ambiente que flui e um que trava a cada esquina. Com WSL 2 como base, venv bem configurado, e Claude Code e Codex integrados, você tem um setup profissional para desenvolver projetos Django e FastAPI com o poder dos agentes de IA.

O que vimos neste tutorial:

WSL 2 como ambiente Linux nativo dentro do Windows, com performance de I/O adequada para projetos Python.
venv configurado corretamente para que os agentes de IA enxerguem as mesmas dependências que você.
Claude Code para refatoração com contexto, estruturação de views e depuração de erros.
Codex para geração rápida de serializers, schemas Pydantic e testes.
Exemplos Django e FastAPI com código gerado, validado e testado por agentes — em minutos, não horas.

O próximo passo natural é orquestrar Claude Code e Codex lado a lado, num ambiente onde você possa alternar entre eles sem perder contexto. É exatamente para isso que o Orquestra foi construído: um canvas infinito com terminais dedicados para cada agente, sincronização de diretório, histórico completo e suporte nativo ao Windows 11 — sem configuração complexa.

👉 Baixe o Orquestra para Windows 11 — gratuito por 7 dias, sem cartão de crédito.

👉 Conheça os planos para times que querem produtividade máxima com agentes de IA.

Links internos recomendados

Git hooks com agentes de IA — Automatize validações antes do commit — tutorial complementar sobre Git hooks com Claude Code e Codex
APIs REST com Agentes de IA: Tutorial Completo — desenvolva APIs REST completas com Claude Code e Codex
Automação de Deploy com Agentes de IA — pipeline completo do commit à produção com agentes
Orquestração de Agentes de IA: Guia Definitivo para 2026 — conceitos fundamentais de orquestração multi-agente
Docker no WSL 2 para Agentes de IA — configure o ambiente Docker ideal para deploys automatizados

Links externos recomendados

WSL 2 Documentation (Microsoft) — documentação oficial do Windows Subsystem for Linux
Python venv Documentation — documentação oficial de ambientes virtuais Python
Django REST Framework — documentação oficial do DRF
FastAPI Documentation — documentação oficial do FastAPI

Imagens/GIFs sugeridos para o post

Diagrama de arquitetura: Windows 11 + WSL 2 + Python + Claude Code + Codex em camadas com setas de comunicação
Setup WSL: Terminal PowerShell instalando WSL 2 com wsl --install e verificando versão
venv ativado: Terminal WSL mostrando a ativação do venv com prefixo (.venv) e pip list das dependências
Claude Code vs Codex: Tabela visual comparando os dois agentes no contexto Python (contexto, velocidade, refatoração)
Django testes: Terminal com python manage.py test mostrando todos os testes verdes
FastAPI docs: Navegador exibindo /docs com Swagger UI mostrando os endpoints de Task
Canvas Orquestra: Três terminais lado a lado: Claude Code refatorando, Codex gerando schemas, e servidor FastAPI rodando

Pronto para orquestrar seus agentes?

Baixe o Orquestra para Windows 11 e comece a coordenar seus agentes de IA em um canvas infinito. Grátis por 7 dias.

Começar teste grátis