useAgent کے ساتھ AI معاونین بنائیں اور خود ہوسٹ کریں

الفا انتباہ: useAgent ابھی فعال ترقی کے مرحلے میں ہے۔ ریلیزز کے درمیان APIs اور schemas تبدیل ہو سکتے ہیں، اس لیے جہاں استحکام اہم ہو وہاں ریلیز ٹیگ کو پن کریں۔

useAgent کیا ہے؟

useAgent ایک اوپن سورس AI ساتھی پلیٹ فارم ہے جو Claude Code، Codex اور OpenCode جیسے ایجنٹس چلانے کے لیے استعمال ہوتا ہے۔ صرف گفتگو پر مبنی جوابات واپس کرنے کے بجائے، ایجنٹس الگ تھلگ Linux ماحول میں کام کرتے ہیں اور مکمل ویب سائٹس، پریزنٹیشنز، اسپریڈشیٹس، تحقیقی رپورٹس اور آزمودہ pull requests فراہم کر سکتے ہیں۔

ہر تھریڈ کو terminal، repositories، browser اور noVNC کے ذریعے نظر آنے والے desktop پر مشتمل ایک workstation ملتا ہے۔ رنز کو Postgres میں event-sourced timelines کے طور پر پیش کیا جاتا ہے، جس سے تکمیل کے بعد وہ پائیدار، دوبارہ چلانے کے قابل اور قابلِ معائنہ رہتے ہیں۔

اہم خصوصیات

• متعدد ایجنٹس کے لیے ایک انٹرفیس: فراہم کنندہ کے لحاظ سے مخصوص engines ایک canonical event contract کے ذریعے رابطہ کرتے ہیں۔
• پائیدار execution: رنز backend کے دوبارہ شروع ہونے کے باوجود برقرار رہتے ہیں، جبکہ recovery فعال sessions کو دوبارہ جانچ کر مکمل شدہ کام اپنا سکتی ہے۔
• الگ تھلگ Linux sandboxes: ہر تھریڈ کو الگ workstation ملتا ہے۔ Daytona اور CubeSandbox مشترکہ sandbox contract نافذ کرتے ہیں۔
• قابلِ اعتماد tool gateway: credentials control plane میں رہتے ہیں اور agent sandbox میں داخل نہیں ہوتے۔
• انسانی منظوری: تباہ کن tool calls ویب انٹرفیس یا Slack میں منظوری تک رک جاتی ہیں، پھر argument-bound، one-use capability کے ساتھ دوبارہ جاری ہوتی ہیں۔
• GitHub پر مبنی skills: ٹیمیں versioned SKILL.md فائلیں درآمد، تبدیلیاں ہم آہنگ، اور متعلقہ skills کو agent turns میں درجہ بند کر سکتی ہیں۔
• تنظیمی context: knowledge retrieval میں citations شامل ہوتے ہیں، جبکہ team memory انسانی جائزے والے learning lane کو استعمال کرتی ہے۔
• مقامی artifacts: پلیٹ فارم revisioned DOCX، XLSX، PPTX اور PDF فائلوں کو native renderers کے ساتھ سپورٹ کرتا ہے۔
• متعدد entry channels: کام web application، Slack، REST API یا schedules کے ذریعے آ سکتا ہے۔

architecture کیسے کام کرتی ہے

useAgent اپنے self-hosted control plane کو اس ماحول سے الگ رکھتا ہے جہاں agent کام کرتا ہے۔ Entry channels ایک ہی run path کے ذریعے رنز بناتے ہیں۔ Engine adapters فراہم کنندہ کے لحاظ سے مخصوص سرگرمی کو canonical events میں تبدیل کرتے ہیں، جبکہ ہر تھریڈ کو الگ تھلگ sandbox دیا جاتا ہے۔

تین architectural خصوصیات خاص طور پر اہم ہیں:

1. Engines قابلِ تبدیلی ہیں: engine تبدیل کرنے کے لیے threads، artifacts یا memory کی مشترکہ نمائندگی تبدیل کرنا ضروری نہیں ہوتا۔
2. Postgres source of truth ہے: ہر رن event log کے طور پر محفوظ ہوتا ہے، جس سے restart کے بعد عین replay اور معائنہ ممکن ہوتا ہے۔
3. Secrets sandboxes سے باہر رہتے ہیں: integrations کو trusted gateway کے ذریعے typed tools کے طور پر پیش کیا جاتا ہے، جبکہ credentials صرف control plane میں محفوظ رہتے ہیں۔

Repository layout

