Agent Starter Pack พร้อม ADK สำหรับ Go

1. บทนำ

ADK ด้วย Go

แม้ว่า Python จะยังคงเป็นที่นิยมสำหรับการฝึกโมเดลและการวิจัย แต่ข้อกำหนดในการให้บริการและจัดระเบียบเอเจนต์ AI ก็สอดคล้องกับจุดแข็งของ Go อย่างใกล้ชิด ได้แก่ เวลาในการตอบสนองต่ำ การทำงานพร้อมกันสูง และความปลอดภัยของประเภท

การเปลี่ยนจากเอเจนต์ต้นแบบไปเป็นเอเจนต์เวอร์ชันที่ใช้งานจริงจะทำให้เกิดความท้าทายด้านวิศวกรรมที่ Go สามารถจัดการได้อย่างยอดเยี่ยม การพิมพ์แบบคงที่ของ Go ช่วยขจัดข้อผิดพลาดขณะรันไทม์เมื่อแยกวิเคราะห์เอาต์พุต LLM ที่มีโครงสร้าง Goroutine ที่มีน้ำหนักเบาซึ่งเริ่มต้นด้วยหน่วยความจำสแต็กเพียงไม่กี่กิโลไบต์เมื่อเทียบกับเธรดของระบบปฏิบัติการที่มีขนาดหลายเมกะไบต์ ช่วยให้เอเจนต์จัดการการเรียกใช้เครื่องมือพร้อมกันหลายพันรายการได้โดยไม่ต้องมีค่าใช้จ่ายในการจัดการเธรดที่หนักหน่วง

Agent Development Kit (ADK) ของ Google ช่วยอุดช่องว่างระหว่างข้อได้เปรียบด้านสถาปัตยกรรมเหล่านี้กับ Generative AI ในคู่มือนี้ คุณจะได้สร้างโครงร่างโปรเจ็กต์ใหม่และนำไปใช้งานเป็นไมโครเซอร์วิสที่ปลอดภัยใน Google Cloud

สิ่งที่คุณต้องดำเนินการ

  • สร้างโครงร่างโปรเจ็กต์เอเจนต์ที่พร้อมใช้งานจริงโดยใช้ Agent Starter Pack
  • ใช้เว็บ UI ของ Agent Development Kit ในเครื่องเพื่อแก้ไขข้อบกพร่องและทดสอบ Agent
  • พัฒนาและทําความเข้าใจตรรกะของเอเจนต์ ADK ที่อิงตาม Go
  • เรียกใช้การทดสอบหน่วยและการทดสอบตั้งแต่ต้นจนจบ (E2E)
  • ติดตั้งใช้งานเอเจนต์ใน Cloud Run อย่างปลอดภัย

สิ่งที่คุณต้องมี ได้แก่

  • เว็บเบราว์เซอร์ เช่น Chrome
  • โปรเจ็กต์ Google Cloud ที่เปิดใช้การเรียกเก็บเงิน

2. ก่อนเริ่มต้น

สร้างโปรเจ็กต์ Google Cloud

หากยังไม่มีบัญชี ให้ทำดังนี้

  1. ในคอนโซล Google Cloud ให้เลือกหรือสร้างโปรเจ็กต์ Google Cloud ในหน้าตัวเลือกโปรเจ็กต์
  2. ตรวจสอบว่าได้เปิดใช้การเรียกเก็บเงินสำหรับโปรเจ็กต์ Cloud แล้ว

เริ่มต้น Cloud Shell

Cloud Shell คือสภาพแวดล้อมบรรทัดคำสั่งที่ทำงานใน Google Cloud ซึ่งโหลดเครื่องมือที่จำเป็นไว้ล่วงหน้า ซึ่งจะเป็นสภาพแวดล้อมการพัฒนาหลักของคุณสำหรับแล็บนี้

  1. คลิกเปิดใช้งาน Cloud Shell ที่ด้านบนของคอนโซล Google Cloud
  2. เมื่อเชื่อมต่อกับ Cloud Shell แล้ว ให้เรียกใช้คำสั่งนี้เพื่อยืนยันการตรวจสอบสิทธิ์ใน Cloud Shell
