LangChain para Pydantic AI: migre uma fatia sem perder contratos

ANÁLISE EDITORIAL

Trocar LangChain ou LangGraph por Pydantic AI não é uma troca de nomes de classes. Uma aplicação pode depender de histórico de mensagens, ferramentas com efeitos externos, eventos de streaming e retomada após interrupção. Se a migração preservar apenas a resposta de um exemplo simples, ela ainda pode quebrar o contrato usado pelo produto. A Skill oficial Migrating LangChain to Pydantic AI, publicada pelo projeto Pydantic AI, orienta um agente a começar pelo comportamento observado, escolher uma fatia pequena e demonstrar o que foi preservado. O pacote local desta página é somente documentação; não altera código nem instala bibliotecas.

O que a Skill realmente faz

O SKILL.md pede ao agente que leia o aplicativo existente, identifique versões instaladas e siga uma requisição representativa da entrada até a saída pública. O percurso inclui prompts, busca e recuperação, chamadas ao modelo, ferramentas, estado, persistência, interrupções, eventos e observabilidade quando esses elementos existirem. Só depois disso a Skill propõe um destino. Para uma cadeia determinística, pode bastar Python comum; um agente com ferramentas pode virar um pydantic_ai.Agent; um grafo com desvios tipados pode justificar pydantic_graph. A Skill não manda converter tudo em agente.

Se o projeto usa Deep Agents, a análise se amplia para planejamento, arquivos, shell, sandbox, memória, subagentes, aprovação e outras capacidades que o aplicativo de fato utiliza. O material distingue o loop do agente da infraestrutura do produto. Filas, autenticação, banco de dados, agendadores e adaptadores de transporte ficam no lugar quando estão fora da fatia autorizada. As seis referências Markdown do pacote detalham mapeamento de conceitos, lacunas semânticas, Deep Agents, receitas para lacunas concretas, verificação com Logfire e corte para produção. Elas não são um conversor automático.

Para quem serve e quando não serve

A Skill é útil para quem mantém uma aplicação Python com LangChain, LangGraph ou Deep Agents e já consegue localizar seus pontos de entrada, testes e dependências. Também ajuda uma equipe que precisa estimar o risco de uma migração antes de alterar a base inteira. O foco é preservar o contrato do aplicativo: formato de requisição e resposta, erros, eventos, chamadas síncronas e assíncronas, aprovações e efeitos externos que os consumidores realmente usam.

Ela não é um tutorial genérico de Pydantic, nem um comando que migra repositórios sem contexto. Não é indicada como atalho quando o objetivo é só atualizar uma dependência ou quando a equipe não pode inspecionar a aplicação atual. Uma migração de fluxo persistente ou com aprovação humana precisa de decisões sobre estado e retomada; se essas decisões mudam a arquitetura ou o comportamento do usuário, a Skill manda apresentá-las ao responsável antes de implementar.

Compatibilidade e pré-requisitos

O pacote contém um SKILL.md com frontmatter e seis arquivos relativos em references/. Ele pode ser lido por um agente que suporte esse formato e consiga acessar os documentos relativos; o caminho de instalação depende do cliente. Não há requisito de uma conta Pydantic para ler a Skill. Para aplicar o roteiro, tenha uma cópia controlada do código Python, os arquivos de dependência, os testes existentes e permissão para executar ao menos a linha de base em ambiente de desenvolvimento.

A documentação atual de instalação do Pydantic AI exige Python 3.11 ou mais recente e mostra pip install pydantic-ai ou uv add pydantic-ai. O próprio SKILL.md orienta preferir pydantic-ai-slim com extras específicos quando o conjunto de integrações é limitado. Nenhuma dessas bibliotecas vem no ZIP local. O pydantic-ai-harness só deve ser adicionado se a fatia observada usa funções de harness, como arquivos, memória, planejamento, execução de comandos ou subagentes. Antes de escolher API, versão ou provedor, confira o ambiente do projeto e a documentação correspondente à versão instalada.

Instalação do pacote e configuração

Baixe o ZIP no card local, compare o SHA-256 exibido e examine os nove arquivos antes de copiá-los. Eles são SKILL.md, LICENSE, ORIGEM.md e seis referências Markdown. Em um cliente que lê Skills por projeto na convenção .agents/skills/, copie a pasta migrating-langchain-to-pydantic-ai para esse diretório, preservando references/. Outros clientes usam caminhos próprios, portanto confirme a documentação do seu agente e não sobrescreva uma pasta homônima sem comparar os arquivos. O botão separado de repositório leva ao diretório oficial fixado no commit auditado.

