Starterpaket für KI-Agenten mit dem ADK für Go

1. Einführung

Python ist zwar weiterhin beliebt für das Trainieren von Modellen und für die Forschung, die Anforderungen für das Bereitstellen und Orchestrieren von KI-Agents stimmen jedoch eng mit den Stärken von Go überein: niedrige Latenz, hohe Parallelität und Typsicherheit.

Der Übergang von einem Prototyp zu einem Produktions-Agenten bringt technische Herausforderungen mit sich, die Go hervorragend bewältigen kann. Durch die statische Typisierung von Go werden Laufzeitfehler beim Parsen strukturierter LLM-Ausgaben vermieden. Die schlanken Goroutines, die mit nur wenigen Kilobyte an Stackspeicher beginnen, im Vergleich zu mehreren Megabyte für Betriebssystem-Threads, ermöglichen es Agents, Tausende von gleichzeitigen Tool-Ausführungen ohne den Overhead einer aufwendigen Thread-Verwaltung zu verarbeiten.

Das Agent Development Kit (ADK) von Google schließt die Lücke zwischen diesen architektonischen Vorteilen und generativer KI. In diesem Leitfaden erstellen Sie ein neues Projekt und stellen es als sicheren Microservice in Google Cloud bereit.

Aufgaben:

• Mit dem Agent Starter Pack ein produktionsreifes Agent-Projekt erstellen
• Lokale Web-UI des Agent Development Kit zum Debuggen und Testen Ihres Agenten verwenden
• Go-basierte ADK-Agentenlogik entwickeln und verstehen
• Unit- und End-to-End-Tests (E2E) ausführen
• Agenten sicher in Cloud Run bereitstellen

Sie benötigen Folgendes:

• Ein Webbrowser wie Chrome
• Ein Google Cloud-Projekt mit aktivierter Abrechnung

2. Hinweis

Google Cloud-Projekt erstellen

Falls Sie noch kein Konto haben:

1. Wählen Sie in der Google Cloud Console auf der Seite zur Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
2. Die Abrechnung für das Cloud-Projekt muss aktiviert sein.

Cloud Shell starten

Cloud Shell ist eine Befehlszeilenumgebung, die in Google Cloud ausgeführt wird und mit den erforderlichen Tools vorinstalliert ist. Sie dient als primäre Entwicklungsumgebung für dieses Lab.

1. Klicken Sie oben in der Google Cloud Console auf Cloud Shell aktivieren.
2. Sobald Sie mit Cloud Shell verbunden sind, führen Sie diesen Befehl aus, um Ihre Authentifizierung in Cloud Shell zu bestätigen:

gcloud auth list

3. Führen Sie den folgenden Befehl aus, um zu bestätigen, dass Ihr Projekt für die Verwendung mit gcloud konfiguriert ist:

gcloud config get project

4. Prüfen Sie, ob das Projekt wie erwartet ist, und führen Sie dann den folgenden Befehl aus, um Ihre Projekt-ID festzulegen:

export PROJECT_ID=$(gcloud config get project)

3. Erste Schritte mit dem Agent Starter Pack

Die gute Nachricht ist, dass Sie nicht bei null anfangen müssen. Das Agent Starter Pack ist ein CLI-Tool, mit dem eine produktionsreife Ordnerstruktur erstellt wird, einschließlich CI/CD-Pipelines, Infrastrukturkonfiguration und Boilerplate-Code.

Führen Sie dazu einfach den Befehl zum Erstellen des Builds mit uvx aus:

uvx agent-starter-pack create

Die Befehlszeile führt Sie durch eine interaktive Einrichtung. Wählen Sie für dieses Projekt die folgenden Optionen aus:

• Projektname: my-first-go-agent
• Vorlage:Option 6 (Go ADK, Go-Agent mit A2A)
• CI/CD:Option 3 (GitHub Actions)
• Region : us-central1

Das Tool authentifiziert sich automatisch bei Google Cloud, aktiviert die erforderlichen Vertex AI-APIs und konfiguriert Ihre lokale Umgebung.

Sobald die grüne Meldung Success! (Erfolg) angezeigt wird, können Sie fortfahren.

4. Agent lokal visualisieren

Eine der praktischsten Funktionen des ADK ist die Möglichkeit, Ihren Agenten vor der Bereitstellung visuell zu debuggen. Wenn Sie die folgenden Befehle ausführen, starten Sie einen lokalen Entwicklungsserver mit einer integrierten Benutzeroberfläche. Ja, es gibt ein Chatfenster, aber es geht weit darüber hinaus, da Ereignisse, Tool-Aufrufe und mehr nachvollzogen werden.

Wechseln Sie in Ihr Projektverzeichnis und starten Sie die Playground-Umgebung:

cd my-first-go-agent
make install
make playground

Sobald der Playground ausgeführt wird, öffnen Sie die Webvorschau in Cloud Shell, um mit dem neu erstellten Agenten zu interagieren.

