Pakiet startowy agenta z ADK dla języka Go

1. Wprowadzenie

Python pozostaje popularny w przypadku trenowania modeli i badań, ale wymagania dotyczące udostępniania i orkiestracji agentów AI są ściśle powiązane z zaletami języka Go: niskim opóźnieniem, dużą liczbą współbieżnych procesów i zabezpieczeniami wpisywania.

Przejście od prototypu do agenta produkcyjnego wiąże się z wyzwaniami inżynieryjnymi, z którymi Go radzi sobie wyjątkowo dobrze. Statyczne typowanie w Go eliminuje błędy czasu działania podczas analizowania strukturalnych danych wyjściowych LLM. Lekkie gorutyny, które zaczynają się od zaledwie kilku kilobajtów pamięci stosu w porównaniu z kilkoma megabajtami w przypadku wątków systemu operacyjnego, umożliwiają agentom obsługę tysięcy równoczesnych wykonań narzędzi bez obciążenia związanego z zarządzaniem wieloma wątkami.

Pakiet Agent Development Kit (ADK) od Google wypełnia lukę między tymi zaletami architektury a generatywną AI. Z tego przewodnika dowiesz się, jak utworzyć nowy projekt i wdrożyć go jako bezpieczną mikrousługę w Google Cloud.

Co musisz zrobić:

• Tworzenie projektu agenta gotowego do wprowadzenia w środowisku produkcyjnym za pomocą pakietu startowego agenta
• Korzystaj z lokalnego interfejsu internetowego pakietu Agent Development Kit, aby debugować i testować agenta.
• Opracowywanie i poznawanie logiki agenta ADK opartej na Go
• Uruchamianie testów jednostkowych i kompleksowych
• Bezpieczne wdrażanie agenta w Cloud Run

Co będzie Ci potrzebne

• przeglądarka, np. Chrome;
• projekt Google Cloud z włączonymi płatnościami;

2. Zanim zaczniesz

Tworzenie projektu Google Cloud

Jeśli jeszcze go nie masz:

1. W konsoli Google Cloud na stronie selektora projektu wybierz lub utwórz projekt w chmurze Google Cloud.
2. Sprawdź, czy w projekcie Cloud włączone są płatności.

Uruchamianie Cloud Shell

Cloud Shell to środowisko wiersza poleceń działające w Google Cloud, które zawiera niezbędne narzędzia. Będzie to Twoje główne środowisko programistyczne w tym module.

1. Kliknij Aktywuj Cloud Shell u góry konsoli Google Cloud.
2. Po połączeniu z Cloud Shell uruchom to polecenie, aby zweryfikować uwierzytelnianie w Cloud Shell:

gcloud auth list

3. Aby sprawdzić, czy projekt jest skonfigurowany do używania z gcloud, uruchom to polecenie:

gcloud config get project

4. Sprawdź, czy projekt jest zgodny z oczekiwaniami, a następnie uruchom to polecenie, aby ustawić identyfikator projektu:

export PROJECT_ID=$(gcloud config get project)

3. Pierwsze kroki z pakietem startowym dla agentów

Dobra wiadomość jest taka, że nie musisz zaczynać od zera. Pakiet startowy agenta to narzędzie wiersza poleceń, które tworzy strukturę folderów gotową do wdrożenia w środowisku produkcyjnym, w tym potoki CI/CD, konfigurację infrastruktury i powtarzalny kod.

Aby rozpocząć, uruchom polecenie tworzenia kompilacji z parametrem uvx:

uvx agent-starter-pack create

Interfejs wiersza poleceń przeprowadzi Cię przez interaktywną konfigurację. W przypadku tego projektu wybierz te opcje:

• Nazwa projektu: my-first-go-agent
• Szablon: opcja 6 (Go ADK, Go agent z A2A)
• CI/CD: opcja 3 (Działania na GitHubie)
• Region: us-central1

Narzędzie automatycznie uwierzytelnia się w Google Cloud, włącza niezbędne interfejsy Vertex AI API i konfiguruje środowisko lokalne.

Gdy zobaczysz zielony komunikat Sukces!, możesz przejść dalej.

4. Lokalna wizualizacja agenta

Jedną z najwygodniejszych funkcji ADK jest możliwość wizualnego debugowania agenta przed jego wdrożeniem. Uruchamiając poniższe polecenia, uruchomisz lokalny serwer programistyczny z wbudowanym interfejsem. Tak, ma okno czatu, ale to nie wszystko. Śledzi też wydarzenia, wywołania narzędzi i inne elementy.

Przejdź do katalogu projektu i uruchom środowisko testowe:

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

Gdy plac zabaw będzie działać, otwórz podgląd w Cloud Shell, aby korzystać z nowo utworzonego agenta.

Agent jest skonfigurowany zgodnie z wzorcem ReAct (Reasoning and Acting), czyli strukturą, która stała się podstawą agentowej AI. Ciągła pętla „Myśl”, „Działanie” i „Obserwacja” w wzorcu ReAct zwiększa zdolność rozwiązywania problemów i interpretowalność, dzięki czemu proces podejmowania decyzji przez agenta jest przejrzysty.

Jeśli na przykład zapytasz o pogodę, agent rozpozna intencję, wywoła narzędzie get_weather i zwróci dane strukturalne.

5. Zrozumienie kodu

Skoro już widzieliśmy agenta w działaniu, przyjrzyjmy się kodowi Go, który to umożliwia. Logika znajduje się w pliku agent/agent.go. Ten plik zawiera definicje narzędzi, konfigurację modelu i inicjowanie.

ADK używa standardowych struktur Go do określania sposobu interakcji dużego modelu językowego (LLM) z Twoim kodem. Aby zdefiniować parametry wejściowe naszego narzędzia pogodowego, definiujemy strukturę z tagami json i jsonschema:

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