gcloud auth list
  1. เรียกใช้คำสั่งต่อไปนี้เพื่อยืนยันว่าได้กำหนดค่าโปรเจ็กต์ให้ใช้กับ gcloud แล้ว
gcloud config get project
  1. ยืนยันว่าโปรเจ็กต์เป็นไปตามที่คาดไว้ จากนั้นเรียกใช้คำสั่งด้านล่างเพื่อตั้งรหัสโปรเจ็กต์
export PROJECT_ID=$(gcloud config get project)

3. เริ่มต้นใช้งาน Agent Starter Pack

ข่าวดีก็คือคุณไม่ต้องเริ่มต้นใหม่ทั้งหมด Agent Starter Pack เป็นเครื่องมือ CLI ที่สร้างโครงสร้างโฟลเดอร์ที่พร้อมใช้งานจริง ซึ่งรวมถึงไปป์ไลน์ CI/CD, การกำหนดค่าโครงสร้างพื้นฐาน และโค้ด Boilerplate

หากต้องการเริ่มต้นใช้งาน เพียงเรียกใช้คำสั่งสร้างบิลด์ด้วย uvx ดังนี้

uvx agent-starter-pack create

CLI จะแนะนำการตั้งค่าแบบอินเทอร์แอกทีฟให้คุณ สำหรับโปรเจ็กต์นี้ ให้เลือกตัวเลือกต่อไปนี้

  • ชื่อโปรเจ็กต์: my-first-go-agent
  • เทมเพลต: ตัวเลือก 6 (Go ADK, Go agent with A2A)
  • CI/CD: ตัวเลือกที่ 3 (GitHub Actions)
  • ภูมิภาค: us-central1

การตั้งค่า Agent Starter Pack

เมื่อเห็นข้อความสำเร็จ! สีเขียว คุณก็พร้อมดำเนินการต่อ

ข้อความแสดงความสำเร็จ

4. การแสดงภาพ Agent ในเครื่อง

ฟีเจอร์ที่สะดวกที่สุดอย่างหนึ่งของ ADK คือความสามารถในการแก้ไขข้อบกพร่องของเอเจนต์ด้วยภาพก่อนที่จะนําไปใช้งาน การเรียกใช้คำสั่งด้านล่างจะเปิดเซิร์ฟเวอร์การพัฒนาภายในด้วย UI ในตัว ใช่ มีหน้าต่างแชท แต่ก็ทำได้มากกว่านั้นด้วยการติดตามเหตุการณ์ การเรียกใช้เครื่องมือ และอื่นๆ

เปลี่ยนไปที่ไดเรกทอรีโปรเจ็กต์แล้วเริ่ม Playground โดยทำดังนี้

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

เมื่อ Playground ทำงานแล้ว ให้เปิดตัวอย่างเว็บใน Cloud Shell เพื่อโต้ตอบกับเอเจนต์ที่สร้างขึ้นใหม่

เอเจนต์ได้รับการกำหนดค่าด้วยรูปแบบ ReAct (การให้เหตุผลและการดำเนินการ) ซึ่งเป็นเฟรมเวิร์กที่กลายเป็นพื้นฐานใน AI แบบเอเจนต์ ลูปต่อเนื่องของ "ความคิด" "การกระทำ" และ "การสังเกต" ของรูปแบบ ReAct ช่วยเพิ่มการแก้ปัญหาและความสามารถในการตีความ ทำให้กระบวนการตัดสินใจของเอเจนต์มีความโปร่งใส

เช่น หากคุณถามถึงสภาพอากาศ เอเจนต์จะจดจำเจตนา เรียกใช้เครื่องมือ get_weather และแสดงผล Structured Data

UI ของ 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 กำหนดโครงสร้างของข้อมูลที่ส่งคืนไปยัง Agent หลังจากที่เครื่องมือดำเนินการ

