Modul 14: AI-Frameworks in Go
Der Go-AI-Stack in der Praxis: offizielle SDKs für OpenAI & Anthropic, LangChainGo für Workflows, Eino als leichte Alternative, Genkit von Google, Streaming über SSE & WebSockets, Vektor-DBs mit pgvector & Qdrant, und Agent-Loops mit Guardrails und Evals.
Der Go-AI-Stack: offizielle SDKs, LangChainGo, Eino, Genkit
Lektion 66 von 100
Vom HTTP-Client zum Framework: Warum der Stack wichtig ist
In Modul 4 haben wir LLM-Clients mit der Standardbibliothek (net/http, encoding/json) gebaut. Das reicht für einzelne Requests — aber sobald es um Werkzeuge wie Retrieval Augmented Generation (RAG), Tool-Calling oder Agent-Loops geht, wird der Code schnell unübersichtlich. Die Lösung: spezialisierte Frameworks, die sich auf den Go-Ekosystem-Standards aufbauen und dabei zusätzliche Abstraktionen für typische AI-Workflows liefern.
Der Go-AI-Stack gliedert sich aktuell in vier Ebenen: offizielle SDKs der Anbieter (OpenAI, Anthropic, Google), Workflow-Frameworks für komplexe Pipelines (LangChainGo, Eino), Streaming-& Integrationstools (Genkit) und Dateninfrastruktur (Vektordatenbanken, Embedding-Clients). Die gute Nachricht: Alle diese Frameworks bauen auf context.Context, io.Reader/io.Writer und Go-Typen auf — es gibt keine Magie, nur solides Interface-Design.
Interface-Design als Go-Stärke
Bitten Sie einen Python-Entwickler, die Unterschiede zwischen LangChain, LlamaIndex und Microsofts Semantic Kernel zu erklären, erhalten Sie eine lange Liste incompatibler Klassen und magischer String-Workarounds. In Go reichen drei Regeln: 1) Jeder AI-Call bekommt einen context.Context für Cancellation und Timeouts, 2) Antworten kommen als io.Reader oder direkt in Structs zurück, und 3) Fehler implementieren error. Das macht es einfach, Komponenten auszutauschen — ein Embedder-Interface arbeitet mit OpenAI- und lokalen Ollama-Embeddings gleichermaßen.
Ebene 1: Offizielle SDKs — OpenAI und Anthropic
Die Provider bieten seit 2023/24 offizielle Go-SDKs an. Sie abstrahieren die REST-API, bringen Type-Safety und sparen Boilerplate — aber sie decken nur die Basis-Funktionalität des jeweiligen Anbieters ab.
package main
import (
"context"
"fmt"
"github.com/openai/openai-go"
)
func main() {
client := openai.NewClient("sk-...")
resp, err := client.Chat.Completions.New(
context.Background(),
&openai.ChatCompletionNewParams{
Model: openai.F("gpt-4o-mini"),
Messages: openai.F([]openai.ChatCompletionMessageParamUnion{
&openai.ChatCompletionMessageParam{
Role: openai.F("user"),
Content: openai.F("Erkläre das Go-Interface {} in einem Satz."),
},
}),
MaxTokens: openai.F(100),
Temperature: openai.F(0.0),
},
)
if err != nil {
fmt.Println("Fehler:", err)
return
}
fmt.Println("Antwort:", *resp.Choices[0].Message.Content)
// → Antwort: In Go definiert ein Interface einen Vertrag (Methode + Signatur), den jeder Typ erfüllen kann, der diese Methode mit passender Signatur implementiert.
}
Für Anthropic gibt es github.com/anthropics/anthropic-sdk-go mit ähnlichem API-Design:
package main
import (
"context"
"fmt"
"github.com/anthropics/anthropic-sdk-go"
)
func main() {
client := anthropic.NewClient("sk_ant_...")
resp, err := client.Messages.New(
context.Background(),
&anthropic.MessageNewParams{
Model: anthropic.F("claude-3-5-sonnet"),
MaxTokens: openai.F(1024),
Messages: anthropic.F([]anthropic.MessageParam{
{Role: anthropic.MessageRoleUser, Content: []anthropic.TextBlockParam{
{Type: "text", Text: "Was ist der Unterschied zwischen struct und interface in Go?"},
}},
}),
},
)
if err != nil {
fmt.Println("Fehler:", err)
return
}
fmt.Println("Antwort:", resp.Content[0].Text)
// → Antwort: Ein struct ist ein konkreter Typ, der Daten felder gruppiert, während ein interface ein Vertrag ist, den Typen durch Methoden-Implementierung erfüllen können.
}
⚠ Häufiger Fehler: Die SDKs aus 2023/24 erwarten oft noch Pointer auf Structs (
openai.F(...)ist ein Helper, der*Tzurückgibt), und setzen aufcontext.Contextfür Timeouts. Wer hiercontext.Background()ohne Timeout verwendet und gleichzeitig langlaufende Batch-Jobs startet, riskiert, dass ein stürzender Client-Request den ganzen Service blockiert. Immer mitcontext.WithTimeout(context.Background(), 30*time.Second)arbeiten oder noch besser: den timeout-Kontext aus dem HTTP-Handler durchreichen (r.Context()).
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
Structured Output & Tool-Calling robust machen
Lektion 67 von 100
Der Vertrag zwischen Mensch und Maschine: Structured Output
LLMs geben Text zurück — aber Texte sind für Software unberechenbar. Structured Output zwingt das Modell, seine Antwort in einem festgelegten Format (meist JSON) zu liefern, das direkt in Go-Structs geparst werden kann. Das ist kein Luxus, sondern Überlebensnotwendigkeit: Jetzt, da LLMs nicht nur Antworten generieren, sondern Tools aufrufen und Daten verarbeiten, muss der Output maschinell verarbeitbar sein.
LangChainGo (github.com/tmc/langchaingo) ist aktuell das bekannteste Go-Framework für AI-Workflows. Es bietet ein durchdachtes schema Paket für Structured Output: Mit WithStructuredOutput kann man dem LLM ein Go-Struct überreichen, und das Frameworkgenerated automatisch das passende JSON-Schema für den Prompt. Das Modell wird aufgefordert, die Antwort in diesem Format zu liefern.
Structured Output = Type Safety in AI-Workflows
Structured Outputandelt nichts anderes, als dass das LLM seine Antwort in einem definierten JSON-Format zurückgibt, das direkt in Go-Structs geparst werden kann. LangChainGo macht das besonders einfach, indem es das JSON-Schema automatisch aus dem Struct generiert. Wichtig: Das LLM kann trotzdem invalides JSON liefern — Validierung des Outputs ist immer noch Pflicht!
Structured Output mit LangChainGo
Ein praktisches Beispiel: Wir wollen, dass das LLM eine Nutzeranfrage klassifiziert und die Kategorisierung in einem Struct zurückgibt.
package main
import (
"context"
"fmt"
"github.com/tmc/langchaingo/llms/openai"
"github.com/tmc/langchaingo/schema"
)
// Klassifizierung ist das Schema, das wir vom LLM erwarten
type Klassifizierung struct {
Kategorie string `json:"kategorie" description:"Die Hauptkategorie der Anfrage: support, sales, bug, feature"`
Prioritaet int `json:"prioritaet" description:"1-5, wobei 5 am dringendsten ist"`
Beschreibung string `json:"beschreibung" description:"Kurze Zusammenfassung der Anfrage"`
}
func main() {
llm, _ := openai.New(openai.WithToken("sk-..."), openai.WithModel("gpt-4o-mini"))
resp, err := llm.GenerateContent(
context.Background(),
"Klassifiziere: Der Kunde melden, dass die Bestellung #4711 nicht angekommen ist. Welche Kategorie und Priorität hat das?",
schema.WithStructuredOutput[Klassifizierung](),
)
if err != nil {
fmt.Println("Fehler:", err)
return
}
// Die Antwort ist direkt als struct verfügbar
klass := resp.StructuredContent
fmt.Printf("Kategorie: %s, Priorität: %d, Beschreibung: %s",
klass.Kategorie, klass.Prioritaet, klass.Beschreibung)
// → Kategorie: support, Priorität: 5, Beschreibung: Kunde meldet fehlende Bestellung #4711
}
Tool-Calling: LLMs als Orchestrierer
Mit Structured Output allein können wir bereits konkrete Daten aus LLM-Antworten extrahieren. Aber was, wenn das LLM nicht nur antworten, sondern auch Handlungen auslösen soll? Genau hier kommt Tool-Calling ins Spiel: Das LLM entscheidet auf Basis seiner Tool-Beschreibungen, welches Tool aufgerufen werden soll, und liefert die Parameter als JSON zurück.
LangChainGo unterstützt dies durch das tools Paket. Jedes Tool implementiert das Tool Interface mit Name(), Description() und Call(ctx, input):
package main
import (
"context"
"fmt"
"github.com/tmc/langchaingo/llms/openai"
"github.com/tmc/langchaingo/schema"
"github.com/tmc/langchaingo/tools"
)
// WetterTool ruft eine fiktive Wetter-API auf
type WetterTool struct{}
func (WetterTool) Name() string { return "get_wetter" }
func (WetterTool) Description() string {
return "Ruft das aktuelle Wetter für eine Stadt ab. Parameter: ort (string). Gibt das Wetter als String zurück."
}
func (WetterTool) Call(ctx context.Context, input string) (string, error) {
// In echt: HTTP-Aufruf an Wetter-API
return fmt.Sprintf("Wetter in %s: sonnig, 22°C", input), nil
}
func main() {
llm, _ := openai.New(openai.WithToken("sk-..."))
wetterTool := &WetterTool{}
llmWithTools := llm.WithTools([]tools.Tool{wetterTool})
// Das LLM entscheidet selbst, ob und welches Tool aufgerufen wird
resp, err := llmWithTools.GenerateContent(
context.Background(),
"Wie ist das Wetter heute in Berlin?",
schema.WithStructuredOutput[map[string]any](),
)
if err != nil {
fmt.Println("Fehler:", err)
return
}
fmt.Println("Antwort:", resp.Content)
// → Antwort: get_wetter{"ort": "Berlin"}
// Jetzt müssen wir das Tool selbst aufrufen (Dashboard siehe Text)
result, _ := WetterTool{}.Call(context.Background(), "Berlin")
fmt.Println("Wetter:", result)
// → Wetter: Wetter in Berlin: sonnig, 22°C
}
⚠ Häufiger Fehler: Tool-Calling wie im Beispiel oben bietet nur die Entscheidung, welches Tool aufgerufen werden soll. Die eigentliche Ausführung (der
Callauf das Tool) obliegt Ihnen als Entwickler — in einer Schleife (Agent-Loop, siehe Lektion 70). Viele Entwickler erwarten, dass das LLM das Tool direkt ausführt, doch das wäre unsicher: Das LLM hat keinen Zugriff auf Ihr Dateisystem, Ihre Datenbank oder Ihre APIs. Es entscheidet nur, dass ein Tool aufgerufen werden soll.
Validierung: Nie auf blindes Vertrauen setzen
Auch bei Structured Output und Tool-Calling: Das LLM kann lügen. Es kann:
- Falsche JSON-Strukturen liefern (trotz Schema-Hinweis)
- Parameter generieren, die das Tool nicht unterstützt
- Werte außerhalb der erlaubten Bereiche vorschlagen
Daher: Immer validieren! Ein Simple Helfen ist die validator Paket (z. B. github.com/go-playground/validator/v10):
package main
import (
"context"
"fmt"
"github.com/go-playground/validator/v10"
)
type Klassifizierung struct {
Kategorie string `json:"kategorie" validate:"oneof=support sales bug feature"`
Prioritaet int `json:"prioritaet" validate:"min=1,max=5"`
Beschreibung string `json:"beschreibung"`
}
func validateKlass(k Klassifizierung) error {
validate := validator.New()
return validate.Struct(k)
}
Für die Sicherheit von Prompts und System-Boundaries verweisen wir auf die Sicherheitsarchitektur zu Prompt-Injection und Trust-Boundaries.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
Streaming: SSE & WebSockets für LLM-Responses
Lektion 68 von 100
Warum Text-Streaming die UX revolutioniert
Die erste Generation von AI-Anwendungen hat einen entscheidenden Nachteil: Der Nutzer wartet. Bei langen Antworten oder komplexen Berechnungen kann das mehrere Sekunden dauern. Streaming ändert das: Statt die gesamte Antwort auf einmal zu liefern, werden die Token so schnell wie möglich — oft Wort für Wort — an den Nutzer geschickt. Das verbessert nicht nur die wahrgenommene Performance, sondern ermöglicht auch Interaktionen wie "Denken laut" (Chain-of-Thought) oder Echtzeit-Feedback.
Es gibt zwei etablierte Protokolle: Server-Sent Events (SSE) und WebSockets. SSE ist das einfachere Protokoll — HTTP-basiert, unidirektional (Server → Client), hervorragend für LLM-Streaming. WebSockets sind bidirektional und komplexer, aber notwendig für Echtzeit-Collaboration (z. B. gemeinsames Editieren mit AI-Unterstützung).
SSE vs. WebSockets: Das richtige Werkzeug wählen
Server-Sent Events (SSE) ist ein HTTP-basiertes Streaming-Protokoll, das eine unidirektionale Verbindung vom Server zum Client herstellt. Jede Nachricht ist eine Textzeile mit dem Präfix data: . SSE funktioniert hervorragend für LLM-Streaming, da der Client nur die Antworten empfängt und nicht aktiv mit dem Server kommunizieren muss. WebSockets hingegen sind bidirektional und ermöglichen Echtzeit-Interaktionen in beide Richtungen, sind aber komplexer zu implementieren und zu warten.
SSE-Streaming mit net/http
Die OpenAI-API unterstützt Streaming über SSE. In Go implementieren wir das mit net/http und bufio.Scanner — genau wie in Modul 4, nur dass wir die SSE-Formate parsen müssen:
package main
import (
"bufio"
"bytes"
"context"
"encoding/json"
"fmt"
"io"
"net/http"
"strings"
)
type StreamResponse struct {
Choices []struct {
Delta struct {
Content string `json:"content"`
} `json:"delta"`
FinishReason *string `json:"finish_reason"`
} `json:"choices"`
}
// Proxy-Handler, der OpenAI-Streaming an den Client weiterleitet
func handleStreamProxy(w http.ResponseWriter, r *http.Request) {
// Client-API-Key aus dem Header
apiKey := r.Header.Get("X-API-Key")
if apiKey == "" {
http.Error(w, "X-API-Key fehlt", http.StatusUnauthorized)
return
}
// OpenAI-Request vorbereiten
reqBody := map[string]interface{}{
"model": "gpt-4o-mini",
"messages": []map[string]string{{"role": "user", "content": "Erzühl eine Kurze Geschichte."}},
"stream": true,
}
jsonData, _ := json.Marshal(reqBody)
req, _ := http.NewRequestWithContext(r.Context(), "POST",
"https://api.openai.com/v1/chat/completions", bytes.NewBuffer(jsonData))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+apiKey)
resp, err := http.DefaultClient.Do(req)
if err != nil {
http.Error(w, "Stream-Fehler", http.StatusInternalServerError)
return
}
defer resp.Body.Close()
// Client: SSE-Header setzen
w.Header().Set("Content-Type", "text/event-stream")
w.Header().Set("Cache-Control", "no-cache")
w.Header().Set("Connection", "keep-alive")
// OpenAI-Stream parsen und weiterleiten
scanner := bufio.NewScanner(resp.Body)
for scanner.Scan() {
line := scanner.Text()
if line == "" {
continue
}
if strings.HasPrefix(line, "data: ") {
data := strings.TrimPrefix(line, "data: ")
if data == "[DONE]" {
break
}
// Weiterleiten als SSE
fmt.Fprintf(w, "data: %s\n\n", data)
if f, ok := w.(http.Flusher); ok {
f.Flush()
}
}
}
}
func main() {
http.HandleFunc("/stream", handleStreamProxy)
fmt.Println("Streaming-Proxy läuft auf :8080")
http.ListenAndServe(":8080", nil)
}
// Terminal: curl -N http://localhost:8080/stream -H "X-API-Key: sk-..."
// → data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Es"}}]}
// → data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":" war"}}]}
// → data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":" einmal"}}]}
// → data: [DONE]
WebSockets für bidirektionale Kommunikation
Für Chat-Anwendungen, bei denen Client und Server gleichzeitig Nachrichten senden können, sind WebSockets die bessere Wahl. Das Paket github.com/gorilla/websocket ist der De-facto-Standard in Go:
package main
import (
"fmt"
"log"
"net/http"
"time"
"github.com/gorilla/websocket"
)
var upgrader = websocket.Upgrader{
ReadBufferSize: 1024,
WriteBufferSize: 1024,
CheckOrigin: func(r *http.Request) bool { return true }, // Im echten Code: Prüfe Origin!
}
func handleChat(w http.ResponseWriter, r *http.Request) {
conn, err := upgrader.Upgrade(w, r, nil)
if err != nil {
log.Println("Upgrade-Fehler:", err)
return
}
defer conn.Close()
// Nachrichten empfangen
for {
messageType, p, err := conn.ReadMessage()
if err != nil {
if websocket.IsUnexpectedCloseError(err, websocket.CloseGoingAway, websocket.CloseAbnormalClosure) {
log.Println("WebSocket-Fehler:", err)
}
break
}
// Echo: Nachricht zurücksenden (in echt: LLM aufrufen)
if messageType == websocket.TextMessage {
// Simuliere ein Streaming-Antwort
messages := []string{"Verstanden...", "Ich denke nach...", "Hier ist deine Antwort: " + string(p)}
for _, msg := range messages {
if err := conn.WriteMessage(websocket.TextMessage, []byte(msg)); err != nil {
log.Println("Write-Fehler:", err)
return
}
time.Sleep(500 * time.Millisecond) // Simulierte Verzögerung
}
}
}
}
func main() {
http.HandleFunc("/chat", handleChat)
fmt.Println("WebSocket-Server läuft auf :8080")
log.Fatal(http.ListenAndServe(":8080", nil))
}
// Terminal mit websocat (oder Browser-JS):
// → $ websocat ws://localhost:8080/chat
// → > Hallo!
// → < Verstanden...
// → < Ich denke nach...
// → < Hier ist deine Antwort: Hallo!
⚠ Häufiger Fehler: WebSocket-Verbindungen können sehr lange offen bleiben — wenn der Client die Verbindung nicht ordnungsgemäß schließt, bleiben Goroutines und Speicher allokiert. Immer einen
defer conn.Close()in der Handler-Funktion platzieren, und den Client dazu auffordern, die Verbindung mit einemClose-Frame zu beenden (z. B. wenn der Nutzer das Browser-Fenster schließt). Für eine robuste Vektor-Store-Ergänzung zu Streaming-Diensten empfiehlt sich ein Blick auf Modul 6 der Architektur-lehre zu Datenbankwahl.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
Embeddings & Vektor-DBs aus Go: pgvector, Qdrant
Lektion 69 von 100
Warum Embeddings das Herzstück von RAG sind
In Modul 4 haben wir Embeddings bereits als numerische Repräsentation von Text kennengelernt. Für RAG (Retrieval Augmented Generation) sind sie unverzichtbar: Statt nach exakten Keywords zu suchen, vergleicht RAG die semantische Ähnlichkeit von Vektoren. Das ermöglicht es, Dokumente zu finden, die thematisch verwandt sind, auch wenn sie unterschiedliche Wörter verwenden.
Die Herausforderung: Embeddings sinnvoll zu speichern und effizient abzufragen. Für kleine Datensätze (bis zu einigen tausend Dokumente) reicht eine In-Memory-Lösung mit Kosinus-Ähnlichkeit. Für produktive Anwendungen braucht man spezialisierte Vektordatenbanken (Vector Databases), die für genau diese Aufgabe optimiert sind: schnelle Ähnlichkeitsabfragen über Millionen von Vektoren.
Vektordatenbanken: Der Index für AI-Wissen
Eine Vektordatenbank speichert Embeddings und ermöglicht blitzschnelle Ähnlichkeitsabfragen. Statt wie bei einer traditionellen Datenbank nach exakten Treffern zu suchen, findet sie die "nächsten Nachbarn" (Nearest Neighbors) im hochdimensionalen Vektorraum. Die beiden etabliertesten Lösungen für Go-Entwickler sind pgvector (PostgreSQL-Erweiterung) und Qdrant (standalone).
Embeddings generieren mit OpenAI
Bevor wir Vektoren speichern können, müssen wir sie generieren. Die OpenAI-Embeddings-API ist der einfachste Einstieg:
package main
import (
"bytes"
"context"
"encoding/json"
"fmt"
"net/http"
)
type EmbeddingRequest struct {
Input string `json:"input"`
Model string `json:"model"`
}
type EmbeddingResponse struct {
Data []struct {
Embedding []float64 `json:"embedding"`
} `json:"data"`
}
// getEmbedding generiert ein Embedding für den gegebenen Text
func getEmbedding(apiKey, text string) ([]float64, error) {
payload, _ := json.Marshal(EmbeddingRequest{
Input: text,
Model: "text-embedding-3-small",
})
req, _ := http.NewRequestWithContext(
context.Background(),
"POST",
"https://api.openai.com/v1/embeddings",
bytes.NewBuffer(payload),
)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+apiKey)
resp, err := http.DefaultClient.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
var result EmbeddingResponse
if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
return nil, err
}
if len(result.Data) == 0 {
return nil, fmt.Errorf("kein Embedding erhalten")
}
return result.Data[0].Embedding, nil
}
func main() {
emb, _ := getEmbedding("sk-...", "Go ist eine statisch typisierte Programmiersprache.")
fmt.Printf("Embedding hat %d Dimensionen\n", len(emb))
// → Embedding hat 1536 Dimensionen
}
pgvector: Vektoren in PostgreSQL
pgvector ist eine PostgreSQL-Erweiterung, die Vektor-Operationen direkt in der Datenbank ermöglicht. Das Paket github.com/pgvector/pgvector-go bietet Go-Bindings:
package main
import (
"context"
"fmt"
"log"
"github.com/jackc/pgx/v5/pgxpool"
_ "github.com/pgvector/pgvector-go"
)
func main() {
// Verbindung zum PostgreSQL mit pgvector
conn, err := pgxpool.New(context.Background(),
"postgres://user:password@localhost:5432/vector_db?sslmode=disable")
if err != nil {
log.Fatal(err)
}
defer conn.Close()
// Tabelle für Dokumente mit Embeddings
_, err = conn.Exec(context.Background(), `
CREATE TABLE IF NOT EXISTS documents (
id SERIAL PRIMARY KEY,
content TEXT,
embedding vector(1536)
)
`)
if err != nil {
log.Fatal(err)
}
// Embedding einfügen
emb, _ := getEmbedding("sk-...", "Go unterstützt nebenläufige Programmierung mit Goroutines.")
_, err = conn.Exec(context.Background(),
"INSERT INTO documents (content, embedding) VALUES ($1, $2)",
"Go unterstützt nebenläufige Programmierung mit Goroutines.",
emb,
)
if err != nil {
log.Fatal(err)
}
// Nach Ähnlichkeit suchen (Top 3)
queryEmb, _ := getEmbedding("sk-...", "Wie funktionieren Goroutines in Go?")
rows, err := conn.Query(context.Background(), `
SELECT content, embedding <=> $1 as distance
FROM documents
ORDER BY distance ASC
LIMIT 3
`, queryEmb)
if err != nil {
log.Fatal(err)
}
fmt.Println("Treffer:")
for rows.Next() {
var content string
var distance float64
rows.Scan(&content, &distance)
fmt.Printf("• %s (Distanz: %.4f)\n", content, distance)
}
// → Treffer:
// → • Go unterstützt nebenläufige Programmierung mit Goroutines. (Distanz: 0.1234)
}
Qdrant: Standalone-Vektordatenbank
Qdrant ist eine standalone Vektordatenbank, die als separates Service läuft. Das Go-Client-Paket github.com/qdrant/go-client bietet eine idiomatische API:
package main
import (
"context"
"fmt"
"log"
"github.com/qdrant/go-client/qdrant"
)
func main() {
// Verbindung zu lokalem Qdrant (Standard: :6333)
client := qdrant.NewClient(qdrant.WithHost("localhost"), qdrant.WithPort(6333))
// Collection erstellen (ähnlich einer Tabelle)
_, err := client.CreateCollection(context.Background(), &qdrant.CreateCollection{
CollectionName: "go_docs",
VectorsConfig: &qdrant.VectorsConfig{
Size: 1536,
Distance: qdrant.DistanceCosine,
},
})
if err != nil {
log.Fatal(err)
}
// Dokument einfügen
emb, _ := getEmbedding("sk-...", "Go hat einen integrierten HTTP-Server im Paket net/http.")
point := &qdrant.PointStruct{
ID: &qdrant.PointID{UUID: qdrant.NewUUID()},
Vector: emb,
Payload: map[string]interface{}{
"content": "Go hat einen integrierten HTTP-Server im Paket net/http.",
},
Collections: []string{"go_docs"},
}
_, err = client.Upsert(context.Background(), &qdrant.UpsertPoints{
CollectionName: "go_docs",
Points: []*qdrant.PointStruct{point},
})
if err != nil {
log.Fatal(err)
}
// Suche nach ähnlichen Dokumenten
queryEmb, _ := getEmbedding("sk-...", "Wie baue ich einen Webserver in Go?")
result, err := client.Search(context.Background(), &qdrant.SearchPoints{
CollectionName: "go_docs",
Vector: queryEmb,
Limit: 3,
})
if err != nil {
log.Fatal(err)
}
fmt.Println("Treffer:")
for _, scoredPoint := range result.Result {
content := scoredPoint.Payload["content"].(string)
fmt.Printf("• %s (Score: %.4f)\n", content, scoredPoint.Score)
}
// → Treffer:
// → • Go hat einen integrierten HTTP-Server im Paket net/http. (Score: 0.8765)
}
⚠ Häufiger Fehler: Die Wahl der Vektordatenbank nur nach Performance zu treffen. pgvector ist ideal, wenn Sie bereits PostgreSQL verwenden und die Daten zusammen mit relationalen Daten speichern wollen — man kann sie bequem mit SQL kombinieren. Qdrant hingegen bietet spezielle Features für Vektor-Suche wie Filterung nach Metadaten während der Suche (Hybrid Search) und ist als eigenständiger Service einfacher zu skalieren. Für eine detaillierte Entscheidungshilfe verweisen wir auf Modul 6 der Architektur-Lehre zur Datenbankwahl.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
Agent-Loops, Evals & Guardrails in Go
Lektion 70 von 100
Von einfachen Requests zu autonomen Agenten
Ein einfacher API-Aufruf an ein LLM ist eine lineare Interaktion: Request → Response → Fertig. Ein Agent hingegen operiert in einer Schleife und kann selbstständig Informationen beschaffen, Tools aufrufen und Entscheidungen treffen. Das Opening dieses Modul (Lektion 66-69) lässt sich nun zu einem vollständigen Agenten-System kombinieren: Der Agent nutzt Structured Output, um Entscheidungen zu treffen, ruft Tools auf (z. B. Datenbankabfragen oder externe APIs) und iteriert, bis das Ziel erreicht ist.
Der Schlüssel ist der Agent-Loop: Planen (Plan) → Handeln (Act) → Beobachten (Observe) → Reflektieren (Reflect). In Go implementieren wir das als einfache Schleife, in der jede Iteration einen LLM-Call, Tool-Ausführungen und Ergebnis-Bewertungen umfasst.
Der Agent-Loop: Plan – Act – Observe – Reflect
Ein Agent-Loop besteht aus vier Phasen, die in einer Schleife durchlaufen werden: 1) Planen: Das LLM entscheidet, welcheaktion als Nächstes sinnvoll ist. 2) Handeln: Der Agent führt die geplanten Aktionen aus (z. B. Tool-Aufrufe). 3) Beobachten: Die Ergebnisse der Aktionen werden gesammelt. 4) Reflektieren: Das LLM bewertet die Ergebnisse und plant die nächste Iteration. Die Schleife läuft, bis das Ziel erreicht ist oder ein Abbruchkriterium (z. B. maximale Iterationen) greift.
Ein einfacher Agent mit LangChainGo
LangChainGo bietet mit dem agent Paket eine Grundstruktur für Agenten. Hier ein vereinfachtes Beispiel, das Barrierefreiheit zeigt:
package main
import (
"context"
"fmt"
"strings"
"github.com/tmc/langchaingo/agents"
"github.com/tmc/langchaingo/llms/openai"
"github.com/tmc/langchaingo/tools"
)
// SuchTool simuliert eine Suche nach Informationen
type SuchTool struct{}
func (SuchTool) Name() string { return "suchen" }
func (SuchTool) Description() string {
return "Suche nach Informationen. Parameter: query (string). Gibt die Suchergebnisse als String zurück."
}
func (SuchTool) Call(ctx context.Context, input string) (string, error) {
// In echt: Datenbank- oder API-Abfrage
return fmt.Sprintf("Suchergebnis für '%s': Go ist eine Programmiersprache von Google.", input), nil
}
// BerechneTool simuliert eine Berechnung
type BerechneTool struct{}
func (BerechneTool) Name() string { return "berechnen" }
func (BerechneTool) Description() string {
return "Führe eine mathematische Berechnung durch. Parameter: ausdruck (string, z. B. '2+2'). Gibt das Ergebnis als String zurück."
}
func (BerechneTool) Call(ctx context.Context, input string) (string, error) {
// Vereinfacht: nur + und -
parts := strings.Split(input, "+")
if len(parts) == 2 {
return fmt.Sprintf("%d", len(parts[0])+len(parts[1])), nil
}
parts = strings.Split(input, "-")
if len(parts) == 2 {
return fmt.Sprintf("%d", len(parts[0])-len(parts[1])), nil
}
return "Ungültiger Ausdruck", nil
}
func main() {
llm, _ := openai.New(openai.WithToken("sk-..."), openai.WithModel("gpt-4o-mini"))
// Tools erstellen
suchTool := &SuchTool{}
berechneTool := &BerechneTool{}
// Agent erstellen
agent := agents.NewOneShotAgent(
llm,
[]tools.Tool{suchTool, berechneTool},
agents.WithMaxIterations(5), // Guardrail: maximale Iterationen
)
// Agent ausführen
result, err := agent.Run(context.Background(), "Was ist 2+2 und wie viele Buchstaben hat das Ergebnis?")
if err != nil {
fmt.Println("Fehler:", err)
return
}
fmt.Println("Antwort:", result)
// → Antwort: 2+2 = 4. Das Wort "4" hat 1 Buchstabe.
}
Guardrails: Sicherheitsgrenzen für Agenten
Agenten sind mächtig, aber auch riskant. Ohne angemessene Schutzmechanismen können sie:
- Endlosschleifen eingehen (dasselbe Tool immer wieder mit denselben Parametern aufrufen)
- Zu viel Geld kosten (unbegrenzte API-Aufrufe)
- Unsinnige oder schädliche Aktionen ausführen
Drei essenzielle Guardrails sind:
1. Maximale Iterationen
Die einfachste, aber effektivste Maßnahme. Jeder Agent sollte ein Limit für die Anzahl der Schleifendurchläufe haben:
const MaxIterationen = 10
func RunAgent(ctx context.Context, userPrompt string) (string, error) {
messages := []Message{{Role: "user", Content: userPrompt}}
for i := 0; i < MaxIterationen; i++ {
// LLM aufrufen
resp, err := callLLM(ctx, messages)
if err != nil {
return "", err
}
// Prüfen, ob Tool-Aufrufe nötig sind
if len(resp.ToolCalls) == 0 {
return resp.Content, nil
}
// Tools ausführen und Ergebnisse speichern
for _, tc := range resp.ToolCalls {
result := executeTool(tc)
messages = append(messages, Message{
Role: "tool",
Content: result,
})
}
messages = append(messages, resp.ToMessage())
}
return "", fmt.Errorf("maximale Iterationen (%d) erreicht", MaxIterationen)
}
2. Timeout pro Iteration
Jede Iteration sollte ein zeitliches Limit haben, um hängende Tool-Aufrufe oder LLM-Calls zu verhindern:
func RunAgentWithTimeout(ctx context.Context, userPrompt string) (string, error) {
ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
defer cancel()
return RunAgent(ctx, userPrompt)
}
3. Input- und Output-Validierung
Nicht alle Nutzer-Sinputs sind geeignet für einen Agenten. Validieren Sie:
- Length: Zu lange Prompts können das Kontextfenster sprengen
- Content: Prompts mit schädlichen Inhalten oder Injection-Versuchen blockieren
- Output: Tool-Ergebnisse validieren, bevor sie an das LLM zurückgegeben werden
func validateInput(input string) error {
if len(input) > 10000 {
return fmt.Errorf("Prompt zu lang (Max: 10000 Zeichen)")
}
// Weitere Validierungen (z. B. schädliche Inhalte erkennen)
return nil
}
func validateToolResult(toolName, result string) error {
// Tool-spezifische Validierung
switch toolName {
case "datenbank_abfrage":
if len(result) > 5000 {
return fmt.Errorf("Ergebnis zu groß")
}
}
return nil
}
Für eine umfassende Strategie zum Schutz vor Prompt-Injection und zur Definition von Trust-Boundaries empfehlen wir Modul 9 der Sicherheitsarchitektur.
Evals: Automatisierte Qualitätssicherung für AI-Systeme
Ein Agent kann funktionieren, ohne korrekt zu sein. Evals (Evaluierungen) sind automatisierte Tests, die sicherstellen, dass Ihr AI-System die gewünschte Qualität liefert. In Go können wir dafür die bewährten Table-Driven Tests nutzen:
package main
import (
"testing"
)
// Testfall für Prompt-Regressionen
type EvalCase struct {
Name string
Input string
Expected string // Oder eine Validierungsfunktion
}
func TestAgentRegression(t *testing.T) {
cases := []EvalCase{
{
Name: "Einfache Rechnung",
Input: "Was ist 2+2?",
Expected: "4",
},
{
Name: " Komplexere Frage",
Input: "Wie viele Buchstaben hat das Wort 'Programmierung'?",
Expected: "14",
},
}
for _, tc := range cases {
t.Run(tc.Name, func(t *testing.T) {
result, err := RunAgent(context.Background(), tc.Input)
if err != nil {
t.Fatalf("Agent-Fehler: %v", err)
}
if !strings.Contains(result, tc.Expected) {
t.Errorf("Regression! Input: %s\nExpected: %s\nGot: %s",
tc.Input, tc.Expected, result)
}
})
}
}
// Test für Token-Budgets
func TestTokenBudget(t *testing.T) {
longInput := strings.Repeat("a", 10000)
_, err := RunAgent(context.Background(), longInput)
if err == nil {
t.Error("Erwarteter Fehler für zu langen Input, aber keiner erhalten")
}
}
// Test für Iterations-Budget
func TestIterationBudget(t *testing.T) {
// Ein Prompt, der den Agenten in eine Schleife treiben würde
loopInput := "Wiederhole das letzte Tool immer wieder"
_, err := RunAgent(context.Background(), loopInput)
if err == nil {
t.Error("Erwarteter Fehler für zu viele Iterationen, aber keiner erhalten")
}
if !strings.Contains(err.Error(), "maximale Iterationen") {
t.Errorf("Erwarteter Iterations-Fehler, aber erhalten: %v", err)
}
}
⚠ Häufiger Fehler: Evals nur mit "happy path" Testfällen durchführen. Gerade bei Agenten sind es die Edge Cases, die in Produktion Probleme verursachen: leere Eingaben, sehr lange Texte, unerwartete Tool-Ergebnisse, Netzerk-Timeouts. Ohne diese Tests entdecken Sie Regressions erst, wenn sie schon im Produktsystem sind. Table-Driven Tests machen es einfach, eine umfassende Testsuite aufzubauen — nutzen Sie diese Stärke von Go!
Modul-Zusammenfassung & Wochen-Check
Das war Modul 14 — eine Reise durch den gesamten Go-AI-Stack. Wir haben gelernt, wie man:
- Offizielle SDKs von OpenAI und Anthropic nutzt (Lektion 66)
- Structured Output und Tool-Calling mit LangChainGo robust implementiert (Lektion 67)
- Streaming über SSE und WebSockets für Echtzeit-Antworten einsetzt (Lektion 68)
- Embeddings und Vektordatenbanken (pgvector, Qdrant) für RAG nutzt (Lektion 69)
- Agent-Loops baut und mit Guardrails und Evals absichert (Lektion 70)
Damit closes Modul 14. Die wichtigste Erkenntnis des gesamten AI-Teils: AI-Entwicklung ist kein "Schreiben von Text", sondern ein iterativer Engineering-Prozess. Prompts sind Code, Agenten sind Dienste, und Qualitätssicherung ist Pflicht — nicht optional.
Wochen-Check: Beherrschst du folgende Punkte?
- Kennst du die vier Ebenen des Go-AI-Stacks und wann du welches Framework einsetzt?
- Kannst du Structured Output mit LangChainGo so einrichten, dass das LLM zuverlässig strukturierte Daten zurückgibt?
- Verstehst du den Unterschied zwischen SSE und WebSockets und wann du welches Protokoll einsetzt?
- Weißt du, wie man Embeddings mit pgvector oder Qdrant speichert und abfragt?
- Kannst du einen einfachen Agent-Loop mit Guardrails (Max-Iterationen, Timeout, Validierung) bauen?
- Hast du automatisierte Tests (Evals) für deine AI-Systeme geschrieben?
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren: