ערכה למתחילים עם ADK ל-Go

1. מבוא

ADK עם Go

Python עדיין פופולרית לאימון מודלים ולמחקר, אבל הדרישות להפעלת סוכני AI ולתזמור ביניהם תואמות מאוד ליתרונות של Go: חביון נמוך, בו-זמניות (concurrency) ומניעת שגיאות הקלדה.

המעבר מאב-טיפוס לסוכן ייצור מציב אתגרים הנדסיים ש-Go יכולה להתמודד איתם בצורה טובה במיוחד. ההקלדה הסטטית של Go מבטלת שגיאות בזמן ריצה כשמנתחים פלט מובנה של LLM. ה-goroutines הקלילים שלו, שמתחילים עם כמה קילובייט בלבד של זיכרון מחסנית בהשוואה לכמה מגה-בייט עבור שרשורי OS, מאפשרים לסוכנים לטפל באלפי הפעלות מקבילות של כלים ללא התקורה של ניהול שרשורים כבד.

ערכת פיתוח הסוכנים (ADK) של Google מגשרת על הפער בין היתרונות הארכיטקטוניים האלה לבין AI גנרטיבי. במדריך הזה תבנו פרויקט חדש ותפרסו אותו כשירות מיקרו מאובטח ב-Google Cloud.

מה הלאה:

יצירת פרויקט של סוכן שמוכן לייצור באמצעות ערכת המתחילים של סוכנים
שימוש בממשק המשתמש האינטרנטי של ערכת פיתוח הסוכנים המקומית כדי לנפות באגים ולבדוק את הסוכן
פיתוח והבנה של לוגיקה של סוכן ADK מבוסס-Go
הפעלת בדיקות יחידה ובדיקות מקצה לקצה (E2E)
פריסת הסוכן בצורה מאובטחת ב-Cloud Run

מה דרוש לכם?

דפדפן אינטרנט כמו Chrome
פרויקט ב-Google Cloud שהחיוב בו מופעל

‫2. לפני שמתחילים

יצירת פרויקט ב-Google Cloud

אם עדיין אין לכם חשבון:

במסוף Google Cloud, בדף לבחירת הפרויקט, בוחרים פרויקט ב-Google Cloud או יוצרים פרויקט.
הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud.

הפעלת Cloud Shell

‫Cloud Shell היא סביבת שורת פקודה שפועלת ב-Google Cloud וכוללת מראש את הכלים הנדרשים. הוא ישמש כסביבת הפיתוח העיקרית שלכם במעבדה הזו.

לוחצים על Activate Cloud Shell בחלק העליון של מסוף Google Cloud.
אחרי שמתחברים ל-Cloud Shell, מריצים את הפקודה הבאה כדי לאמת את האימות ב-Cloud Shell:

gcloud auth list

מריצים את הפקודה הבאה כדי לוודא שהפרויקט מוגדר לשימוש ב-gcloud:

gcloud config get project

מוודאים שהפרויקט הוא כמו שציפיתם, ואז מריצים את הפקודה הבאה כדי להגדיר את מזהה הפרויקט:

export PROJECT_ID=$(gcloud config get project)

3. איך מתחילים להשתמש בחבילת המתחילים של הסוכן

החדשות הטובות הן שלא צריך להתחיל מאפס. ‫Agent Starter Pack הוא כלי CLI שיוצר מבנה תיקיות מוכן לייצור, כולל צינורות CI/CD, הגדרת תשתית וקוד boilerplate.

כדי להתחיל, פשוט מריצים את הפקודה ליצירת build עם uvx:

uvx agent-starter-pack create

ה-CLI ידריך אתכם בתהליך הגדרה אינטראקטיבי. בפרויקט הזה, בוחרים את האפשרויות הבאות:

שם הפרויקט: my-first-go-agent
תבנית: אפשרות 6 (Go ADK, Go agent with A2A)
‫CI/CD: אפשרות 3 (פעולות GitHub)
אזור: us-central1

הגדרה של חבילת התחלה לסוכנים

אחרי שמופיעה ההודעה הירוקה Success! (הצלחה!), אפשר להמשיך.

הודעת הצלחה

4. הדמיה של הסוכן באופן מקומי

אחת התכונות הנוחות ביותר של ADK היא האפשרות לבצע ניפוי באגים חזותי בנציג לפני הפריסה שלו. כשמריצים את הפקודות שבהמשך, מפעילים שרת פיתוח מקומי עם ממשק משתמש מובנה. כן, יש לו חלון צ'אט, אבל הוא עושה הרבה יותר מזה – הוא עוקב אחרי אירועים, קריאות לכלים ועוד.

עוברים לספריית הפרויקט ומפעילים את ההדמיה:

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

אחרי שהסביבה מתחילה לפעול, פותחים את התצוגה המקדימה באינטרנט ב-Cloud Shell כדי ליצור אינטראקציה עם הסוכן החדש.

הסוכן מוגדר עם דפוס ReAct (Reasoning and Acting) – מסגרת שהפכה לבסיס ב-AI אקטיבי. הלולאה הרציפה של התבנית ReAct, שכוללת את השלבים 'מחשבה', 'פעולה' ו'תצפית', משפרת את יכולת פתרון הבעיות ואת יכולת ההסבר, וכך הופכת את תהליך קבלת ההחלטות של הסוכן לשקוף.

לדוגמה, אם שואלים על מזג האוויר, הסוכן מזהה את הכוונה, מפעיל את הכלי get_weather ומחזיר את הנתונים המובְנים.

ממשק המשתמש של Playground

5. הסבר על הקוד

אחרי שראינו את הסוכן בפעולה, נסתכל על קוד Go שגורם לזה לקרות. הלוגיקה נמצאת ב-agent/agent.go. הקובץ הזה מטפל בהגדרות של כלים, בהגדרת המודל ובאתחול.

ה-ADK משתמש במבני נתונים סטנדרטיים של Go כדי להגדיר איך מודל השפה הגדול (LLM) מתקשר עם הקוד שלכם. כדי להגדיר את פרמטרי הקלט לכלי מזג האוויר שלנו, אנחנו מגדירים מבנה עם תגי json ו-jsonschema:

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

‫GetWeatherResult מגדיר את מבנה הנתונים שמוחזרים לסוכן אחרי הפעלת הכלי:

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

‫GetWeather היא פונקציית Go רגילה שמקבלת את tool.Context ואת מבנה הארגומנטים, מבצעת את הלוגיקה העסקית ומחזירה את מבנה התוצאה:

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

הפונקציה NewRootAgent אחראית להרכבה ולהחזרה של מופע agent.Agent שנדרש למרכז האפליקציות. התהליך מתחיל באתחול של הגדרת המודל, וביצירה של מופע מודל gemini-2.5-flash שמגובה על ידי genai.BackendVertexAI.

לאחר מכן, הוא מגשר על הפער בין קוד Go לבין ה-LLM על ידי עטיפת הפונקציה המקומית GetWeather ב-functiontool. בשלב הזה, הכלי נרשם בשם get_weather ומוצג התיאור הנדרש להקשר של המודל. לבסוף, הוא בונה את הסוכן באמצעות llmagent.New, שמשלב את מודל Gemini שאותחל, את הוראות המערכת שמגדירות את התנהגות הסוכן ואת קטע הכלים הזמינים ליחידה אחת.

// 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. בדיקה

הפרויקט מכיל גם בדיקות יחידה ללוגיקה פנימית וגם בדיקות מקצה לקצה לשילוב עם השרת.

בדוגמה agent/agent_test.go, הפונקציה GetWeather נקראת עם חבילה של תרחישי בדיקה כדי לוודא שמחרוזת הפלט תואמת לציפיות.

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

בבדיקות מקצה לקצה מוודאים שהסוכן פועל בצורה תקינה כשהוא מופעל כשרת, ובפרט בודקים שתמיכת הפרוטוקול A2A או Agent-to-Agent פועלת בצורה תקינה. בבדיקות מקצה לקצה מופעל מופע אמיתי של השרת, נשלחות אליו בקשות HTTP והתגובות נבדקות.

