ai-agents-for-beginners

Skapa Lokala AI-agenter med Microsoft Foundry Local och Qwen

Skapa Lokala AI-agenter

Den föregående lektionen skalerade agenter upp till molnet. Den här tar dem ner till en enda maskin. I slutet kommer du att ha en fungerande ingenjörsassistent som resonerar, anropar verktyg, läser dina filer och söker i din dokumentation — utan ett enda molninferensanrop.

Varför skulle du vilja det? Tre anledningar som ständigt dyker upp i verkligt ingenjörsarbete:

Nackdelen är att du byter ut en topprankad molnmodell mot en Small Language Model (SLM) som körs på din CPU, GPU eller NPU. Den här lektionen handlar om att bygga agenter som är bra inom denna begränsning snarare än att låtsas att begränsningen inte finns.

Introduktion

Den här lektionen kommer att täcka:

Lärandemål

Efter att ha genomfört denna lektion kommer du att kunna:

Förkunskapskrav

Den här lektionen förutsätter att du har genomfört tidigare lektioner och är bekväm med:

Du behöver också:

Small Language Models: Rätt verktyg för lokalt arbete

En topprankad molnmodell har hundratals miljarder parametrar och ett datacenter bakom sig. En SLM har några få miljarder parametrar och måste rymmas i din laptops RAM. Den skillnaden sätter tydliga förväntningar.

SLM är bra på:

SLM är svagare på:

Den vinnande strategin för lokala agenter är alltså: låt SLM orkestrera och låt verktyg göra tyngre lyft. Modellen behöver inte känna till din kodbas — den behöver veta när den ska anropa read_file och search_docs. Det spelar direkt på en SLM:s styrkor.

flowchart LR
    U[Utvecklare] --> A[Lokal SLM-agent]
    A -->|bestämmer vilket verktyg| T1[läs_fil]
    A -->|bestämmer vilket verktyg| T2[sök_dokument RAG]
    A -->|bestämmer vilket verktyg| T3[analysera_kod]
    T1 --> A
    T2 --> A
    T3 --> A
    A --> R[Svar, helt på enheten]

Microsoft Foundry Local

Microsoft Foundry Local är en lättviktig runtime som laddar ner, hanterar och serverar modeller helt på din maskin. Dess viktigaste funktion för oss är att den exponerar en OpenAI-kompatibel HTTP-slutpunkt — vilket betyder att OpenAI SDK och Microsoft Agent Frameworks OpenAI-klient fungerar med den med bara en ändring av base_url. Allt du lärt dig om att bygga agenter överförs direkt; bara slutpunkten flyttas från molnet till localhost.

Foundry Local väljer också automatiskt den bästa bygget för en modell för din hårdvara — en CPU-build, en CUDA/GPU-build eller en NPU-build — så du behöver inte optimera manuellt per maskin.

Installation

Installera Foundry Local (se dokumentationen för ditt OS), och kontrollera sedan att det fungerar:

# Installera (exempel; följ dokumentationen för din plattform)
winget install Microsoft.FoundryLocal      # Windows
# brew install microsoft/foundrylocal/foundrylocal   # macOS

# Ladda ner och kör en Qwen-modell, starta sedan den lokala tjänsten
foundry model run qwen2.5-7b-instruct
foundry service status

