Schnellstart

Quelldateien

Diese Seite wurde aus den folgenden Quelldateien erstellt:

• README.md
• examples/quickstart/main.go
• go.mod
• examples/a2a/main.go
• examples/mcp/main.go
• examples/web/main.go
• examples/rest/main.go
• examples/telemetry/main.go
• examples/vertexai/agent.go
• cmd/internal/adkcli/main.go

Das Agent Development Kit (ADK) für Go ist ein flexibles und modulares Framework, das Softwareentwicklungsprinzipien auf die Erstellung von KI-Agenten anwendet. Es ist darauf ausgelegt, das Erstellen, Bereitstellen und Orchestrieren von Agenten-Workflows zu vereinfachen – von einfachen Aufgaben bis hin zu komplexen Systemen. Die Go-Version ist ideal für Entwickler, die Cloud-native Agenten-Anwendungen erstellen und dabei die Stärken von Go in Bezug auf Nebenläufigkeit und Leistung nutzen möchten (README.md:1-53).

Einführung und Installation

Das ADK Go zeichnet sich durch mehrere Hauptmerkmale aus: Es ist idiomatisch Go konzipiert, bietet ein reichhaltiges Tool-Ökosystem, ermöglicht Code-First-Entwicklung, unterstützt modulare Multi-Agenten-Systeme und lässt sich überall deployen, mit starker Unterstützung für Cloud-native Umgebungen wie Google Cloud Run (README.md:32-39).

Systemanforderungen

Das Projekt erfordert Go 1.25.0 und ist unter der Apache 2.0 Lizenz lizenziert (go.mod:1-3). Die wichtigsten Abhängigkeiten umfassen:

(go.mod:5-37)

Installation

Um ADK Go zu einem Projekt hinzuzufügen, führen Sie den folgenden Befehl aus:

bash
1go get google.golang.org/adk

(README.md:42-46)

Agent-Initialisierung und Konfiguration

Die Erstellung eines Agenten erfolgt in zwei Hauptschritten: Initialisierung des Modells und Konfiguration des LLMAgent.

Modell-Erstellung mit Gemini

Das folgende Beispiel zeigt die Initialisierung eines Gemini-Modells mit API-Key-Authentifizierung:

go
1ctx := context.Background()
2
3model, err := gemini.NewModel(ctx, "gemini-2.5-flash", &genai.ClientConfig{
4    APIKey: os.Getenv("GOOGLE_API_KEY"),
5})
6if err != nil {
7    log.Fatalf("Failed to create model: %v", err)
8}

(examples/quickstart/main.go:34-42)

Die Umgebungsvariable GOOGLE_API_KEY muss vor der Ausführung gesetzt werden. Das Modell gemini-2.5-flash wird als Standard für Schnellstart-Beispiele verwendet.

LLMAgent-Konfiguration

Nach der Modellerstellung wird der LLMAgent mit Name, Beschreibung, Instruktionen und Tools konfiguriert:

go
1a, err := llmagent.New(llmagent.Config{
2    Name:        "weather_time_agent",
3    Model:       model,
4    Description: "Agent to answer questions about the time and weather in a city.",
5    Instruction: "Your SOLE purpose is to answer questions about the current time and weather in a specific city. You MUST refuse to answer any questions unrelated to time or weather.",
6    Tools: []tool.Tool{
7        geminitool.GoogleSearch{},
8    },
9})

(examples/quickstart/main.go:44-52)

Die Instruction-Eigenschaft definiert das Verhalten und die Einschränkungen des Agenten. In diesem Beispiel wird der Agent explizit angewiesen, nur Fragen zu Zeit und Wetter zu beantworten.

Eine alternative Konfigurationsstruktur zeigt das A2A-Beispiel mit einer Factory-Funktion:

go
1agent, err := llmagent.New(llmagent.Config{
2    Name:        "weather_time_agent",
3    Model:       model,
4    Description: "Agent to answer questions about the time and weather in a city.",
5    Instruction: "I can answer your questions about the time and weather in a city.",
6    Tools:       []tool.Tool{geminitool.GoogleSearch{}},
7})

(examples/a2a/main.go:52-58)

Tool-Integration

ADK Go bietet zwei Hauptansätze zur Tool-Integration: direkte Einbindung vordefinierter Tools und MCP-Toolsets für erweiterte Szenarien.

Vordefinierte Tools

Die direkte Einbindung von Tools erfolgt über die Tools-Eigenschaft in der Agent-Konfiguration:

go
1Tools: []tool.Tool{
2    geminitool.GoogleSearch{},
3},

(examples/quickstart/main.go:49-52)

geminitool.GoogleSearch ermöglicht dem Agenten, Websuchen durchzuführen, um aktuelle Informationen abzurufen.

MCP-Toolset-Einbindung

Für komplexere Szenarien unterstützt ADK Go das Model Context Protocol (MCP). Das folgende Beispiel zeigt die Integration eines MCP-Toolsets:

