تصور کنید یک برنامهنویس بتواند تنها با یک دستور، یک عامل هوش مصنوعی کاملاً تایپشده (Type-safe) را بدون ترس از خطاهای زمان اجرا در ابر مستقر کند. این دقیقاً همان اتفاقی است که گوگل با عرضه نسخه تایپاسکریپتی Agent Development Kit (ADK) رقم زده است. طبق مستندات فنی، این تغییر مسیر از پرامپتهای آزاد به یک محیط ساختاریافته و کد-محور است. اکنون یک توسعهدهنده میتواند با استفاده از ADK برای تایپاسکریپت، یک عامل کاملاً تایپشده را با یک دستور واحد در فضای ابری مستقر کند. در آموزشهای ارائه شده، این نسخه امکان ایجاد یک عامل اولیه به سبک «Hello World» را با استفاده از تایپاسکریپت و نسخه بومی ADK فراهم میکند. پروژه نمونه کامل که یک عامل حداقلی برای نمایش وضعیت آبوهوا و زمان است، در گیتهاب با نام "ADK Hello World for TypeScript" در دسترس است.
به نقل از مستندات فنی گوگل، این ابزار اجازه میدهد تا عاملها به جای تکیه بر پرامپتهای شل و غیرقابل پیشبینی، در یک محیط کد-محور و ساختاریافته توسعه یابند. همانطور که در تحلیلهای پیشین ما درباره امنیت مدلهای بازمتن اشاره کردیم، انتقال لایه کنترل از زبان طبیعی به کد، اولین گام برای رسیدن به قابلیت اطمینان در سامانههای عاملمحور است. برای سالها، ساخت عاملهای هوش مصنوعی به معنای 씨وکست با خروجیهای نامطمئن JSON و منطقهای شکننده در فراخوانی ابزارها بود. در این مدت، اکثر چارچوبها بر پایه پایتون بودند و اکوسیستم عظیم Node.js و مرورگرها در اولویت دوم قرار داشتند. گوگل با عرضه ADK برای تایپاسکریپت، حالا پیکربندی عامل را به جای یک تمرین «پرامپتنویسی»، به یک مسئله مهندسی نرمافزار تبدیل کرده است. این نسخه بهطور خاص برای اکوسیستمهای Node.js و مرورگر طراحی شده و از ESM، CommonJS و محیطهای وب پشتیبانی میکند.
هسته فنی و معماری
طبق اعلام گوگل، هسته فنی این ابزار تحت بسته @google/adk در npm منتشر شده و ابزارهای توسعه آن در @google/adk-devtools قرار دارند. این آموزش بهطور مشخص از نسخه ۱.۴.۰ ADK استفاده میکند. این نسخه برای Node.js ۲۰ یا نسخههای جدیدتر هدفگذاری شده است و بهگونهای طراحی شده که مدل-ناپذیر (Model-agnostic) و استقرار-ناپذیر (Deployment-agnostic) باشد، هرچند که برای اکوسیستم Gemini بهینه شده است.
ADK یک چارچوب منعطف و ماژولار برای ساخت، استقرار و سازماندهی جریانهای کاری عاملهای هوش مصنوعی است؛ از وظایف ساده گرفته تا سیستمهای پیچیده چندعامله. این ابزار به توسعهدهندگان اجازه میدهد رفتار عامل، نحوه سازماندهی و استفاده از ابزارها را مستقیماً در کد تعریف کنند و از این طریق، دیباگینگ، نسخهبندی و استقرار در هر محیطی را تسهیل کنند. گوگل سورس کد کامل این پروژه را از طریق مخزن google / adk-js در گیتهاب منتشر کرده است.
ویژگیهای کلیدی معماری این سیستم عبارتند از:
- ادغام با Zod: این چارچوب از شمای Zod نسخه ۳ و ۴ برای پارامترهای ابزار استفاده میکند. این یعنی پارامترها و نتایج ابزارها قبل از اینکه مدل آنها را ببیند، از طریق استنتاج نوع در زمان کامپایل (compile-time type inference) بررسی میشوند.
- کلاس LlmAgent: عاملها از طریق این کلاس تعریف میشوند. توسعهدهندگان در اینجا مدل مورد نظر (مثلاً Gemini 2.5 Flash)، دستورات سیستمی و لیستی از ابزارهای در دسترس را مشخص میکنند.
- اتحادیهای متمایز (Discriminated Unions): ابزارها خروجیی با ساختار ثابت دارند؛ یا یک نتیجه موفق با فرمت
{status: 'success'; report: string}و یا یک پیام خطا با فرمت{status: 'error'; errorMessage: string}. این ساختار کمک میکند تا مدل بتواند درباره شکستها با قابلیت اطمینان بیشتری استدلال کند.
تایپاسکریپت چیست و چرا اهمیت دارد؟
در این میان باید به نقش TypeScript اشاره کرد. تایپاسکریپت یک زبان برنامهنویسی با تایپینگ قوی است که بر روی جاوااسکریپت بنا شده و توسط مایکروسافت پشتیبانی میشود. چون این زبان به جاوااسکریپت خالص کامپایل میشود، در هر جایی که جاوااسکریپت اجرا شود (از جمله محیط Node.js که هدف ADK است) قابل اجراست. سیستم تایپ استاتیک در اینجا بهطور طبیعی با توسعه عاملها جفت میشود، زیرا پارامترهای ابزار و پیکربندیها در طول فرآیند بیلد (build) اعتبارسنجی میشوند. این امر باعث میشود خطاها توسط کامپایلر شناسایی شوند، نه در زمان اجرا (runtime) در حین یک فراخوانی مدل زبانی بزرگ (LLM).
تنظیمات محیطی و نصب
برای راهاندازی، توسعهدهندگان باید Node.js ۲۰ یا جدیدتر داشته باشند. گوگل توصیه میکند در صورت عدم نصب، از Node Version Manager (nvm) استفاده شود. کاربران میتوانند دستور nvm install --lts و سپس nvm use --lts را اجرا کنند. نصب صحیح با دستور node --version تایید میشود که باید نسخهای مانند v22.x یا مشابه آن را برگرداند.
شروع پروژه با کلون کردن مخزن adk-hello-world-typescript و اجرای اسکریپت init.sh آغاز میشود. این اسکریپت فرآیند نصب وابستگیهای npm را خودکار کرده و یک فایل .env اولیه را از روی .env.example میسازد.
مکانیزمهای احراز هویت
توسعهدهندگان دو گزینه اصلی برای احراز هویت عاملهای خود دارند که در فایل .env پیکربندی میشوند (این فایل در .gitignore قرار دارد تا از ارسال تصادفی به مخزن جلوگیری شود):
- Gemini Developer API: کاربران باید
GOOGLE_API_KEYرا تنظیم کنند. این کلیدها از طریق Google AI Studio در آدرسhttps://aistudio.google.com/apikeyقابل دریافت هستند. - Vertex AI: کاربران باید
GOOGLE_GENAI_USE_VERTEXAI=TRUEرا به همراهGOOGLE_CLOUD_PROJECTوGOOGLE_CLOUD_LOCATIONتنظیم کنند. این روش نیازمند احراز هویت از طریق Google Cloud CLI با دستوراتgcloud auth loginوgcloud auth application-default loginاست.
اگر اعتبارنامه پیشفرض برنامه (ADC) منقضی شود، توسعهدهندگان میتوانند مجدداً با دستورات gcloud auth احراز هویت کنند. همچنین یک اسکریپت set_env.sh برای دستوراتی که نیاز به بارگذاری این متغیرهای محیطی در شل دارند، فراهم شده است.
توسعه محلی و تست
بر اساس بررسی منابع متعدد، تفاوت اصلی این نسخه با نسخههای Go یا پایتون، معرفی یک مجموعه تست واحد (Unit Test) بومی است. توسعهدهندگان میتوانند با استفاده از محیط تست بومی Node.js (node:test) منطق ابزارها را بهصورت قطعی و بدون نیاز به فراخوانیهای گرانقیمت یا کند API به مدل زبانی بررسی کنند. اجرای دستور npm run check ابتدا دستور tsc --noEmit را برای بررسی تایپها اجرا کرده و سپس مجموعه تستها را اجرا میکند.
خروجیهای نمونه تست تایید میکنند که عامل:
- ریشه عامل ADK را صادر میکند (۰.۴۳ میلیثانیه).
- آبوهوای پیکربندی شده نیویورک را برمیگرداند (۰.۱۶ میلیثانیه).
- شهرهای پشتیبانی نشده را رد میکند (۰.۴۵ میلیثانیه).
- زمان نیویورک را بهصورت قطعی فرمت میکند (۱۲.۲۷ میلیثانیه).
برای عیبیابی (Debugging) نیز سه رابط اصلی فراهم شده است:
۱. CLI: دستورات npm start (که adk run src/agent.ts را اجرا میکند) یا npx adk run src/agent.ts برای تعامل سریع در ترمینال.
۲. Web UI: دستور npm run web (که adk web را اجرا میکند) یا npx adk web یک رابط گرافیکی محلی را اجرا میکند که ردیابی کامل فراخوانی ابزارها (tool-calling tracing) را ارائه میدهد. برای ماشینهای مجازی یا کانتینرهای راه دور، توسعهدهندگان میتوانند سرور را با npx adk web --host=0.0.0.0 متصل کنند.
۳. HTTP API: عامل میتواند بدون رابط کاربری و به عنوان یک API ساده از طریق npx adk api_server در دسترس قرار گیرد.
جزئیات پیادهسازی: src/agent.ts
تمام منطق عامل در فایل src/agent.ts قرار دارد. این کد از یک LlmAgent استفاده میکند که روی مدل Gemini 2.5 Flash با پیکربندیهای زیر اجرا میشود:
- نام:
weather_time_agent - دستورالعمل (Instruction): "شما یک دستیار مفید هستید. از ابزارهای موجود برای پاسخ به سوالات درباره زمان و آبوهوا استفاده کنید. اگر شهری پشتیبانی نمیشود، آن را بهوضوح توضیح دهید."
- ابزارها: دو ابزار محلی به نامهای
get_weatherوcurrentTimeTool.
در مورد مکانیزم ابزارها:
- تعریف شما (Schema): ابزار
get_weatherاز یک شیء Zod برایcityParametersاستفاده میکند. این تعریف مستلزمz.string().min(1)است و شامل این توصیف است: "شهری که باید جستجو شود." - نگاشت تابع (Function Mapping): کلاس
FunctionToolشما را به منطق متصل میکند. برای مثال، ویژگیexecuteدرget_weatherتابعgetWeather(city)را فراخوانی میکند. - پشتیبانی از شهرها: در این نمونه، آبوهوا و زمان محلی فقط برای نیویورک در دسترس است. هر شهر دیگری منجر به بازگشت نتیجه «شهر پشتیبانی نشده» میشود.
در یک تعامل نمونه، وقتی از عامل پرسیده میشود "چه کارهایی میتوانی انجام دهی؟"، او قابلیتهای خود را شناسایی کرده و اعلام میکند که نیویورک را پشتیبانی میکند. هنگام پرسش "آبوهوای نیویورک چگونه است؟"، گزارش دقیقی ارائه میدهد: "آبوهوای نیویورک آفتابی با دمای ۲۵ درجه سانتیگراد (۷۷ درجه فارنهایت) است."
خط لوله استقرار (Deployment Pipeline)
CLI ابزار ADK شامل قابلیتهای استقرار داخلی برای Google Cloud Run است. اسکریپت cloudrun.sh این فرآیند را با فراخوانی دستور deploy مدیریت میکند:npx adk deploy cloud_run --project "$GOOGLE_CLOUD_PROJECT" --region "$GOOGLE_CLOUD_LOCATION" --service_name "$SERVICE_NAME" --with_ui true src/agent.ts
یک پرچم خاص یعنی --with_ui true اجازه میدهد تا رابط کاربری توسعه مستقیماً در سرویس مستقر شده بستهبندی شود تا مانیتورینگ راه دور آسانتر گردد. پس از استقرار، کاربران میتوانند URL سرویس را با دستور زیر دریافت کنند:gcloud run services describe hello-world-agent-service --region us-central1 --format 'value(status.url)'
این چرخش به سمت رویکرد «کد-محور»، به این معناست که رفتار عاملها اکنون مانند هر میکروسرویس دیگری نسخهبندی و دیباگ میشود. گوگل با انتقال لایه اعتبارسنجی به کامپایلر از طریق تایپاسکریپت و Zod، در واقع «سطح توهم» (Hallucination Surface) را در لحظه فراخوانی ابزارها کاهش داده است؛ یعنی نقاطی که عاملها معمولاً در هنگام اجرای ابزار دچار خطا میشوند.
برای یک توسعهدهنده معمولی، این یعنی مانع ورود برای ساخت عاملهای در سطح تولید (production-grade) کاهش یافته است. شما دیگر به یک بکاند پیچیده پایتون برای اجرای یک عامل پیشرفته نیاز ندارید؛ یک محیط استاندارد Node.js کافی است. این رویکرد ساختاریافته برای دسترسی به دادهها یادآور ابزارهایی است که گوگل برای مدیریت دادههای تخصصی ارائه داده است؛ برای مثال، ابزار ghealth برای تبدیل دادههای سلامتی نیز از رویکردی مشابه در CLI برای تسهیل تعامل با APIهای گوگل بهره میبرد. اگر برای مرورگر توسعه میدهید، ADK بستههای ESM و CommonJS را ارائه میدهد، به این معنی که عاملها میتوانند مستقیماً در محیط زمان اجرای کلاینت (Client-side runtime) اجرا شوند و نیاز به سرور واسط را کاملاً حذف کنند.
گام بعدی شما
- اگر از Node.js استفاده میکنید، بسته
@google/adkرا نصب کرده و یک عامل ساده برای اتوماسیون کارهای تکراری خود بسازید. - برای کاهش هزینههای API، ابتدا منطق ابزارهای خود را با
node:testدر محیط محلی اعتبارسنجی کنید. - از قابلیت
--with_uiدر Cloud Run برای مانیتورینگ زنده زنجیره تفکر عامل خود در محیط عملیاتی استفاده کنید.
اما داستان سختافزاری این تحول حتی شگفتانگیزتر است — به تحلیل ما درباره تراشههای Blackwell مراجعه کنید.
گفتگو