Der Agent ist mit einem ReAct-Muster (Reasoning and Acting) konfiguriert, einem Framework, das in der agentischen KI von grundlegender Bedeutung ist. Der kontinuierliche Zyklus von „Thought“ (Gedanke), „Action“ (Aktion) und „Observation“ (Beobachtung) des ReAct-Musters verbessert die Problemlösung und Interpretierbarkeit und macht den Entscheidungsprozess des Agenten transparent.

Wenn Sie beispielsweise nach dem Wetter fragen, erkennt der Agent den Intent, ruft das Tool get_weather auf und gibt die strukturierten Daten zurück.

5. Code verstehen

Nachdem wir den Agent in Aktion gesehen haben, sehen wir uns den Go-Code an, der das ermöglicht. Die Logik befindet sich in agent/agent.go. Diese Datei enthält Tooldefinitionen, die Modellkonfiguration und die Initialisierung.

Im ADK werden Standard-Go-Structs verwendet, um zu definieren, wie das Large Language Model (LLM) mit Ihrem Code interagiert. Um die Eingabeparameter für unser Wettertool zu definieren, definieren wir eine Struktur mit json- und jsonschema-Tags:

type GetWeatherArgs struct {
    City string `json:"city" jsonschema:"City name to get weather for"`
}

GetWeatherResult definiert die Struktur der Daten, die nach der Ausführung des Tools an den Agent zurückgegeben werden:

// GetWeatherResult defines the output for the get_weather tool.
type GetWeatherResult struct {
	Weather string `json:"weather"`
}

GetWeather ist eine Standard-Go-Funktion, die tool.Context und die Argumentstruktur akzeptiert, die Geschäftslogik ausführt und die Ergebnisstruktur zurückgibt:

// GetWeather returns mock weather data for a city.
func GetWeather(_ tool.Context, args GetWeatherArgs) (GetWeatherResult, error) {
	return GetWeatherResult{
		Weather: "It's sunny and 72°F in " + args.City,
	}, nil
}

Die Funktion NewRootAgent ist für das Zusammenstellen und Zurückgeben der agent.Agent-Instanz verantwortlich, die für den App-Launcher erforderlich ist. Zuerst wird die Modellkonfiguration initialisiert und eine gemini-2.5-flash-Modellinstanz erstellt, die von genai.BackendVertexAI unterstützt wird.

Als Nächstes wird die Lücke zwischen dem Go-Code und dem LLM geschlossen, indem die lokale Funktion GetWeather in eine functiontool eingebunden wird. In diesem Schritt wird das Tool mit dem Namen get_weather registriert und die erforderliche Beschreibung für den Kontext des Modells bereitgestellt. Schließlich wird der KI-Agent mit llmagent.New erstellt. Dabei werden das initialisierte Gemini-Modell, die Systemanweisungen, die das Verhalten des KI-Agenten definieren, und die verfügbaren Tools in einer einzigen Einheit kombiniert.

// NewRootAgent creates and returns the root agent with all configured tools.
func NewRootAgent(ctx context.Context) (agent.Agent, error) {
	model, err := gemini.NewModel(ctx, "gemini-2.5-flash", &genai.ClientConfig{
		Backend: genai.BackendVertexAI,
	})

	weatherTool, err := functiontool.New(functiontool.Config{
		Name:        "get_weather",
		Description: "Get the current weather for a city.",
	}, GetWeather)

	rootAgent, err := llmagent.New(llmagent.Config{
		Name:        "my-first-go-agent",
		Model:       model,
		Description: "A helpful AI assistant.",
		Instruction: "You are a helpful AI assistant designed to provide accurate and useful information.",
		Tools:       []tool.Tool{weatherTool},
	})
	// ... (additional logic omitted for brevity)
	return rootAgent, nil
}

6. Test

Das Projekt enthält sowohl Unit-Tests für die interne Logik als auch End-to-End-Tests für die Serverintegration.

In agent/agent_test.go wird die Funktion GetWeather mit einer Reihe von Testläufen aufgerufen, um zu prüfen, ob der Ausgabestring den Erwartungen entspricht.

func TestGetWeather(t *testing.T) {
	// tests struct initialized with "San Francisco" and "New York"

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			// Pass nil for tool.Context since GetWeather doesn't use it
			result, err := GetWeather(nil, GetWeatherArgs{City: tt.city})
			if err != nil {
				t.Fatalf("GetWeather() error = %v", err)
			}
			if !strings.Contains(result.Weather, tt.wantCity) {
				t.Errorf("GetWeather() = %v, want city %v in response", result.Weather, tt.wantCity)
			}
		})
	}
}

Die End-to-End-Tests prüfen, ob der Agent korrekt funktioniert, wenn er als Server ausgeführt wird. Dabei wird insbesondere geprüft, ob die Unterstützung für das A2A- oder Agent-to-Agent-Protokoll korrekt funktioniert. Bei E2E-Tests wird eine echte Instanz des Servers gestartet, an die HTTP-Anfragen gesendet werden. Anschließend werden die Antworten geprüft.