go
1mcpToolSet, err := mcptoolset.New(mcptoolset.Config{
2    Transport: transport,
3})
4if err != nil {
5    log.Fatalf("Failed to create MCP tool set: %v", err)
6}
7
8a, err := llmagent.New(llmagent.Config{
9    Name:        "helper_agent",
10    Model:       model,
11    Description: "Helper agent.",
12    Instruction: "You are a helpful assistant that helps users with various tasks.",
13    Toolsets: []tool.Toolset{
14        mcpToolSet,
15    },
16})

(examples/mcp/main.go:107-123)

MCP unterstützt zwei Transportarten:

• In-Memory-Transport: Für lokale Tools innerhalb derselben Anwendung
• Remote-Transport: Für externe MCP-Server wie GitHub MCP (examples/mcp/main.go:64-86)

Ausführung und Launcher

Die Ausführung eines Agenten erfolgt über das Launcher-System, das verschiedene Ausführungsmodi unterstützt.

Launcher-Konfiguration

Die Standard-Launcher-Einrichtung verwendet agent.NewSingleLoader für einen einzelnen Agenten:

go
1config := &launcher.Config{
2    AgentLoader: agent.NewSingleLoader(a),
3}
4
5l := full.NewLauncher()
6if err = l.Execute(ctx, config, os.Args[1:]); err != nil {
7    log.Fatalf("Run failed: %v\n\n%s", err, l.CommandLineSyntax())
8}

(examples/quickstart/main.go:57-65)

Der Launcher akzeptiert Kommandozeilenargumente über os.Args[1:] und bietet bei Fehlern eine Syntaxhilfe über l.CommandLineSyntax().

Remote-Agent Ausführung

Für verteilte Szenarien kann der Launcher auch mit Remote-Agenten arbeiten:

go
1remoteAgent, err := remoteagent.NewA2A(remoteagent.A2AConfig{
2    Name:            "A2A Weather agent",
3    AgentCardSource: a2aServerAddress,
4})
5
6config := &launcher.Config{
7    AgentLoader: agent.NewSingleLoader(remoteAgent),
8}
9
10l := full.NewLauncher()
11if err = l.Execute(ctx, config, os.Args[1:]); err != nil {
12    log.Fatalf("Run failed: %v\n\n%s", err, l.CommandLineSyntax())
13}

(examples/a2a/main.go:115-131)

Minimales Ausführungsbeispiel

Ein vollständiges, ausführbares Beispiel finden Sie unter examples/quickstart/main.go. Die folgenden Schritten ermöglichen einen Schnellstart:

Schritt 1: Umgebungsvariablen setzen

bash
1export GOOGLE_API_KEY="ihr-api-key-hier"

Schritt 2: Zum Beispielverzeichnis navigieren und ausführen

bash
1cd examples/quickstart
2go run main.go

(examples/quickstart/main.go:34-65)

Verifikation und erwartete Ausgabe

Bei erfolgreicher Ausführung initialisiert der Agent und wartet auf Eingaben. Fehler bei der Modellerstellung führen zu einer Ausgabe ähnlich:

Failed to create model: <fehlerdetails>

(examples/quickstart/main.go:40-42)

Bei Fehlern in der Agent-Konfiguration erscheint:

Failed to create agent: <fehlerdetails>

(examples/quickstart/main.go:53-55)

Häufige Probleme und Lösungen

Problem 1: Fehlender API-Key

Symptom: Fehlermeldung Failed to create model: API key not provided

Lösung: Stellen Sie sicher, dass die Umgebungsvariable GOOGLE_API_KEY korrekt gesetzt ist:

bash
1export GOOGLE_API_KEY="ihr-gültiger-api-key"

(examples/quickstart/main.go:37-39)

Problem 2: Ungültiges Modell

Symptom: Fehlermeldung bei der Modellerstellung

Lösung: Verwenden Sie ein unterstütztes Modell wie gemini-2.5-flash. Die Modellbezeichnung muss exakt übereinstimmen (examples/quickstart/main.go:37).

Problem 3: MCP-Verbindungsfehler

Symptom: Failed to create MCP tool set bei Verwendung von MCP-Tools

Lösung: Für GitHub MCP-Integration stellen Sie sicher, dass GITHUB_PAT gesetzt ist:

bash
1export GITHUB_PAT="ihr-github-personal-access-token"
2export AGENT_MODE="github"

(examples/mcp/main.go:78-86)

Problem 4: Go-Version inkompatibel

Symptom: Kompilierungsfehler aufgrund von Syntax oder Abhängigkeiten

Lösung: Stellen Sie sicher, dass Go 1.25.0 oder höher installiert ist (go.mod:3).

Nächste Schritte

Nach erfolgreicher Einrichtung des Schnellstarts empfiehlt es sich, folgende Themen zu erkunden:

• Multi-Agenten-Systeme: Kombination mehrerer spezialisierter Agenten
• A2A-Protokoll: Agent-To-Agent-Kommunikation für verteilte Systeme (examples/a2a/main.go:1-131)
• Erweiterte Tool-Integration: Nutzung des MCP-Protokolls für externe Tools (examples/mcp/main.go:1-135)
• Deployment: Containerisierung und Cloud-Deployment auf Google Cloud Run
• Telemetrie: Integration von OpenTelemetry für Observability (go.mod:20-26)

Die offizielle Dokumentation unter google.github.io/adk-docs/ bietet detaillierte Anleitungen für diese Themen (README.md:18).