• frontend/ میں sessions، skills، playbooks، wiki، artifacts، automations اور settings کے لیے product interface شامل ہے۔
• backend/ میں authentication، run orchestration، engine adapters، sandboxes، knowledge، memory، artifacts اور connectors شامل ہیں۔
• packages/ میں shared event contracts، workpieces، artifact formats، renderers اور متعلقہ packages شامل ہیں۔
• docs-site/ میں documentation website شامل ہے۔
• infra/self-host/ میں provider-independent deployment tooling اور Hetzner Terraform reference شامل ہے۔
• memory/ میں اختیاری team-memory service شامل ہے۔

ضروریات

مقامی development installation کے لیے Bun اور Postgres 16 یا اس کے بعد کا ورژن درکار ہے، جس میں pgvector extension شامل ہو۔ معیاری Postgres container images میں pgvector شامل نہیں ہوتا، اس لیے مناسب pgvector-enabled image استعمال کریں۔

اگر آپ فراہم کردہ database container command شروع کرنے کا ارادہ رکھتے ہیں تو Docker بھی دستیاب ہونا چاہیے۔ درج ذیل اقدامات useAgent repository کی root سے چلائیں۔

مرحلہ 1: pgvector کے ساتھ Postgres شروع کریں

اگر آپ کے پاس پہلے سے compatible database موجود نہیں ہے تو Docker میں ایک شروع کریں:

docker run -d --name useagent-pg -p 5432:5432 \
  -e POSTGRES_HOST_AUTH_METHOD=trust pgvector/pgvector:pg16
export DATABASE_URL=postgres://postgres@localhost:5432/postgres

پہلی command Postgres کو port 5432 پر دستیاب کرتی ہے۔ دوسری application کے زیرِ استعمال connection string مقرر کرتی ہے۔ trust configuration مقامی development کے لیے آسان ہے؛ production environments میں مناسب طور پر محفوظ database credentials استعمال کیے جانے چاہییں۔

مرحلہ 2: workspace dependencies انسٹال کریں

Dependencies کو shared packages، backend اور frontend workspaces میں الگ الگ انسٹال کیا جاتا ہے:

for workspace in \
  packages/agent-harness packages/artifact-workspace \
  packages/agent-client packages/artifact-formats packages/conformance \
  backend frontend; do
  (cd "$workspace" && bun install)
done

مرحلہ 3: backend اور frontend شروع کریں

الگ الگ terminal sessions کھولیں اور دونوں development processes شروع کریں:

bun run dev:backend

bun run dev:frontend

