Bygg en enkel agentisk app med CUGA

Den här guiden är för utvecklare som vill testa en agentisk app utan att börja med ett tungt ramverk. Du bygger ett litet CUGA-upplägg där agenten får en modell, en verktygslista, en systeminstruktion och tydliga testfall.

Det här behöver du

• Python 3.10 eller senare.
• Ett API-konto hos valfri modellleverantör, eller en lokal modell via exempelvis Ollama om din CUGA-konfiguration stödjer det.
• Grundläggande vana vid terminal och Python-filer.
• Ett testproblem där agenten får använda verktyg men där resultatet går att kontrollera.

Steg 1: Skapa projektet

Börja med en ny mapp och isolerad miljö.

mkdir cuga-pilot
cd cuga-pilot
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

Installera CUGA. Hugging Face/IBM-artikeln beskriver CUGA som ett lättviktigt agent-harness där mycket av appen kan hållas i en enkel fil.

python -m pip install cuga

Om installationen misslyckas: kontrollera Python-version och läs projektets aktuella installationsinstruktioner innan du felsöker själva agentkoden.

Steg 2: Sätt miljövariabler för modellen

Håll modellvalet utanför appkoden. Då kan du byta mellan molnmodell och lokal modell utan att skriva om agentens logik.

export LLM_PROVIDER="openai"
export LLM_MODEL="gpt-4.1-mini"
export OPENAI_API_KEY="din-nyckel-här"

För teammiljö bör nycklar ligga i en secrets-lösning, inte i shell-historik eller repo.

Steg 3: Skapa en enkel modell-fabrik

Lägg modellkopplingen i en separat fil, till exempel _llm.py. Exakt klient beror på leverantör, så se detta som en strukturmall.

# _llm.py
import os

def create_llm(provider: str | None = None, model: str | None = None):
 provider = provider or os.getenv("LLM_PROVIDER")
 model = model or os.getenv("LLM_MODEL")

 if not provider or not model:
 raise RuntimeError("Sätt LLM_PROVIDER och LLM_MODEL innan du startar appen.")

 # Byt detta mot den adapter CUGA-exemplet använder i din miljö.
 return {"provider": provider, "model": model}

Poängen är separationen: agenten ska inte behöva veta vilken modell som ligger bakom.

Steg 4: Definiera verktygen agenten får använda

Välj ett ofarligt första verktyg. Här använder vi en lokal funktion som söker i en hårdkodad tjänstekatalog.

# tools.py
SERVICES = [
 {"name": "Object Storage", "use": "lagra filer och träningsdata"},
 {"name": "PostgreSQL", "use": "relationsdata och interna appar"},
 {"name": "Vector DB", "use": "sökning med embeddings"},
]

def search_catalog(query: str) -> dict:
 hits = [s for s in SERVICES if query.lower() in s["use"].lower() or query.lower() in s["name"].lower()]
 return {"ok": True, "data": hits[:5]}

Använd ett konsekvent svarskuvert: ok, data och vid fel en kod eller förklaring. Det gör agentens beteende lättare att testa.

Steg 5: Bygg agenten i main.py

IBM/Hugging Face-exemplet visar en konstruktion där CugaAgent får modell, verktyg, systeminstruktion och en .cuga-mapp för appens tillstånd och policy.

# main.py
import os
from pathlib import Path
from cuga import CugaAgent
from _llm import create_llm
from tools import search_catalog

_DIR = Path(__file__).parent

_SYSTEM = """
Du hjälper användaren att välja intern teknisk tjänst.
Använd alltid katalogverktyget innan du rekommenderar något.
Om frågan ligger utanför katalogen ska du säga att du inte vet.
"""

def make_agent():
 return CugaAgent(
 model=create_llm(
 provider=os.getenv("LLM_PROVIDER"),
 model=os.getenv("LLM_MODEL"),
 ),
 tools=[search_catalog],
 special_instructions=_SYSTEM,
 cuga_folder=str(_DIR / ".cuga"),
 )

if __name__ == "__main__":
 agent = make_agent()
 result = agent.invoke("Vilken tjänst passar för att lagra träningsfiler?")
 print(result)

Om din installerade CUGA-version använder await agent.invoke(...) i stället för synkront anrop: gör main.py asynkron enligt dokumentationen.

Steg 6: Kör appen och kontrollera resultatet

Starta appen från projektmappen.

python main.py

Du vet att första delen fungerar när agenten svarar med en rekommendation som bygger på katalogverktyget, inte på fri gissning.

Steg 7: Lägg till testfall innan du bygger UI

Agentiska appar bör testas innan de får ett snyggt gränssnitt. Skapa enkla fall för normal fråga, okänd fråga och fråga där agenten ska avstå.

# test_cases.py
CASES = [
 ("Vad passar för relationsdata?", "PostgreSQL"),
 ("Vad passar för embeddings?", "Vector DB"),
 ("Vilken lön har Anna?", "vet inte"),
]

Kör fallen manuellt först. När beteendet stabiliserats kan de bli automatiska regressionstester.

Steg 8: Sätt stoppregler för produktion

Innan appen används av fler bör du bestämma:

• Vilka verktyg får agenten anropa?
• Vilka frågor ska nekas?
• Hur loggas verktygsanrop?
• Vem granskar felaktiga svar?

CUGA-idén är användbar just för att appen kan växa från ett litet harness till mer styrt agentflöde. Börja smalt och öka autonomin först när testfallen visar stabilt beteende.

Felsökning

• Problem: pip install cuga misslyckas. Orsak: fel Python-version eller paketmiljö. Lösning: skapa ny virtuell miljö och kontrollera aktuell CUGA-dokumentation.
• Problem: Agenten svarar utan att använda verktyget. Orsak: systeminstruktionen är för svag. Lösning: skriv att verktyget alltid måste användas före rekommendation.
• Problem: Modellen går inte att byta. Orsak: modellvalet är hårdkodat. Lösning: använd miljövariabler och en separat create_llm-funktion.
• Problem: Svaren går inte att testa. Orsak: verktygen returnerar ostrukturerad text. Lösning: returnera konsekvent JSON-liknande objekt med ok, data och felkod.

Källa: Hugging Face Blog