När tjänsten körs har du en lokal, OpenAI-kompatibel slutpunkt (vanligtvis http://localhost:PORT/v1). Notebooken använder foundry-local-sdk för att automatiskt upptäcka slutpunkten, så du behöver inte hårdkoda porten.

Qwen Funktionsanrop: Varför det är viktigt

En agent är bara en agent om den kan anropa verktyg. Många SLM kan chatta men producerar opålitliga, felaktigt formade verktygsanrop. Qwen-modeller tränas för funktionsanrop och genererar konsekvent välformade verktygsanropsstrukturer — vilket är precis vad som gör en lokal chattmodell till en lokal agent.

Flödet är den standardiserade verktygsanropsloopen du redan känner till, men körs på enheten:

sequenceDiagram
    participant U as Användare
    participant A as Qwen-Agent (lokal)
    participant T as Lokalt verktyg
    U->>A: "Vad gör auth.py?"
    A->>A: Bestäm: anropa read_file
    A->>T: read_file("auth.py")
    T-->>A: filinnehåll
    A->>A: Resonerar över innehåll
    A-->>U: Förklaring

Lokal RAG

Dokumentationssökning är där lokala agenter verkligen gör skillnad. Istället för att hoppas att SLM memorerat din ramverksdokumentation bäddar du in dessa dokument i en lokal vektordatabas och låter agenten hämta relevanta delar vid behov.

Vi använder Chroma, en inbäddad vektordatabas som körs i processen utan någon server att hantera. Pipeline är helt lokal: lokal inbäddningsmodell → lokala vektorer → lokal hämtning → lokal SLM.

flowchart TB
    D[Dina dokument / kod] --> E[Lokal inbäddningsmodell]
    E --> V[(Chroma vektor DB - på disk)]
    Q[Agentfråga] --> QE[Bädda in fråga lokalt]
    QE --> V
    V -->|top-k segment| A[Qwen agent]
    A --> Ans[Grundat svar]

Detta är samma Agentic RAG-mönster från Lektion 5 — enda skillnaden är att varje komponent körs på din maskin.

Lokala MCP-servrar

MCP är en transport, inte en molntjänst. En MCP-server kan köras som en lokal process på stdio, vilket exponerar verktyg till din agent över standardprotokollet. Detta låter dig återanvända det växande ekosystemet av MCP-servrar — filsystemåtkomst, git-operationer, databasfrågor — helt offline.

Säkerhetsinställningen skiljer sig från molnet, men är inte frånvarande: en lokal MCP-server körs fortfarande med dina användarbehörigheter, så begränsa vad den kan röra vid (en projektkatalog, inte hela din hemkatalog) och behandla dess utdata som indata för validering.

Hybrida Moln- och Lokala Mönster

Lokalt först betyder inte bara lokalt. Mogna system styr baserat på känslighet och svårighetsgrad:

Situation Var det körs
Känslig kod / data, eller offline Lokal SLM
Enkel, avgränsad uppgift Lokal SLM (billigt, snabbt)
Svårt flerstegsresonemang på icke-känslig data Molnmodell
Allt under ett avbrott Lokal SLM (graciell degradering)

Detta speglar idén om modellriktning från Lektion 16 — förutom att en av “modellerna” nu är din egen maskin. En robust design faller tillbaka på lokal när molnet inte är tillgängligt, så agenten degraderas i kvalitet istället för att helt misslyckas.

flowchart LR
    Q[Begäran] --> S{Känslig eller offline?}
    S -->|ja| L[Lokal SLM]
    S -->|nej| C{Behöver djup resonemang?}
    C -->|nej| L
    C -->|ja| Cloud[Molnmodell]
    L --> Out[Svar]
    Cloud --> Out

Praktisk Laboration: En Lokal Ingenjörsassistent

Öppna code_samples/17-local-agent-foundry-local.ipynb och arbeta igenom den. Du kommer att bygga en lokal ingenjörsassistent som körs helt på din arbetsstation och kan:

  1. Anropa verktyg — via Qwen funktionsanrop genom Foundry Local.
  2. Utföra lokala filoperationer — lista och läsa filer i en projektmapp.
  3. Analysera kod — rapportera grundläggande mått på en källkodfil.
  4. Söka dokumentation — lokal RAG över en dokumentationsmapp med Chroma.
  5. Använda MCP — anslut till en lokal MCP-server (med en graciös bortprioritering om ingen är konfigurerad).

Ingen molninferens används vid något tillfälle.

Genomgång

Assistenten ansluter till Foundry Local via den OpenAI-kompatibla slutpunkten, så agentkoden ser nästan identisk ut med molnlektionerna — bara klienten ändras:

from foundry_local import FoundryLocalManager
from openai import OpenAI

# Foundry Local upptäcker/laddar ner modellen och ger oss en lokal slutpunkt.
manager = FoundryLocalManager(\"qwen2.5-7b-instruct\")
client = OpenAI(base_url=manager.endpoint, api_key=manager.api_key)  # api_key är en lokal platshållare

Verktygen är vanliga Python-funktioner som begränsas till en projektmapp:

def read_file(path: str) -> str:
    \"\"\"Read a file, but only inside the sandboxed project directory.\"\"\"
    full = (PROJECT_ROOT / path).resolve()
    if PROJECT_ROOT not in full.parents and full != PROJECT_ROOT:
        return \"Access denied: path is outside the project directory.\"
    return full.read_text(encoding=\"utf-8\")

Notera sandboxkontrollen — även lokalt är ett verktyg som läser godtyckliga sökvägar en risk. Notebooken håller varje verktyg begränsat till en projektrot.

Kunskapskontroll

Testa din förståelse innan du går vidare till uppgiften.

1. Ge två konkreta anledningar till att köra en agent lokalt istället för i molnet.

Svar Vilka två som helst av: **sekretess** (kod och data lämnar aldrig maskinen), **kostnad** (ingen kostnad per token), och **offline-förmåga** (fungerar utan nätverk — på ett plan, i en säker anläggning eller under ett avbrott). Regulatoriska/efterlevnadsbegränsningar som förbjuder att skicka data utanför enheten är en vanlig drivkraft för sekretessskälet.

2. Vad är den rekommenderade arbetsfördelningen mellan en SLM och dess verktyg i en lokal agent, och varför?

Svar Låt SLM **orkestrera** (avgöra vilket verktyg som ska anropas och med vilka argument) och låt **verktygen göra det tunga arbetet** (läsa filer, hämta dokument, beräkna resultat). SLM är starka på avgränsade beslut som verktygsval men svaga på bred kunskap och långt flerstegsresonemang, så att luta sig mot verktyg spelar på deras styrkor.

3. Vad gör det möjligt att återanvända molnagenter med Foundry Local?

Svar Foundry Local exponerar en **OpenAI-kompatibel HTTP-slutpunkt**. OpenAI SDK och Agent Frameworks OpenAI-klient fungerar mot den genom att bara ändra `base_url` (och använda en lokal platshållar-API-nyckel). Allt annat i agentkoden förblir samma.

4. Varför använder vi specifikt en Qwen funktionsanropsmodell snarare än vilken SLM som helst?

Svar För att en agent måste producera pålitliga, välformade **verktygsanrop**. Många SLM kan chatta men genererar felaktiga eller inkonsekventa strukturer för verktygsanrop. Qwen-modeller är tränade för funktionsanrop och producerar konsekventa verktygsanrop, vilket förvandlar en lokal chattmodell till en fungerande lokal agent.

5. Vilka komponenter körs på maskinen i den lokala RAG-pipelinen?

Svar Alla: inbäddningsmodellen, vektordatabasen (Chroma, på disk), hämtningsteget och SLM. Dokument bäddas in lokalt, lagras lokalt, hämtas lokalt och resonerar med en lokal modell — ingen komponent rör molnet.

6. En lokal MCP-server körs på din maskin. Gör det den automatiskt säker? Vilken försiktighetsåtgärd bör du ändå vidta?

Svar Nej. En lokal MCP-server körs med dina användarbehörigheter, så den kan röra vid allt du kan. Begränsa den till vad den behöver (till exempel en enskild projektmapp snarare än hela din hemkatalog) och behandla dess utdata som indata som ska valideras innan du agerar på dem.

7. Beskriv en rimlig hybridriktregel som inkluderar en lokal modell.

Svar Rikt känsliga eller offline-förfrågningar till lokal SLM; rikt enkla, avgränsade uppgifter till lokal SLM för snabbhet och kostnad; rikta svåra flerstegsresonemang på icke-känslig data till en molnmodell; och falla tillbaka på lokal SLM om molnet inte är tillgängligt så agenten degraderas graciöst istället för att misslyckas. Detta är modellriktning (Lektion 16) med den lokala maskinen som en av modellerna.

8. Vad är en realistisk miniminivå av RAM för att köra den lokala agenten i denna lektion, och vad köper du med mer RAM?

Svar Runt **8 GB** är en realistisk minimum; 16 GB+ är bekvämt. Mer RAM låter dig köra större, mer kapabla modeller och hålla mer kontext i minnet. En GPU eller NPU snabbar upp inferens men krävs inte — Foundry Local väljer en CPU-build när ingen accelerator är tillgänglig.

Uppgift

Utöka den lokala ingenjörsassistenten till en lokal dokumentationsgranskare för ett litet projekt du väljer (använd gärna någon av lektionens mappar i detta repot).

Din inlämning ska:

  1. Indexera en riktig dokumentations-/kodmapp i Chroma (minst fem filer).

  2. Lägga till ett find_todos-verktyg som skannar projektet efter TODO/FIXME-kommentarer och returnerar dem med fil och radnummer — med samma sandbox-kontroll som read_file.

  3. Ställ tre frågor till agenten som tvingar den att kombinera verktyg: en ren RAG-fråga, en som kräver att läsa en specifik fil, och en som kräver att hitta TODOs.
  4. Mät det: tidtag varje av de tre svaren och notera dem i en markdown-cell. Kommentera om latensen är acceptabel för din tänkta arbetsflöde.

Skriv sedan ett kort stycke om vad du skulle flytta till molnet och vad du skulle behålla lokalt för denna granskare, och varför. Du bedöms på om de lokala komponenterna är korrekt kopplade tillsammans och om din hybrida resonemang är sund — inte på modellkvaliteten.

Sammanfattning

I denna lektion byggde du en agent som körs helt på din egen maskin:

Detta slutför distributionsbågen: Lektion 16 skalade upp agenter i Microsoft Foundry, och denna lektion skalade ned dem till en enskild arbetsstation. Nästa lektion handlar om att hålla distribuerade agenter säkra.

Ytterligare resurser

Föregående lektion

Distribuera skalbara agenter

Nästa lektion

Säkra AI-agenter

Ansvarsfriskrivning: Detta dokument har översatts med hjälp av AI-översättningstjänsten Co-op Translator. Även om vi strävar efter noggrannhet, var vänlig notera att automatiska översättningar kan innehålla fel eller brister. Det ursprungliga dokumentet på dess modersmål bör betraktas som den auktoritativa källan. För kritisk information rekommenderas professionell mänsklig översättning. Vi ansvarar inte för några missförstånd eller feltolkningar som uppstår till följd av användningen av denna översättning.

This site is open source. Improve this page.