Backend API اور orchestration service کو port 3201 پر فراہم کرتا ہے۔ Frontend port 3400 پر چلتا ہے اور /api/* کے تحت requests کو backend کی طرف proxy کرتا ہے۔

انٹرفیس تک رسائی کے لیے براؤزر میں http://localhost:3400 کھولیں۔ پرووائیڈر اور سینڈ باکس کی تشکیل مختلف ہو سکتی ہے، اس لیے ایجنٹ انجن سے منسلک ہوتے وقت یا اس کے ایگزیکیوشن ماحول کی فراہمی کرتے وقت موجودہ useAgent دستاویزات کی پیروی کریں۔

مرحلہ 4: کوڈ بیس کی توثیق کریں

انسٹالیشن کے بعد یا تبدیلی جمع کرانے سے پہلے پورے ریپوزٹری کا ٹائپ چیکر چلائیں:

bun run typecheck

یہ کمانڈ ریپوزٹری کے ہر پیکیج کا احاطہ کرتی ہے اور مشترکہ معاہدوں، بیک اینڈ اور فرنٹ اینڈ میں غیر مطابقت رکھنے والی تبدیلیوں کی نشان دہی میں مدد دیتی ہے۔

بنیادی استعمال

ایجنٹ رن بنائیں

1. پورٹ 3400 پر ویب انٹرفیس کھولیں۔
2. ایجنٹ کمپوزر میں مطلوبہ مکمل نتیجے کی وضاحت کریں۔
3. رن شروع کریں اور اس کی براہِ راست ایونٹ ٹائم لائن دیکھیں۔
4. ایجنٹ کے کام کے دوران ٹرمینل، براؤزر، ڈیسک ٹاپ یا ورک اسپیس کی سرگرمی کا معائنہ کریں۔
5. تباہ کن ٹول آپریشن کی اجازت دینے سے پہلے کسی بھی منظوری کارڈ کا جائزہ لیں۔
6. سیشن سے واپس ملنے والا مکمل شدہ آرٹیفیکٹ یا ریپوزٹری کا کام حاصل کریں۔

کسی کام کو کسی ٹھوس قابلِ تسلیم نتیجے کے گرد ترتیب دیا جا سکتا ہے، مثلاً:

موضوع پر تحقیق کریں، متعلقہ ذرائع کے حوالے دیں، اور نتیجہ ایک منظم رپورٹ کی صورت میں واپس کریں۔

سافٹ ویئر کے کام کے لیے مطلوبہ نفاذ اور توثیق واضح کریں:

ریپوزٹری میں مطلوبہ تبدیلی نافذ کریں، متعلقہ ٹیسٹ چلائیں، اور مکمل شدہ کام کو جائزے کے لیے تیار کریں۔

یہ قدرتی زبان میں کام کی مثالیں ہیں، کسی خاص کمانڈ کے قواعد نہیں۔ کسی رن کے لیے دستیاب ٹولز کا انحصار تشکیل دیے گئے انجن، سینڈ باکس، علمی ذرائع، اسکلز اور انٹیگریشنز پر ہوتا ہے۔

Slack کے ذریعے کام کریں

جب مقامی Slack انٹیگریشن تشکیل شدہ ہو، تو صارفین کام شروع کرنے کے لیے ایجنٹ کو مینشن کر سکتے ہیں۔ جوابات، منسلکات، آرٹیفیکٹس اور منظوری کی درخواستیں Slack تھریڈ میں برقرار رہتی ہیں۔ اس طرح اصل چینل میں تعاون برقرار رکھتے ہوئے ویب انٹرفیس جیسا ہی رن پاتھ دستیاب ہوتا ہے۔

تنظیمی علم اور اسکلز استعمال کریں

علم، وکی کا مواد اور ٹیم کی یادداشت حوالہ جات کے ساتھ تنظیمی دائرۂ کار کا سیاق فراہم کر سکتے ہیں۔ دوبارہ استعمال کے قابل ہدایات GitHub سے ورژن شدہ SKILL.md اسکلز کے طور پر بھی درآمد کی جا سکتی ہیں۔ useAgent ان اسکلز کو خودکار طور پر دوبارہ ہم وقت ساز کر سکتا ہے اور ہر ٹرن میں متعلقہ اسکلز کی درجہ بندی کر سکتا ہے۔

useAgent کی خود میزبانی

useAgent کسی بھی Linux ہوسٹ پر چل سکتا ہے، بشمول AWS، Google Cloud، Azure، Hetzner یا بیئر میٹل۔ ریپوزٹری میں پرووائیڈر سے آزاد ڈپلائمنٹ اسکرپٹس کے ساتھ Terraform کے ذریعے بنایا گیا ایک کمانڈ میں تیار ہونے والا Hetzner حوالہ ہوسٹ بھی شامل ہے۔

Linux ہوسٹ تیار کرنے اور مطلوبہ اقدار فراہم کرنے کے بعد ریپوزٹری سے ڈپلائمنٹ اسکرپٹ چلائیں:

SERVER_IP=<host-ip> PG_PASSWORD=... OPENROUTER_API_KEY=... \
  infra/self-host/deploy-app.sh /path/to/this/repo

فراہمی کا عمل SSH کے ذریعے ہدف مشین سے رابطہ کرتا ہے۔ مکمل پروڈکشن رہنما اور مطلوبہ ماحول کی تفصیلات کے لیے infra/self-host/README.md دیکھیں؛ مختصر مثال کو مکمل سیکیورٹی تشکیل نہ سمجھیں۔

سینڈ باکس رن ٹائم منتخب کریں

• Daytona: ایک منظم سینڈ باکس سروس جو کسی بھی کلاؤڈ پر موجود کنٹرول پلین ہوسٹ کے ساتھ منسلک ہو سکتی ہے۔ README اسے آغاز کے لیے آسان ترین آپشن قرار دیتا ہے۔
• CubeSandbox: ان تنظیموں کے لیے خود میزبان رن ٹائم جو اپنے ہارڈویئر پر سینڈ باکسز چلانا چاہتی ہیں اور مکمل ڈیٹا لوکلٹی کی ضرورت رکھتی ہیں۔

دونوں رن ٹائمز ایک ہی سینڈ باکس معاہدے کے پیچھے کام کرتے ہیں، جس سے کنٹرول پلین ایجنٹ کے کام کو ترتیب دے سکتا ہے اور اس کا بنیادی رن ماڈل کسی ایک سینڈ باکس پرووائیڈر سے مخصوص نہیں ہوتا۔

اعلیٰ سطحی عملی تجاویز

• ریلیز ٹیگ مقرر کریں: چونکہ یہ منصوبہ الفا مرحلے میں ہے، اس لیے معلوم ٹیگ مقرر کرنے سے بدلتی ہوئی APIs یا اسکیماؤں کے باعث غیر متوقع خرابی کم ہوتی ہے۔
• Postgres محفوظ رکھیں: ایونٹ لاگ رنز کے لیے اصل ماخذِ صداقت ہے۔ ڈیٹا بیس کا اسی مناسبت سے بیک اپ لیں اور اسے چلائیں۔
• اسناد گیٹ وے میں رکھیں: طویل مدتی انٹیگریشن سیکرٹس کو سینڈ باکسز میں نقل کر کے طرزِ تعمیر کو نظرانداز نہ کریں۔
• منظوریوں کا سوچ سمجھ کر استعمال کریں: تباہ کن اقدامات کے لیے انسانی نگرانی کے کنٹرولز فعال رکھیں، خاص طور پر جب رنز Slack یا شیڈولز کے ذریعے شروع ہوں۔
• آپریشنز کے مطابق سینڈ باکس منتخب کریں: Daytona منظم راستہ فراہم کرتا ہے، جبکہ CubeSandbox خود میزبانی کے ساتھ ایگزیکیوشن اور ڈیٹا لوکلٹی کو سپورٹ کرتا ہے۔
• ٹائپ چیکس مستقل طور پر چلائیں: مشترکہ معاہدے کئی ورک اسپیسز میں پھیلے ہوئے ہیں، اس لیے پیکیجز کے درمیان تبدیلیوں کے بعد bun run typecheck استعمال کریں۔
• پروڈکشن لینز کا جائزہ لیں: مکمل ڈپلائمنٹ رہنمائی infra/self-host/ کے تحت موجود ہے، جبکہ اضافی ناقابلِ تغیر کنٹینر ریلیز لین کی دستاویز docs/operations/immutable-releases.md میں ہے۔
• درخواست کے بہاؤ کا معائنہ کریں: ریپوزٹری میں گہرے طرزِ تعمیر کے مطالعے کے لیے docs/architecture/request-flow.html پر ایک interactive diagram شامل ہے۔

انٹیگریشنز اور ترسیلی سطحیں

مقامی Slack اور GitHub سپورٹ کے علاوہ، پلیٹ فارم کنیکٹرز کے ذریعے Gmail، Linear، Notion اور HubSpot بھی فہرست میں شامل کرتا ہے۔ OAuth کو ایک بروکر سنبھالتا ہے اور ٹوکنز سرور کی جانب سے محفوظ کیے جاتے ہیں۔ ورک اسپیس کی سطحوں میں نالج بیس، ٹیم میموری، اسکلز، پلے بکس اور شیڈول شدہ آٹومیشنز شامل ہیں۔

GitHub انٹیگریشن App تصدیق، ریپوزٹری کلوننگ اور پل ریکوئسٹ ورک فلو کو سپورٹ کرتی ہے۔ انٹیگریشن سے قطع نظر، ٹول کالز قابلِ اعتماد گیٹ وے سے گزرتی ہیں، اس لیے اسناد براہِ راست ایجنٹ ورک اسٹیشن کے سامنے ظاہر نہیں ہوتیں۔

لائسنسنگ سے متعلق امور

useAgent GNU AGPL v3.0-only لائسنس کے تحت تقسیم کیا جاتا ہے۔ ان شرائط کے تحت اسے استعمال، ترمیم اور اپنے سرور پر ہوسٹ کیا جا سکتا ہے۔ ملکیتی ایمبیڈنگ، OEM یا وائٹ لیبل مصنوعات، AGPL کی ذمہ داریوں کے بغیر تقسیم، یا لائسنسنگ کی دیگر ضروریات کے لیے تجارتی لائسنس دستیاب ہے۔

نتیجہ

useAgent متعدد ایجنٹ انجنز، Postgres سے تقویت یافتہ پائیدار رنز، الگ تھلگ Linux سینڈ باکسز، تنظیمی سیاق و سباق، محفوظ انضمامات، منظوریوں اور قابلِ تدوین آرٹی فیکٹس کو ایک خود ہوسٹ کیے جانے والے پلیٹ فارم میں یکجا کرتا ہے۔ Bun اور pgvector کے ساتھ مقامی طور پر آغاز کریں، اس کے ٹائپ چیکر سے مونوریپو کی توثیق کریں، پھر Linux کے پروڈکشن ہوسٹ پر منتقل ہوتے وقت دستاویزی سیلف ہوسٹنگ طریقہ استعمال کریں۔