Microsoft Local AI Agents: agentes locais com Foundry Local e Qwen

ANÁLISE EDITORIAL

Microsoft Local AI Agents é uma Skill educacional para orientar agentes que rodam no próprio computador com Foundry Local, modelos Qwen, ferramentas limitadas e busca em documentos locais. Ela não instala um modelo, não configura hardware e não transforma qualquer notebook em ambiente privado por conta própria. O valor está no roteiro: decidir o que deve permanecer local, restringir ferramentas a uma pasta, testar chamadas estruturadas e reconhecer quando um modelo pequeno não é suficiente.

A curadoria fixou o commit 01777b05e8afeba6bf5a6dbe74cc2293372d3693, publicado no repositório educacional oficial da Microsoft. Em 25 de agosto de 2026, a API do GitHub registrava 73.199 estrelas no repositório, que estava público, ativo e não arquivado. Esse número descreve o repositório inteiro, não a adoção isolada desta Skill. A licença MIT foi preservada no pacote local.

Ilustração editorial exclusiva do Bastidores da IA. Não é captura de tela, interface real, logotipo da Microsoft, modelo executado nem prova de que um ambiente esteja isolado da rede.

O que esta Skill faz de verdade

O arquivo SKILL.md organiza a Lição 17 do curso AI Agents for Beginners em instruções reutilizáveis. Ele orienta o agente a combinar quatro elementos: Foundry Local como runtime de inferência, um modelo Qwen com suporte a chamadas de ferramentas, funções locais com acesso delimitado e uma camada opcional de recuperação de documentos ou MCP.

A divisão de trabalho é importante. O modelo decide qual ferramenta usar e com quais argumentos. A ferramenta lê um arquivo, busca um trecho ou calcula um resultado. Depois, o modelo recebe a saída e continua. Esse desenho reduz a expectativa de que um modelo pequeno conheça todo o projeto, mas não elimina erros. A própria documentação de function calling do Qwen alerta que a geração nem sempre seguirá o protocolo, mesmo com um template adequado. Portanto, argumentos precisam de validação antes da execução.

A Skill também apresenta roteamento híbrido. Dados sensíveis e tarefas limitadas podem ficar no computador. Raciocínio longo e informações não sensíveis podem seguir para um modelo remoto, desde que essa saída de rede seja uma decisão explícita. Esse ponto merece destaque: instalar uma Skill local não torna automaticamente local o SDK, o servidor MCP, a ferramenta de busca ou o destino configurado pelo usuário.

Para quem serve

Ela serve a desenvolvedores, estudantes e equipes técnicas que já entendem funções, Python e o ciclo básico de um agente. O cenário mais claro é um assistente de engenharia que lê somente uma pasta de teste, consulta documentação aprovada e responde sem enviar o conteúdo ao provedor de inferência em nuvem.

Também pode ajudar quem precisa comparar um fluxo local e um fluxo remoto com critérios concretos: qualidade suficiente para a tarefa, tempo de resposta observado no próprio hardware, tamanho do modelo, uso de memória, custo operacional, possibilidade de trabalhar offline e superfície de permissões. A Skill não traz benchmark independente. Qualquer decisão de desempenho precisa de um teste local com a mesma entrada e a mesma saída esperada.

Ela não é o melhor ponto de partida para quem ainda está aprendendo o que é uma ferramenta de agente, nem para uma equipe que busca implantação em escala na nuvem. O próprio arquivo exclui esses usos e remete a outras lições do curso. Também não deve ser apresentada como solução pronta para dados regulados, porque isolamento técnico, política de retenção, logs, backups e controles do sistema operacional continuam sendo responsabilidades do ambiente.

Compatibilidade e pré-requisitos

A Skill usa o padrão aberto de Agent Skills e pode ser lida por clientes que reconheçam uma pasta com SKILL.md. O material original está em .agents/skills/local-ai-agents/. A documentação atual do VS Code também reconhece Skills de projeto em .agents/skills/, .github/skills/ e .claude/skills/, mas cada cliente pode ter regras próprias de descoberta.

Para executar o laboratório funcional, e não apenas instalar a instrução, são necessários Foundry Local, Python, o SDK correto, um modelo compatível e espaço para o download. A documentação atual da CLI trata o produto como prévia e lista instalação para Windows e macOS Apple Silicon. A página Get started with Foundry Local distingue foundry-local-sdk de foundry-local-sdk-winml e alerta que o pacote PyPI chamado apenas foundry-local é de terceiro.