// 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 ทำงานได้อย่างถูกต้อง การทดสอบ E2E จะเริ่มต้นอินสแตนซ์จริงของเซิร์ฟเวอร์ ส่งคำขอ 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 เพื่อบล็อกการเข้าถึงแบบสาธารณะทั้งหมดโดยค่าเริ่มต้น และกำหนดให้ใช้การตรวจสอบสิทธิ์ Identity and Access Management (IAM) สำหรับคำขอใดก็ตาม เพื่อให้มั่นใจว่าเอเจนต์จะทำงานอย่างปลอดภัย นอกจากนี้ยังแทรกตัวแปรสภาพแวดล้อม รวมถึง GOOGLE_GENAI_USE_VERTEXAI=True ด้วย

URL ของบริการการติดตั้งใช้งาน

เปิดใช้ IAP

เมื่อเปิดใช้ IAP และเพิ่มอีเมลของคุณเป็นผู้ใช้หลักแล้ว คุณจะไปยัง URL ของบริการที่ระบุไว้หลังการติดตั้งใช้งานได้ การดู URL ของบริการฐานจะช่วยให้คุณเห็นการ์ดตัวแทนที่ติดตั้งใช้งาน โครงสร้าง JSON นี้ทำหน้าที่เป็นอินเทอร์เฟซมาตรฐานของเอเจนต์ ซึ่งช่วยให้เอเจนต์อื่นๆ ตัวจัดสรร หรือ UI ที่ผู้ใช้มองเห็นค้นพบและใช้เอเจนต์ของคุณแบบไดนามิกได้

การ์ดตัวแทน

8. ล้าง

โปรดลบทรัพยากรที่สร้างขึ้นระหว่าง Codelab นี้เพื่อหลีกเลี่ยงการเรียกเก็บเงินอย่างต่อเนื่องกับบัญชี Google Cloud

คุณลบโปรเจ็กต์ Cloud ได้ ซึ่งจะหยุดการเรียกเก็บเงินสำหรับทรัพยากรทั้งหมดที่ใช้ในโปรเจ็กต์

gcloud projects delete $PROJECT_ID

นอกจากนี้ คุณอาจต้องการลบไดเร็กทอรีโปรเจ็กต์ Codelab ออกจากดิสก์ Cloud Shell ด้วย โดยทำดังนี้

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

9. ยินดีด้วย

🎊 ภารกิจสำเร็จ! คุณได้สร้างโครงร่าง ทดสอบ และติดตั้งใช้งานเอเจนต์ AI ใน Go โดยใช้ Agent Development Kit เรียบร้อยแล้ว

สิ่งที่คุณทำสำเร็จ

  • สร้างโครงร่างพื้นฐานที่มีโครงสร้างเริ่มต้นโดยใช้ Agent Starter Pack
  • ยืนยันและทดสอบ UI และโค้ดของเอเจนต์ในเครื่อง
  • เจาะลึกสคีมาที่พิมพ์และฟังก์ชันที่แมปพฤติกรรมของ LLM กับออบเจ็กต์ Go
  • ทำให้บริการ Go ใช้งานได้ใน Cloud Run

ขั้นตอนต่อไปคืออะไร

  • เอกสารประกอบ ADK: คู่มือฉบับสมบูรณ์เกี่ยวกับรูปแบบขั้นสูง การจัดระเบียบแบบหลายเอเจนต์ และระบบหน่วยความจำ
  • ชุดคู่มือเริ่มต้นสำหรับ Agent: สำรวจเทมเพลต รวมถึงระบบแบบหลาย Agent และสถาปัตยกรรมที่ซับซ้อน
  • เอกสารประกอบของ Cloud Run: เจาะลึกการเพิ่มประสิทธิภาพ กลยุทธ์การปรับขนาด และแนวทางปฏิบัติแนะนำด้านความปลอดภัย
  • รูปแบบการทำงานพร้อมกันของ Go: การทำความเข้าใจ Goroutine และ Channel จะช่วยให้คุณสร้างเครื่องมือเอเจนต์ที่มีประสิทธิภาพมากขึ้น
  • Vertex AI Agent Engine: สำหรับโครงสร้างพื้นฐานของ Agent ที่มีการจัดการพร้อมการจัดระเบียบและเครื่องมือในตัว