حزمة أدوات المبتدئين في "وكيل Gemini" مع حزمة تطوير التطبيقات (ADK) لـ Go

1. مقدمة

ADK with Go

على الرغم من أنّ لغة Python لا تزال رائجة في تدريب النماذج والأبحاث، فإنّ متطلبات تقديم وتنظيم وكلاء الذكاء الاصطناعي تتوافق بشكل كبير مع مزايا لغة Go، وهي: زمن الاستجابة المنخفض، والتزامن العالي، ومنع أخطاء الكتابة.

يؤدي الانتقال من نموذج أولي إلى وكيل إنتاج إلى ظهور تحديات هندسية يمكن للغة Go التعامل معها بشكل جيد للغاية. تساعد الكتابة الثابتة في Go على التخلص من أخطاء وقت التشغيل عند تحليل نواتج نماذج اللغات الكبيرة المنظَّمة. تتيح إجراءات goroutines الخفيفة، التي تبدأ ببضعة كيلوبايت فقط من ذاكرة التخزين المؤقت مقارنةً بعدة ميغابايت لخيوط نظام التشغيل، للوكلاء التعامل مع آلاف عمليات تنفيذ الأدوات المتزامنة بدون عبء إدارة الخيوط الثقيلة.

تعمل حزمة تطوير الوكلاء (ADK) من Google على سدّ الفجوة بين هذه المزايا المعمارية والذكاء الاصطناعي التوليدي. في هذا الدليل، ستنشئ مشروعًا جديدًا وتنشره كخدمة مصغّرة آمنة على Google Cloud.

الإجراءات اللازمة:

  • إنشاء مشروع وكيل جاهز للإنتاج باستخدام "حزمة أدوات إنشاء الوكلاء"
  • استخدام واجهة مستخدم الويب المحلية الخاصة بأداة Agent Development Kit لتصحيح أخطاء الوكيل واختباره
  • تطوير وفهم منطق وكيل ADK المستند إلى Go
  • إجراء اختبارات الوحدات والاختبارات الشاملة
  • نشر الوكيل بأمان على Cloud Run

يلزمك ما يلي:

  • متصفّح ويب، مثل Chrome
  • مشروع على السحابة الإلكترونية من Google Cloud تم تفعيل الفوترة فيه

2. قبل البدء

إنشاء مشروع على Google Cloud

إذا لم يكن لديك حساب:

  1. في Google Cloud Console، في صفحة اختيار المشروع، اختَر مشروعًا على Google Cloud أو أنشِئ مشروعًا.
  2. تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية.

بدء 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 هي أداة سطر أوامر تنشئ بنية مجلد جاهزة للإنتاج، بما في ذلك مسارات التكامل المستمر/التسليم المستمر (CI/CD) وإعدادات البنية الأساسية ورمز النص النموذجي.

للبدء، ما عليك سوى تشغيل أمر إنشاء الإصدار باستخدام uvx:

uvx agent-starter-pack create

سيرشدك واجهة سطر الأوامر خلال عملية إعداد تفاعلية. بالنسبة إلى هذا المشروع، حدِّد الخيارات التالية:

  • اسم المشروع: my-first-go-agent
  • النموذج: الخيار 6 (Go ADK، وكيل Go مع A2A)
  • التكامل المستمر/التسليم المستمر: الخيار 3 (GitHub Actions)
  • المنطقة: us-central1

إعداد "حزمة أدوات الوكيل المبتدئ"

بعد ظهور الرسالة الخضراء تمّت العملية بنجاح، يمكنك المتابعة.

رسالة النجاح

4. تصوُّر الوكيل محليًا

من أبرز ميزات "حزمة تطوير التطبيقات" إمكانية تصحيح أخطاء الوكيل بشكل مرئي قبل نشره. من خلال تنفيذ الأوامر أدناه، يمكنك تشغيل خادم تطوير محلي مزوّد بواجهة مستخدم مدمجة. نعم، يتضمّن نافذة دردشة، ولكنّه يتجاوز ذلك بكثير من خلال تتبُّع الأحداث واستدعاء الأدوات وغير ذلك.

انتقِل إلى دليل مشروعك وابدأ ساحة اللعب:

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

بعد تشغيل مساحة الترميز، افتح معاينة الويب في Cloud Shell للتفاعل مع الوكيل الذي أنشأته حديثًا.

تمّت برمجة الوكيل باستخدام نمط ReAct (الاستدلال والتنفيذ)، وهو إطار عمل أصبح أساسيًا في الذكاء الاصطناعي الوكيل. تعزّز حلقة "التفكير" و"التنفيذ" و"المراقبة" المستمرة في نمط 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 ونموذج اللغة الكبير من خلال تضمين الدالة المحلية 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 أو بروتوكول "الوكيل إلى الوكيل" بشكل صحيح. تبدأ اختبارات 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) كافية لعمليات النماذج اللغوية الكبيرة، و--no-cpu-throttling لضمان بقاء وحدة المعالجة المركزية مخصّصة على مدار الساعة طوال أيام الأسبوع، ما يمكن أن يمنع عمليات البدء البارد ويضمن تقديم ردود سريعة في تفاعلات الوكيل.

لضمان تشغيل الوكيل بشكل آمن، يتم تفعيل النظام بإعدادات صارمة باستخدام --no-allow-unauthenticated لحظر جميع عمليات الوصول العلني تلقائيًا، ما يتطلّب مصادقة إدارة الهوية وإمكانية الوصول لأي طلبات. ويتم أيضًا إدخال متغيرات البيئة، بما في ذلك GOOGLE_GENAI_USE_VERTEXAI=True.

عنوان URL لخدمة النشر

تفعيل عمليات الشراء داخل التطبيق

بعد تفعيل IAP وإضافة بريدك الإلكتروني كمسؤول، يمكنك الانتقال إلى عنوان URL للخدمة المقدَّم بعد النشر. يتيح لك عرض عنوان URL الأساسي للخدمة الاطّلاع على بطاقة الوكيل التي تم نشرها. يعمل هيكل JSON هذا كواجهة عادية للوكيل، ما يتيح اكتشافه واستخدامه بشكل ديناميكي من قِبل وكلاء أو أدوات تنسيق أو واجهات مستخدم أخرى.

بطاقة الوكيل

8. تنظيف

لتجنُّب تكبُّد رسوم مستمرة على حسابك على Google Cloud، احذف الموارد التي تم إنشاؤها أثناء استخدام Codelab هذا.

يمكنك حذف مشروعك على Cloud، ما يؤدي إلى إيقاف الفوترة لجميع الموارد المستخدَمة فيه باتّباع الخطوات التالية:

gcloud projects delete $PROJECT_ID

يمكنك أيضًا حذف دليل مشروع Codelab من قرص Cloud Shell:

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

9- تهانينا!

🎊 اكتملت المهمة! لقد أنشأت بنجاح بنية أساسية لاختبار ونشر "وكيل ذكاء اصطناعي" في Go باستخدام "حزمة تطوير الوكلاء".

الإنجازات:

  • إنشاء خط أساسي أولي منظَّم باستخدام "حزمة أدوات الوكيل"
  • تم التحقّق من واجهة مستخدم الوكيل ورمزه واختبارهما محليًا
  • التعمّق في المخططات المكتوبة ووظائف ربط سلوكيات النماذج اللغوية الكبيرة بكائنات Go
  • نشر خدمة Go على Cloud Run

ما هي الخطوات التالية؟