بسته‌ی آغازین Agent به همراه ADK برای Go

۱. مقدمه

اگرچه پایتون همچنان برای آموزش مدل و تحقیق محبوب است، اما الزامات مربوط به سرویس‌دهی و هماهنگ‌سازی عامل‌های هوش مصنوعی با نقاط قوت Go همخوانی نزدیکی دارد: تأخیر کم، همزمانی بالا و ایمنی نوع.

گذار از یک نمونه اولیه به یک عامل تولید، چالش‌های مهندسی را ایجاد می‌کند که Go می‌تواند به طور فوق‌العاده‌ای آنها را مدیریت کند. تایپ استاتیک Go خطاهای زمان اجرا را هنگام تجزیه خروجی‌های ساختاریافته LLM از بین می‌برد. گوروتین‌های سبک آن، که در مقایسه با چندین مگابایت برای نخ‌های سیستم عامل، تنها با چند کیلوبایت حافظه پشته شروع می‌شوند، به عامل‌ها اجازه می‌دهند هزاران اجرای همزمان ابزار را بدون سربار مدیریت نخ سنگین مدیریت کنند.

کیت توسعه عامل (ADK) گوگل، شکاف بین این مزایای معماری و هوش مصنوعی مولد را پر می‌کند. در این راهنما، شما یک پروژه جدید را چارچوب‌بندی کرده و آن را به عنوان یک میکروسرویس امن در Google Cloud مستقر خواهید کرد.

کاری که انجام خواهید داد:

• با استفاده از Agent Starter Pack، یک پروژه عامل آماده برای تولید را Scaffold کنید
• از رابط کاربری وب محلی Agent Development Kit برای اشکال‌زدایی و آزمایش Agent خود استفاده کنید.
• توسعه و درک منطق عامل ADK مبتنی بر Go
• اجرای تست‌های واحد و سرتاسری (E2E)
• عامل را به طور ایمن در Cloud Run مستقر کنید

آنچه نیاز دارید:

• یک مرورگر وب مانند کروم
• یک پروژه گوگل کلود با قابلیت پرداخت صورتحساب

۲. قبل از شروع

ایجاد یک پروژه ابری گوگل

اگر از قبل یکی ندارید:

1. در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید .
2. مطمئن شوید که پرداخت برای پروژه ابری شما فعال است.

شروع پوسته ابری

Cloud Shell یک محیط خط فرمان است که در Google Cloud اجرا می‌شود و ابزارهای لازم از قبل روی آن بارگذاری شده است. این محیط به عنوان محیط توسعه اصلی شما برای این آزمایشگاه عمل خواهد کرد.

1. روی فعال کردن Cloud Shell در بالای کنسول Google Cloud کلیک کنید.
2. پس از اتصال به Cloud Shell، این دستور را برای تأیید احراز هویت خود در Cloud Shell اجرا کنید:

gcloud auth list

3. برای تأیید اینکه پروژه شما برای استفاده با gcloud پیکربندی شده است، دستور زیر را اجرا کنید:

gcloud config get project

4. تأیید کنید که پروژه مطابق انتظار است و سپس دستور زیر را برای تنظیم شناسه پروژه خود اجرا کنید:

export PROJECT_ID=$(gcloud config get project)

۳. با بسته‌ی آغازین Agent شروع کنید

خبر خوب این است که لازم نیست از ابتدا شروع کنید. Agent Starter Pack یک ابزار CLI است که یک ساختار پوشه آماده برای تولید، شامل خطوط لوله CI/CD، پیکربندی زیرساخت و کد قالبی (boilerplate code) را فراهم می‌کند.

برای شروع، کافیست دستور build creation را با uvx اجرا کنید:

uvx agent-starter-pack create

رابط خط فرمان (CLI) شما را در یک فرآیند راه‌اندازی تعاملی راهنمایی می‌کند. برای این پروژه، گزینه‌های زیر را انتخاب کنید:

• نام پروژه: my-first-go-agent
• الگو: گزینه ۶ (برو ADK، عامل برو با A2A)
• CI/CD: گزینه ۳ (اقدامات گیت‌هاب)
• منطقه: us-central1

این ابزار به طور خودکار با Google Cloud احراز هویت می‌کند، APIهای لازم Vertex AI را فعال می‌کند و محیط محلی شما را پیکربندی می‌کند.

به محض اینکه پیام سبز رنگ « موفق باشید!» را مشاهده کردید، آماده ادامه کار هستید.

۴. تجسم عامل به صورت محلی

یکی از راحت‌ترین ویژگی‌های ADK، امکان اشکال‌زدایی بصری عامل شما قبل از استقرار آن است. با اجرای دستورات زیر، یک سرور توسعه محلی با یک رابط کاربری داخلی راه‌اندازی می‌کنید. بله، این سرور یک پنجره چت دارد، اما با ردیابی رویدادها، فراخوانی ابزارها و موارد دیگر، فراتر از آن عمل می‌کند.

به دایرکتوری پروژه خود بروید و playground را شروع کنید:

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

پس از اجرای زمین بازی، پیش‌نمایش وب را در Cloud Shell باز کنید تا با عامل تازه ایجاد شده خود تعامل داشته باشید.

این عامل با الگوی ReAct (استدلال و عمل) پیکربندی شده است - چارچوبی که در هوش مصنوعی عامل‌محور به پایه و اساس تبدیل شده است. حلقه پیوسته «فکر»، «عمل» و «مشاهده» در الگوی ReAct، حل مسئله و تفسیرپذیری را افزایش می‌دهد و فرآیند تصمیم‌گیری عامل را شفاف می‌سازد.

