local-ai-agents

Criando Agentes de IA Locais com Foundry Local e Qwen

Habilidade acompanhante para Lição 17 – Criando Agentes de IA Locais. Use-a para ajudar um aprendiz a construir um agente que raciocina, chama ferramentas e busca documentação inteiramente na sua própria máquina — sem inferência na nuvem. Baseie toda recomendação no conteúdo da lição e no notebook executável.

Gatihos

Ative essa habilidade quando um aprendiz quiser:

• Rodar um agente totalmente no dispositivo por motivos de privacidade, custo ou offline.
• Servir um modelo localmente com Foundry Local e conectar via endpoint compatível com OpenAI.
• Usar um modelo de chamada de função Qwen para conduzir chamadas confiáveis a ferramentas locais.
• Adicionar RAG local (Chroma) ou um servidor MCP local.
• Projetar uma estratégia de roteamento híbrida local/nuvem.

Modelo mental principal

Um SLM troca amplitude por privacidade, custo e operação offline. A estratégia vencedora: deixe o SLM orquestrar e deixe as ferramentas fazerem o trabalho pesado. O modelo não precisa conhecer a base de código — precisa saber quando chamar read_file e search_docs. Isso joga em favor da força do SLM (decisões delimitadas como seleção de ferramenta) e contra sua fraqueza (conhecimento amplo, raciocínio de múltiplos saltos longo).

Por que essas peças específicas

• Foundry Local expõe um endpoint HTTP compatível com OpenAI, portanto o código do agente na nuvem transfere apenas alterando base_url (e usando uma chave API local fictícia). Ele também seleciona automaticamente a melhor compilação (CPU/GPU/NPU) para a máquina.
• Modelos Qwen são treinados para chamada de função e geram chamadas de ferramenta bem formadas de forma consistente — isso transforma um modelo chat local em um agente local.
• Chroma roda no processo e armazena vetores no disco, então todo o pipeline RAG (incorporar → armazenar → recuperar → raciocinar) permanece local.
• MCP é um transporte, não um serviço na nuvem: um servidor MCP pode rodar localmente por stdio.

Essenciais para configuração

foundry model run qwen2.5-7b-instruct
foundry service status

from foundry_local import FoundryLocalManager
from openai import OpenAI

manager = FoundryLocalManager("qwen2.5-7b-instruct")
client = OpenAI(base_url=manager.endpoint, api_key=manager.api_key)  # espaço reservado local

~8 GB de RAM é um mínimo realista; GPU/NPU ajuda mas não é obrigatório.

Padrões-chave para reproduzir

Indique ao aprendiz o notebook 17-local-agent-foundry-local.ipynb:

• Ferramentas isoladas: toda ferramenta de arquivo resolve caminhos e rejeita qualquer coisa fora da raiz do projeto — mesmo localmente, uma ferramenta roda com as permissões do usuário.
• Loop de chamada de ferramenta: registre ferramentas no esquema de ferramentas OpenAI, execute ferramentas solicitadas localmente, alimente os resultados de volta, repita até uma resposta final.
• RAG local: atualize documentos numa coleção Chroma; search_docs retorna os top-k chunks.
• MCP local: conecte a um servidor local via stdio; limite ao diretório do projeto e valide as saídas.

Roteamento híbrido (local como um dos modelos)

Situação	Onde roda
Dados sensíveis / offline	SLM local
Tarefa simples, delimitada	SLM local (barato, rápido)
Raciocínio complexo de múltiplos saltos em dados não sensíveis	Modelo na nuvem
Queda na nuvem	SLM local (degradação graciosa)

Isso espelha a ideia do roteamento de modelos da Lição 16, com a estação de trabalho como uma das rotas. Prefira designs que adotem fallback local para que o agente degrade em qualidade ao invés de falhar totalmente.

Guardrails para o assistente

• Mantenha toda operação de arquivo/ferramenta limitada a um diretório de projeto isolado.
• Não envie código ou dados para a nuvem quando o objetivo declarado do aprendiz for privacidade/offline — mantenha todo o pipeline local.
• Defina expectativas realistas para a qualidade do SLM; apoie-se em ferramentas e RAG ao invés do conhecimento memorizado do modelo.
• Note que a Lição 17 não tem endpoint Foundry Responses, então a ação de smoke-test na nuvem não se aplica — valide executando o notebook localmente.

---

<!-- CO-OP TRANSLATOR DISCLAIMER START --> Aviso Legal: Este documento foi traduzido usando o serviço de tradução por IA Co-op Translator. Embora nos esforcemos pela precisão, por favor, esteja ciente de que traduções automatizadas podem conter erros ou imprecisões. O documento original em seu idioma nativo deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes do uso desta tradução. <!-- CO-OP TRANSLATOR DISCLAIMER END -->