Para trabalhar com a aplicação, crie ou use um ambiente Python isolado e resolva as dependências do projeto antes de alterar seu código. Se Pydantic AI ainda não estiver presente, instale a distribuição apropriada seguindo a documentação oficial, registre a versão escolhida e faça um teste simples de importação no mesmo ambiente dos testes. Configure o provedor de modelo somente por meios aprovados pelo projeto, como variáveis de ambiente ou cofre de segredos; não cole chaves em prompts ou no SKILL.md. A execução de modelos e observabilidade podem usar serviços externos e gerar custos. O pacote documental não faz login, não lê seu repositório e não ativa o Logfire por conta própria.

Primeiro uso e resultado esperado

Um primeiro pedido pode ser: “Leia esta Skill e apenas analise o módulo de atendimento que usa LangChain. Identifique a versão instalada, os pontos de entrada, os consumidores, os testes e uma requisição representativa. Liste o contrato público, os efeitos externos e uma fatia mínima para migrar. Não altere arquivos nem envie dados a serviços externos. Marque o que não conseguiu verificar.” Assim, a primeira entrega é um inventário revisável, não uma migração presumidamente pronta.

Com o inventário aprovado, peça uma proposta de mudança limitada a essa fatia e testes de caracterização para o comportamento antigo. Depois, autorize a implementação em branch ou cópia controlada. O resultado esperado é um diff pequeno acompanhado de testes que mostrem o contrato preservado, das diferenças aceitas e dos riscos restantes. A referência VERIFICATION-AND-CUTOVER.md separa alegações verificadas, não verificadas e decisões intencionais. O Bastidores não executou uma migração de aplicativo real e não afirma paridade por ter empacotado a Skill.

Permissões e riscos que exigem revisão

O ZIP só traz Markdown e licença, mas um agente com acesso ao projeto pode ler código privado, executar testes, instalar pacotes, alterar arquivos e chamar modelos externos. Restrinja a pasta, o terminal e a rede ao necessário. Revise as ferramentas que enviam prompts, dados de cliente ou logs a provedores. Não substitua automaticamente o sistema de observabilidade existente por Logfire: a Skill pede uma comparação de correlação, painéis, alertas, retenção, exportação e privacidade antes da decisão.

Persistência, interrupções, aprovação e chamadas com efeitos colaterais são pontos de maior risco. A referência de lacunas semânticas alerta que APIs parecidas podem ter diferenças de estado, streaming e tentativas. Uma ferramenta repetida após falha pode duplicar uma ação externa se não houver proteção adequada. Para um fluxo com retomada, exija teste de reinício, correlação, autorização e idempotência na medida em que o sistema original prometia essas propriedades. Não remova LangChain, LangGraph ou Deep Agents até confirmar que nenhum caminho preservado depende deles.

Erros comuns e como investigar

Se o agente não carregar a Skill, confira o nome da pasta, o frontmatter de SKILL.md e os seis caminhos em references/. Se um link relativo abrir vazio, veja se o ZIP foi extraído com a estrutura completa; copiar só o arquivo principal perde parte do roteiro. Se a instalação funcional falhar, confira Python 3.11+, ambiente virtual, extras do provedor e resolução limpa das dependências. Um import que funciona em uma máquina antiga não prova que a nova árvore de dependências está correta.

Se a nova implementação responder corretamente mas o front-end ou outro consumidor quebrar, volte ao inventário de formato, nomes de parâmetros, erros e eventos. Se a aprovação ou a retomada se comportar de outro jeito, consulte SEMANTIC-GAPS.md e WORKAROUND-RECIPES.md, registre a diferença e teste a decisão antes de prosseguir. Se os testes cobrirem só uma resposta feliz, acrescente casos para ferramentas, falhas e limites que a fatia realmente usa. Um contrato não testado deve ser chamado de não verificado, não de equivalente.

Versão, licença e download local

Esta cópia está fixada no commit 1edeed76af08df1d3e9256be96e9e4a333b91515 do repositório pydantic/pydantic-ai, mantido por Pydantic Services Inc. Na consulta de 18/10/2026, o repositório tinha 20.710 estrelas; isso é adoção do repositório, não contagem de instalações da Skill. A licença MIT permite redistribuir a documentação com seu aviso, preservado em LICENSE. O arquivo ORIGEM.md registra URLs, commit e SHA-256 dos oito arquivos originais.

O download próprio do Bastidores contém somente nove arquivos documentais. Não há SDK, executáveis, scripts, binários, dependências ou credenciais. Confira o SHA-256 do ZIP no card antes de extrair. O link para o repositório oficial é uma ação diferente e abre a fonte original para comparação. A capa é uma ilustração exclusiva, não uma captura do produto; esta página não apresenta imagem de uma migração real.

Fontes primárias

• SKILL.md oficial no commit auditado
• Seis referências oficiais da Skill
• Licença MIT original
• Instalação do Pydantic AI
• Conceito de agentes no Pydantic AI