برای مثال، اگر شما در مورد آب و هوا سوال کنید، عامل (agent) هدف (intent) را تشخیص می‌دهد، ابزار get_weather را فراخوانی می‌کند و داده‌های ساختاریافته را برمی‌گرداند.

۵. درک کد

حالا که عامل را در عمل دیدیم، بیایید به کد 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 و ساختار arguments را می‌پذیرد، منطق کسب و کار را انجام می‌دهد و ساختار نتیجه را برمی‌گرداند:

// 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 پشتیبانی می‌شود، شروع می‌کند.

در مرحله بعد، با قرار دادن تابع محلی GetWeather در یک functiontool ، شکاف بین کد Go و LLM را پر می‌کند. این مرحله ابزار را با نام 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
}

۶. آزمایش

این پروژه شامل تست‌های واحد برای منطق داخلی و تست‌های سرتاسری برای یکپارچه‌سازی سرور است.

در 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

۷. استقرار

وقتی آماده شدید که عامل خود را با جهان به اشتراک بگذارید یا آن را به اکوسیستم‌های عملیاتی متصل کنید، دستور deploy موجود در بسته را اجرا کنید:

make deploy

این دستور به طور خودکار برنامه شما را از منبع با استفاده از Google Cloud Buildpacks که توسط پرچم --source . فعال می‌شود، می‌سازد. این دستور این تصویر را با چندین پرچم بهینه شده برای محیط عملیاتی، در Cloud Run مستقر می‌کند: --memory "4Gi" برای فراهم کردن رم کافی برای عملیات LLM، و --no-cpu-throttling برای اطمینان از اینکه CPU به صورت 24 ساعته و 7 روز هفته اختصاص داده می‌شود، که می‌تواند از شروع سرد جلوگیری کرده و پاسخ‌های سریع در تعاملات عامل را تضمین کند.

برای اطمینان از اجرای ایمن عامل شما، سیستم با پیکربندی دقیقی با استفاده از --no-allow-unauthenticated مستقر می‌شود تا به طور پیش‌فرض تمام دسترسی‌های عمومی را مسدود کند و برای هرگونه درخواستی نیاز به احراز هویت مدیریت هویت و دسترسی (IAM) دارد. همچنین متغیرهای محیطی از جمله GOOGLE_GENAI_USE_VERTEXAI=True را تزریق می‌کند.

از آنجایی که برنامه شما امن است، برای دسترسی ایمن به آن از طریق مرورگر، باید پروکسی آگاه از هویت (IAP) را فعال کنید. مستندات Cloud دستورالعمل‌های گام به گام را در Enable IAP for Cloud Run ارائه می‌دهد.

پس از فعال شدن IAP و اضافه شدن ایمیل شما به عنوان مدیر، می‌توانید به آدرس اینترنتی سرویس (Service URL) ارائه شده پس از استقرار بروید. مشاهده آدرس اینترنتی سرویس پایه به شما امکان می‌دهد تا کارت عامل مستقر شده را مشاهده کنید. این ساختار JSON به عنوان رابط استاندارد عامل شما عمل می‌کند و به آن اجازه می‌دهد تا به صورت پویا توسط سایر عامل‌ها، هماهنگ‌کننده‌ها یا رابط‌های کاربری انسانی کشف و استفاده شود.

۸. تمیز کردن

برای جلوگیری از تحمیل هزینه‌های مداوم به حساب Google Cloud خود، منابع ایجاد شده در طول این Codelab را حذف کنید.

شما می‌توانید پروژه ابری خود را حذف کنید، که باعث می‌شود پرداخت هزینه تمام منابع مورد استفاده در آن متوقف شود:

gcloud projects delete $PROJECT_ID

همچنین می‌توانید دایرکتوری پروژه codelab را از دیسک Cloud Shell خود حذف کنید:

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

۹. تبریک می‌گویم!

🎊 ماموریت کامل شد! شما با موفقیت یک عامل هوش مصنوعی را در Go با استفاده از کیت توسعه عامل، داربست‌بندی، آزمایش و مستقر کرده‌اید.

کاری که شما انجام دادید:

• با استفاده از Agent Starter Pack یک خط پایه ساختار یافته اولیه را ایجاد کردیم.
• رابط کاربری و کد عامل به صورت محلی تأیید و آزمایش شد
• عمیقاً به طرحواره‌ها و توابع تایپ‌شده پرداخته و رفتارهای LLM را به اشیاء Go نگاشت می‌کند.
• سرویس Go را روی Cloud Run مستقر کردیم.

بعدش چی؟

• مستندات ADK : راهنماهای کامل در مورد الگوهای پیشرفته، ارکستراسیون چند عاملی و سیستم‌های حافظه
• بسته مقدماتی Agent : قالب‌ها، از جمله سیستم‌های چندعاملی و معماری‌های پیچیده را بررسی کنید
• مستندات Cloud Run : بررسی عمیق بهینه‌سازی عملکرد، استراتژی‌های مقیاس‌پذیری و بهترین شیوه‌های امنیتی
• الگوهای همزمانی Go : درک گوروتین‌ها و کانال‌ها به شما کمک می‌کند تا ابزارهای عامل کارآمدتری بسازید
• موتور عامل هوش مصنوعی ورتکس : برای زیرساخت عامل مدیریت‌شده با تنظیم و ابزار داخلی