Hardware não deve ser resumido a um número universal. O repositório educacional chama 8 GB de memória de mínimo realista e 16 GB ou mais de confortável, mas isso é orientação do curso, não garantia para todos os modelos. Tamanho, quantização e provedor de execução mudam a necessidade real. Antes do download, confira o alias, o tamanho e a variante indicada para CPU, GPU ou NPU.

Instalação recomendada

O ZIP do Bastidores é documental. Extraia os três arquivos, leia ORIGEM.md e preserve LICENSE. Para um projeto de teste, copie a pasta para o local de Skills reconhecido pelo seu cliente, por exemplo .agents/skills/local-ai-agents/. Não copie o arquivo para um repositório de produção sem revisar o efeito das instruções sobre o agente usado pela equipe.

Instale o runtime somente pela documentação oficial da versão atual. No Windows, a CLI oficial mostra winget install Microsoft.FoundryLocal. Depois confirme a instalação com foundry --version. Em seguida, use foundry model list para descobrir aliases disponíveis no seu equipamento. A documentação atual usa foundry chat <alias> para iniciar uma conversa e foundry server status para verificar o serviço local.

Há uma divergência que não deve ser escondida. O SKILL.md fixado ainda mostra foundry model run qwen2.5-7b-instruct e foundry service status. A referência atual da CLI mostra a família foundry chat, foundry model download e foundry server status. Não misture comandos de versões diferentes. Confira foundry --version e siga a página correspondente à instalação efetiva.

Configuração antes do primeiro uso

Crie uma pasta descartável, sem documentos de cliente, segredos ou código proprietário. Defina esse diretório como única raiz permitida para as ferramentas. Uma função de leitura precisa resolver o caminho absoluto e rejeitar qualquer resultado fora da raiz, inclusive caminhos com .., links simbólicos inesperados ou atalhos para outra unidade.

Liste as ferramentas antes de chamar o modelo. Comece somente com leitura e busca. Não ofereça exclusão, gravação, execução de comandos, instalação de pacotes ou acesso ao perfil inteiro do usuário. Se adicionar RAG com Chroma, crie um banco novo para o teste e registre onde os vetores serão gravados. Se adicionar MCP, prefira um servidor local por stdio, com comandos e diretórios explícitos. A especificação de transportes do MCP explica que, nesse modo, o cliente inicia o servidor como subprocesso.

O primeiro download do runtime, do provedor de execução e do modelo exige rede. Trabalhar offline só é possível depois que todos os componentes necessários estiverem no cache e depois de confirmar que nenhuma ferramenta, extensão, telemetria ou rota híbrida faz chamadas externas. Trate “local” como uma propriedade verificável do fluxo, não como rótulo do modelo.

Primeiro uso seguro

Escolha uma tarefa pequena: localizar uma função em três arquivos de exemplo e explicar o resultado sem alterar nada. Valide o modelo escolhido com uma conversa simples. Depois inicie o agente com apenas duas ferramentas, list_files e read_file, ambas limitadas à pasta descartável.

Antes de executar cada chamada, registre nome da ferramenta, argumentos normalizados e decisão de permitir ou negar. Não grave o conteúdo integral de documentos sensíveis no log. Para o teste, introduza deliberadamente um caminho fora da raiz e confirme que a ferramenta devolve acesso negado. Em seguida, peça ao modelo para ler um arquivo inexistente e verifique se a falha aparece como falha, sem conteúdo inventado.

Se o fluxo passar, acrescente busca local sobre um conjunto curto de documentos. Mantenha os trechos recuperados visíveis na resposta para conferência. Só depois avalie um MCP local. A Lição 17 fixada e o notebook do mesmo commit mostram o laboratório completo. O Bastidores não executou esse notebook nesta curadoria e não apresenta resultado de desempenho.

Resultado esperado

Ao final do primeiro teste, o resultado esperado é um agente que recebe uma pergunta, escolhe uma ferramenta permitida, lê somente a pasta de teste, devolve uma resposta sustentada pelo arquivo e rejeita caminhos fora do escopo. O log deve permitir conferir qual ferramenta foi chamada sem expor dados desnecessários.

Também deve ficar claro quando o modelo não consegue concluir. Uma resposta segura pode pedir uma fonte adicional, limitar a conclusão ou devolver erro de ferramenta. Fluidez não é critério suficiente. Compare a resposta com o arquivo original e marque omissões, argumentos inválidos e chamadas que precisaram de correção.