Hier ist ein Ausschnitt aus e2e/integration/server_e2e_test.go:

func TestA2AMessageSend(t *testing.T) {
    if testing.Short() { t.Skip("Skipping E2E test in short mode") }

    // Start server (local variable to avoid race conditions)
    t.Log("Starting server process")
    serverProcess := startServer(t)
    defer stopServer(t, serverProcess)

    if !waitForServer(t, 90*time.Second) {
	    t.Fatal("Server failed to start")
    }
    t.Log("Server process started")
    // ...
}

Sie können alle Tests lokal mit dem Makefile ausführen:

make test

7. Bereitstellung

Wenn Sie Ihren Agenten für die Öffentlichkeit freigeben oder mit Produktionsökosystemen verbinden möchten, führen Sie den enthaltenen Bereitstellungsbefehl aus:

make deploy

Mit diesem Befehl wird Ihre Anwendung automatisch aus dem Quellcode erstellt. Dazu werden Google Cloud-Buildpacks verwendet, die durch das Flag --source . ausgelöst werden. Das Image wird mit mehreren für die Produktion optimierten Flags in Cloud Run bereitgestellt: --memory "4Gi", um ausreichend RAM für LLM-Vorgänge bereitzustellen, und --no-cpu-throttling, um sicherzustellen, dass die CPU rund um die Uhr zugewiesen bleibt. So können Kaltstarts vermieden und schnelle Antworten bei Agent-Interaktionen gewährleistet werden.

Damit Ihr Agent sicher ausgeführt wird, wird das System mit einer strengen Konfiguration bereitgestellt, die --no-allow-unauthenticated verwendet, um standardmäßig alle öffentlichen Zugriffe zu blockieren. Für alle Anfragen ist eine IAM-Authentifizierung (Identity and Access Management) erforderlich. Außerdem werden Umgebungsvariablen wie GOOGLE_GENAI_USE_VERTEXAI=True eingefügt.

Da Ihre App gesichert ist, müssen Sie Identity-Aware Proxy (IAP) aktivieren, um sicher über einen Browser darauf zuzugreifen. Die Cloud-Dokumentation enthält eine Schritt-für-Schritt-Anleitung unter IAP für Cloud Run aktivieren.

Sobald IAP aktiviert und Ihre E-Mail-Adresse als Prinzipal hinzugefügt wurde, können Sie die nach der Bereitstellung bereitgestellte Dienst-URL aufrufen. Wenn Sie die Basis-Dienst-URL aufrufen, können Sie die bereitgestellte Agent-Karte sehen. Diese JSON-Struktur dient als Standardschnittstelle Ihres Agenten, sodass er dynamisch von anderen Agenten, Orchestratoren oder benutzerorientierten Benutzeroberflächen erkannt und verwendet werden kann.

8. Bereinigen

Löschen Sie die in diesem Codelab erstellten Ressourcen, um zu vermeiden, dass Ihrem Google Cloud-Konto laufende Gebühren in Rechnung gestellt werden.

Sie können Ihr Cloud-Projekt löschen, um die Abrechnung für alle darin verwendeten Ressourcen zu beenden:

gcloud projects delete $PROJECT_ID

Möglicherweise möchten Sie auch das Codelab-Projektverzeichnis von Ihrer Cloud Shell-Festplatte löschen:

rm -rf ~/my-first-go-agent

9. Glückwunsch!

🎊 Mission abgeschlossen! Sie haben mithilfe des Agent Development Kit erfolgreich einen KI-Agenten in Go erstellt, getestet und bereitgestellt.

Das haben Sie erreicht:

• Eine erste strukturierte Baseline mit dem Agent Starter Pack erstellt
• Die Benutzeroberfläche und der Code des Agents wurden lokal überprüft und getestet.
• Detaillierte Informationen zu den typisierten Schemas und Funktionen, die LLM-Verhaltensweisen Go-Objekten zuordnen
• Go-Dienst in Cloud Run bereitgestellt

Nächste Schritte

• ADK-Dokumentation: Vollständige Anleitungen zu erweiterten Mustern, Multi-Agent-Orchestrierung und Speichersystemen
• Starterpaket für Agents: Vorlagen, einschließlich Multi-Agenten-Systeme und komplexe Architekturen
• Cloud Run-Dokumentation: Detaillierte Informationen zur Leistungsoptimierung, zu Skalierungsstrategien und zu Best Practices für die Sicherheit
• Go Concurrency Patterns: Wenn Sie Goroutines und Channels verstehen, können Sie effizientere Agent-Tools entwickeln.
• Vertex AI Agent Engine: Für verwaltete Agent-Infrastruktur mit integrierter Orchestrierung und integrierten Tools