לפניך קטע מתוך 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")
    // ...
}

אפשר להריץ את כל הבדיקות באופן מקומי באמצעות קובץ ה-makefile:

make test

7. פריסה

כשמוכנים לשתף את הסוכן עם העולם או לקשר אותו למערכות אקולוגיות של ייצור, מריצים את פקודת הפריסה שכלולה:

make deploy

הפקודה הזו יוצרת באופן אוטומטי את האפליקציה מקוד המקור באמצעות Google Cloud Buildpacks, באמצעות הטריגר של הדגל --source .. הוא פורס את האימג' הזה ב-Cloud Run עם כמה דגלים שעברו אופטימיזציה לייצור: --memory "4Gi" כדי לספק מספיק זיכרון RAM לפעולות של LLM, ו---no-cpu-throttling כדי לוודא שה-CPU יישאר מוקצה 24 שעות ביממה, מה שיכול למנוע הפעלות קרות ולהבטיח תגובות מהירות באינטראקציות עם הסוכן.

כדי להבטיח שהסוכן יפעל בצורה מאובטחת, המערכת נפרסת עם הגדרה מחמירה באמצעות --no-allow-unauthenticated לחסימת כל הגישה הציבורית כברירת מחדל, ונדרש אימות של ניהול הזהויות והרשאות הגישה (IAM) לכל הבקשות. הוא גם מוסיף משתני סביבה, כולל GOOGLE_GENAI_USE_VERTEXAI=True.

כתובת ה-URL של שירות הפריסה

הפעלת IAP

אחרי שמפעילים את IAP ומוסיפים את כתובת האימייל כמשתמש ראשי, אפשר לעבור לכתובת ה-URL של השירות שמופיעה אחרי הפריסה. כשמציגים את כתובת ה-URL הבסיסית של השירות, אפשר לראות את כרטיס הסוכן שנפרס. מבנה ה-JSON הזה משמש כממשק סטנדרטי של הסוכן, ומאפשר לסוכנים אחרים, למנהלי תזמור או לממשקי משתמש שפונים למשתמשים לגלות אותו ולצרוך אותו באופן דינמי.

כרטיס הסוכן

8. הסרת המשאבים

כדי להימנע מחיובים שוטפים בחשבון Google Cloud, צריך למחוק את המשאבים שנוצרו במהלך ה-Codelab הזה.

אתם יכולים למחוק את הפרויקט בענן, וכך החיוב על כל המשאבים שנעשה בהם שימוש בתוכו ייפסק:

gcloud projects delete $PROJECT_ID

אולי תרצו גם למחוק את ספריית הפרויקט של ה-codelab מהדיסק של Cloud Shell:

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

9. מעולה!

🎊 המשימה הושלמה! הצלחתם ליצור שלד, לבדוק ולפרוס סוכן AI ב-Go באמצעות ערכת פיתוח הסוכנים.

מה השגתם:

יצירת תשתית ראשונית מובנית באמצעות ערכת כלים ליצירת סוכנים
אימתתם ובדקתם את ממשק המשתמש והקוד של הסוכן באופן מקומי
התעמקתי בסכימות המוקלדות ובמיפוי הפונקציות של התנהגויות מודל שפה גדול (LLM) לאובייקטים של Go
פרסתם את שירות Go ב-Cloud Run

מה השלב הבא?

מסמכי ADK: מדריכים מלאים בנושאים כמו דפוסים מתקדמים, תזמור של כמה סוכנים ומערכות זיכרון
המדריך לשימוש בסוכנים בתחילת הדרך: עיון בתבניות, כולל מערכות מרובות סוכנים וארכיטקטורות מורכבות
מאמרי העזרה של Cloud Run: ניתוח מעמיק של אופטימיזציה של הביצועים, אסטרטגיות התאמה לעומס ושיטות מומלצות לאבטחה
‫Go Concurrency Patterns: הבנה של goroutines וערוצים תעזור לכם לבנות כלים יעילים יותר לסוכנים
‫Vertex AI Agent Engine: תשתית סוכנים מנוהלת עם תזמור וכלים מובנים