Se o objetivo for offline, repita o teste sem rede somente depois dos downloads. Observe se o runtime inicia, se o modelo está no cache e se todas as ferramentas continuam funcionais. Não interprete uma conversa local como prova de que o fluxo inteiro não realizou conexões.

Permissões e riscos

A Skill é texto, mas orienta software que lê arquivos, baixa modelos, abre um serviço local, grava cache e pode iniciar subprocessos. O modelo executa com as permissões do processo que o hospeda. Por isso, a barreira principal é o código da ferramenta, não uma promessa do prompt.

Modelos e dependências ocupam disco e podem consumir memória significativa. Confira o cache antes e depois. Não remova modelos automaticamente. Uma rota híbrida pode enviar entradas para a nuvem; um MCP pode acessar rede; uma ferramenta de Git pode alcançar credenciais; e uma pasta aparentemente inofensiva pode conter .env, chaves ou histórico. Exclua esses alvos e teste com conta sem privilégios administrativos quando possível.

Chamadas de ferramenta também são dados não confiáveis. O modelo pode montar argumentos errados, e documentos recuperados podem conter instruções maliciosas. Valide schema, caminho, tamanho e tipo de arquivo. Para qualquer escrita ou ação externa, crie uma etapa separada com prévia, diff e confirmação humana explícita.

Erros comuns

O comando da Skill não existe na CLI instalada

Provavelmente há diferença de versão. Rode foundry --version, consulte a referência atual da CLI e use foundry model list antes de escolher o alias. Não troque nomes de comando por tentativa em um ambiente importante.

O servidor local não responde

A documentação atual recomenda conferir foundry server status e, em erros de conexão após instalação, usar foundry server restart. Registre a versão e a mensagem exata. Não reinstale nem limpe cache como primeiro passo.

O pacote Python está errado

Use os nomes documentados pela Microsoft. foundry-local-sdk e foundry-local-sdk-winml são os pacotes esperados conforme plataforma. O pacote foundry-local sem o sufixo não é o SDK da Microsoft.

O modelo chama a ferramenta com JSON inválido

Reduza o número de ferramentas, simplifique os schemas e valide argumentos antes de executar. A documentação do Qwen afirma que chamadas bem formadas não são garantidas em todos os cenários. Não conserte silenciosamente um caminho ou comando com efeito externo.

O agente lê além da pasta

Interrompa o teste. Corrija a resolução de caminhos no código e repita com casos de travessia, links e caminhos absolutos. Um prompt dizendo “use apenas esta pasta” não substitui uma verificação programática.

Versão auditada e download local

A curadoria usou o commit 01777b05e8afeba6bf5a6dbe74cc2293372d3693, de 18 de agosto de 2026. O caminho auditado foi .agents/skills/local-ai-agents/SKILL.md. A licença MIT está no arquivo LICENSE do repositório.

O download local contém exatamente SKILL.md, LICENSE e ORIGEM.md. O SHA-256 do ZIP é 309326997411b9b9421d175bffe63a2ac56664b61adf5d7f362efd1e0f2d4f68. O pacote não inclui runtime, modelo, notebook, scripts, dependências, dados ou credenciais. O botão do repositório oficial é separado porque o curso completo e as instruções atuais devem permanecer na fonte canônica.

Resultado esperado e limite final

Esta Skill é útil quando ajuda a transformar “quero um agente local” em um teste verificável: versão conhecida, modelo escolhido pelo catálogo real, ferramentas mínimas, diretório delimitado, saídas conferidas e rede tratada como variável explícita.

Ela não prova privacidade, qualidade ou economia. A CLI está em prévia, comandos podem mudar e o repositório educacional não relata execução independente do notebook em todo hardware. A decisão de adotar depende do seu teste, da política de dados, do inventário de rede e do custo de manter runtime, modelos e dependências atualizados.

Se o teste exigir acesso amplo ao computador, gravação automática ou fallback remoto invisível, volte ao desenho. Um agente local bem limitado é mais valioso do que um agente chamado de privado sem evidência operacional.

Fontes primárias

• Microsoft, repositório AI Agents for Beginners
• Microsoft, SKILL.md no commit auditado
• Microsoft, Lição 17 no commit auditado
• Microsoft, changelog do curso
• Microsoft Learn, uso atual da CLI Foundry Local
• Microsoft Learn, início com Foundry Local
• Microsoft Learn, integração com SDKs de inferência
• Microsoft Learn, referência atual do SDK
• Qwen, function calling e limites
• Model Context Protocol, transportes e stdio