GetWeatherResult określa strukturę danych zwracanych do agenta po wykonaniu narzędzia:

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

GetWeather to standardowa funkcja Go, która przyjmuje tool.Context i strukturę argumentów, wykonuje logikę biznesową i zwraca strukturę wyników:

// 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
}

Funkcja NewRootAgent odpowiada za tworzenie i zwracanie instancji agent.Agent wymaganej przez program uruchamiający aplikację. Zaczyna się od zainicjowania konfiguracji modelu i utworzenia instancji modelu gemini-2.5-flash opartej na genai.BackendVertexAI.

Następnie wypełnia lukę między kodem Go a LLM, opakowując lokalną funkcję GetWeather w functiontool. Ten krok rejestruje narzędzie pod nazwą get_weather i zawiera niezbędny opis kontekstu modelu. Na koniec tworzy agenta za pomocą funkcji llmagent.New, która łączy zainicjowany model Gemini, instrukcje systemowe określające zachowanie agenta i wycinek dostępnych narzędzi w jedną całość.

// 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. Testowanie

Projekt zawiera zarówno testy jednostkowe logiki wewnętrznej, jak i testy kompleksowe integracji z serwerem.

W agent/agent_test.go funkcja GetWeather jest wywoływana z zestawem przypadków testowych, aby sprawdzić, czy ciąg wyjściowy jest zgodny z oczekiwaniami.

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)
			}
		})
	}
}

Testy kompleksowe sprawdzają, czy agent działa prawidłowo jako serwer, a w szczególności czy protokół A2A lub Agent-to-Agent jest obsługiwany prawidłowo. Testy E2E uruchamiają rzeczywistą instancję serwera, wysyłają do niej żądania HTTP i sprawdzają odpowiedzi.

Oto fragment ze strony 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")
    // ...
}

Wszystkie testy możesz uruchomić lokalnie za pomocą pliku makefile:

make test

7. Wdrożenie

Gdy będziesz gotowy(-a) do udostępnienia agenta lub połączenia go z ekosystemami produkcyjnymi, uruchom dołączone polecenie wdrażania:

make deploy

To polecenie automatycznie kompiluje aplikację ze źródła za pomocą pakietów kompilacji Google Cloud, co jest wywoływane przez flagę --source .. Wdraża ten obraz w Cloud Run z kilkoma flagami zoptymalizowanymi pod kątem produkcji: --memory "4Gi", aby zapewnić wystarczającą ilość pamięci RAM na potrzeby operacji LLM, oraz --no-cpu-throttling, aby zagwarantować, że procesor będzie przydzielony przez całą dobę, co może zapobiec uruchamianiu „na zimno” i zapewnić szybkie odpowiedzi w interakcjach z agentem.

Aby zapewnić bezpieczne działanie agenta, system jest wdrażany ze ścisłą konfiguracją przy użyciu --no-allow-unauthenticated, która domyślnie blokuje cały dostęp publiczny i wymaga uwierzytelniania w usłudze Identity and Access Management (IAM) w przypadku wszystkich żądań. Wstrzykuje też zmienne środowiskowe, w tym GOOGLE_GENAI_USE_VERTEXAI=True.

Ponieważ aplikacja jest zabezpieczona, musisz włączyć Identity-Aware Proxy (IAP), aby bezpiecznie uzyskać do niej dostęp w przeglądarce. Szczegółowe instrukcje znajdziesz w dokumentacji Cloud w sekcji Włączanie IAP w Cloud Run.

Gdy IAP jest włączona, a Twój adres e-mail został dodany jako podmiot, możesz przejść do adresu URL usługi podanego po wdrożeniu. Wyświetlenie podstawowego adresu URL usługi umożliwia wyświetlenie wdrożonej karty agenta. Ta struktura JSON służy jako standardowy interfejs agenta, dzięki czemu może być dynamicznie wykrywana i wykorzystywana przez innych agentów, orkiestratorów lub interfejsy użytkownika.

8. Czyszczenie

Aby uniknąć obciążenia konta Google Cloud bieżącymi opłatami, usuń zasoby utworzone podczas tego ćwiczenia.

Możesz usunąć projekt w chmurze, co spowoduje zaprzestanie naliczania opłat za wszelkie zasoby wykorzystywane w ramach tego projektu:

gcloud projects delete $PROJECT_ID

Możesz też usunąć katalog projektu z ćwiczeniami z dysku Cloud Shell:

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

9. Gratulacje!

🎊 Misja ukończona! Udało Ci się utworzyć szkielet, przetestować i wdrożyć agenta AI w języku Go za pomocą pakietu Agent Development Kit.

Co udało Ci się osiągnąć:

• Utworzenie początkowej strukturalnej linii bazowej za pomocą pakietu startowego agenta
• sprawdzanie i testowanie interfejsu i kodu agenta lokalnie;
• Zbadanie schematów typów i funkcji mapujących zachowania LLM na obiekty Go
• wdrożono usługę Go w Cloud Run,

Co dalej?

• Dokumentacja ADK: pełne przewodniki po zaawansowanych wzorcach, zarządzaniu wieloma agentami i systemach pamięci.
• Pakiet startowy agenta: poznaj szablony, w tym systemy wieloagentowe i złożone architektury.
• Dokumentacja Cloud Run: szczegółowe informacje o optymalizacji wydajności, strategiach skalowania i sprawdzonych metodach w zakresie bezpieczeństwa.
• Go Concurrency Patterns: zrozumienie goroutines i kanałów pomoże Ci tworzyć bardziej wydajne narzędzia agenta.
• Vertex AI Agent Engine: zarządzana infrastruktura agentów z wbudowaną orkiestracją i narzędziami.