معاينة تطبيقات الويب مباشرةً أثناء بناء وكيل البرمجة لها مع Amazon Bedrock AgentCore runtime

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

Amazon Bedrock AgentCore هي منصة لبناء الوكلاء وربطهم وتحسينهم على نطاق واسع، مع حرية اختيارك لإطار عمل الوكيل والنموذج الأساسي (FM). AgentCore runtime، وهي إحدى قدرات Amazon Bedrock AgentCore، تشغّل كل جلسة وكيل في microVM معزولة خاصة بها. مع نقاط نهاية الجلسات (Session endpoints)، يمكنك فتح تطبيق قيد التشغيل في تلك الجلسة من متصفحك الخاص. تمنح نقاط نهاية الجلسات كل جلسة عنوان URL مُصادقًا يعيد توجيه طريقة HTTP ومسار كل طلب وسلسلة الاستعلام والمتن، وكذلك اتصالات WebSocket، إلى المنافذ التي تسمح بها. يمكنك مشاهدة الصفحة تتحدث كلما حفظ الوكيل كل ملف.

في هذه التدوينة، تنشر وكيل برمجة يحافظ على تشغيل موقع Vite في جلسته، ثم تفتح صفحة محلية واحدة فيها وحدة محادثة على اليسار والموقع المباشر على اليمين. تطلب من الوكيل تحويل الموقع إلى سمة ألوان داكنة، وتتابع خطواته وهي تتدفق، وتشاهد الموقع يتغير دون تحديث الصفحة. وأخيرًا، تنظر إلى ما يحدث داخليًا: منفذ ثانٍ في الجلسة نفسها، والطلبات التي ترفضها نقطة نهاية الجلسة.

العينة الكاملة، بما في ذلك دفتر الملاحظات الذي تتبعه هذه التدوينة، موجودة في مجلد 14-remote-access من مستودع agentcore-samples على GitHub.

كيف تعمل نقاط نهاية الجلسات

لكل جلسة نقطة نهاية جلسة خاصة بها، وهناك ست تفاصيل تشكّل طريقة استخدامك لها.

أنت تختار المنافذ التي تصل إليها. أنت تحدد allowedPorts عند استدعاء CreateAgentRuntime: من 1 إلى 5 إدخالات، كل منها منفذ واحد أو نطاق ضمن 8000–12000، باستثناء منافذ المنصة المحجوزة. السماح بمنفذ لا يبدأ خادمًا، لذا يجب أن يستمع تطبيقك عليه، مرتبطًا بـ 0.0.0.0.

يصل عنوان URL مع الجلسة. يحمل استجابة InvokeAgentRuntime العنوان في X-Amzn-Bedrock-AgentCore-Runtime-Session-Endpoint-Url الترويسة، والتي تعرضها حزم SDK التي تصممها على أنها sessionEndpointUrl.

كل طلب مُصادق عليه. بالنسبة لوقت تشغيل يستخدم AWS Identity and Access Management (IAM)، كل طلب HTTP وكل تدفق HTTP/2 وكل مصافحة WebSocket يحمل Signature Version 4 (SigV4) توقيعًا. كما يحتاج المستدعي أيضًا bedrock-agentcore:InvokeAgentRuntimeProxy على بيئة التشغيل ونقطة نهايتها. أما بالنسبة لبيئة تشغيل تحتوي على مُفوِّض JSON Web Token (JWT) وارد، فإن كل طلب يحمل رمز حامل (bearer token) بدلًا من ذلك. معرفة عنوان URL لا تمنح حق الوصول.

يختار اسم المضيف المنفذ. يتصل عميلك عبر المنفذ 443 بغض النظر عن منفذ الهدف، وتختار بادئة في اسم المضيف المنفذ داخل الجلسة:

https://8090--<session-endpoint-id>.runtime.bedrock-agentcore.<region>.on.aws/index.html
https://8081--<session-endpoint-id>.runtime.bedrock-agentcore.<region>.on.aws/status

يحمل البروتوكولات التي يتحدث بها خادمك. تمر طلبات HTTP/1.1 وHTTP/2، بما في ذلك الأحداث المرسلة من الخادم وgRPC، واتصالات WebSocket جميعها من خلاله. يستخدم هذا الدليل التوضيحي HTTP/1.1 وWebSocket.

وهو مقيَّد بجلسة واحدة. يحتاج عنوان URL إلى بيانات اعتماد في كل طلب ولا يدوم إلا طالما استمرت الجلسة، لذا استخدمه للبناء والاختبار ومراجعة ما ينتجه وكيلك. لعرض تطبيق على مستخدميك، انشره على خدمة استضافة مثل AWS Amplify Hosting.

لا يمكن للمتصفح إضافة توقيع SigV4 أو رمز حامل (bearer token) إلى الطلبات التي تقدمها الصفحة من تلقاء نفسها، لذا يمكن لعميل نقطة النهاية Session في bedrock-agentcore SDK أن يفتح نقطة نهاية محلية على جهازك. يفتح متصفحك http://localhost:8088، وتضيف نقطة النهاية المحلية بيانات اعتمادك إلى كل طلب وكل مصافحة WebSocket قبل إعادة توجيهه.

نقطة نهاية Session تختلف عن نقطة نهاية runtime، التي يوفرها AgentCore runtime بالفعل. استخدم نقطة نهاية runtime، مثل DEFAULTللوصول إلى وكيلك، حيث تتحكم في أي إصدار سيصل إليه المتصلون. InvokeAgentRuntime تُحل النداءات من خلالها، لذا يمكنك إبقاء التطوير والإنتاج على إصدارات مختلفة والترقية أو التراجع دون تغيير المتصلين. استخدم نقطة نهاية Session لمعرفة ما يشغّله وكيلك في جلسته، مثل معاينة ويب. إنه رابط URL مُصادق عليه يصل فقط إلى المنافذ التي تسمح بها، ويعمل مع أي إصدار تعمل فيه الجلسة، ويتوقف عن العمل عند انتهاء الجلسة. للتوثيق الكامل، راجع Connect to runtime sessions through a session endpoint.

نظرة عامة على الحل

يتكون النموذج من أربعة أجزاء. يعمل وكيل برمجة (coding agent) في الجلسة على المنفذ 8080 ويحرر ملفات الموقع باستخدام أربع أدوات: list وread وwrite وedit. يبدأ الوكيل خادم تطوير Vite على المنفذ 8090، الذي يقدم الموقع ويدفع كل تغيير محفوظ إلى المتصفح عبر WebSocket الخاص بإعادة التحميل الفوري. على جهازك، PreviewApp يقدم صفحة المعاينة، ويرسل مطالباتك إلى InvokeAgentRuntime، ويفتح نقطة نهاية محلية للموقع. كما يوضح الشكل 1، تحمّل صفحة المعاينة الموقع من خادم تطوير Vite على المنفذ 8090 عبر نقطة النهاية المحلية ونقطة نهاية Session، وترسل مطالباتك عبر InvokeAgentRuntime إلى الوكيل على المنفذ 8080. تُظهر الأرقام ترتيب الخطوات لطلب واحد.

الشكل 1: بنية الحل

قبل الخطوة 1، PreviewApp قد استدعى بالفعل InvokeAgentRuntime مرة واحدة لبدء الجلسة، مما يبدأ تشغيل الوكيل وخادم تطوير Vite. PreviewApp قرأ رابط URL لنقطة نهاية Session من تلك الاستجابة وفتح نقطة نهاية محلية للمنفذ 8090. ثم تتبع الخطوات المرقمة في الشكل 1 طلبًا واحدًا لإجراء تغيير:

1. يحمّل جزء الموقع في صفحة المعاينة الموقع من نقطة النهاية المحلية على localhost:8088. تضيف نقطة النهاية المحلية بيانات اعتمادك إلى كل طلب ومصافحة WebSocket، وتعيد توجيهها إلى نقطة نهاية Session. تتحقق نقطة نهاية Session endpoint من التوقيع والمنفذ مقابل allowedPortsثم تعيد توجيهها إلى خادم تطوير Vite على المنفذ 8090. تحافظ الصفحة على بقاء WebSocket الخاص بإعادة التحميل الفوري في Vite مفتوحًا.
2. ترسل مطالبة من جزء المحادثة. PreviewApp يرسلها إلى InvokeAgentRuntime كنداء AWS API قياسي موقّع ببيانات اعتماد AWS الخاصة بك، ويوصلها runtime إلى الوكيل على المنفذ 8080. تُبَث خطوات الوكيل إلى جزء المحادثة أثناء عمله.
3. يستدعي الوكيل Claude Haiku 5.5 في Amazon Bedrock ليقرر ما يجب تغييره.
4. يقرأ الوكيل ملفات الموقع ويحفظ الملفات التي يغيّرها. يقدم خادم تطوير Vite تلك الملفات ويراقبها بحثًا عن التغييرات.
5. عند حفظ ملف، يدفع Vite التغيير عبر WebSocket الذي فُتح في الخطوة 1، عائدًا عبر نقطة نهاية الجلسة (Session endpoint) ونقطة النهاية المحلية، فيتحدّث جزء الموقع دون إعادة تحميل.
6. من دفتر الملاحظات، PreviewApp يقرأ مسار الوكيل (agent’s route) الخاص بالوكيل /status على المنفذ 8081 عبر نفس نقطة نهاية الجلسة. الاختلاف الوحيد هو المنفذ.

المنفذ 8080 غير موجود في allowedPorts، لأن InvokeAgentRuntime يصل إلى الوكيل دون المرور عبر نقطة نهاية الجلسة.

المتطلبات الأساسية

لمتابعة هذا الاستعراض التوضيحي، تحتاج إلى:

• حساب AWS في منطقة AWS تتوفر فيها نقاط نهاية الجلسة الخاصة بـ AgentCore runtime، مع بيانات اعتماد مُهيأة.
• أذونات لإنشاء دور AWS Identity and Access Management (IAM)، والتحميل إلى Amazon Simple Storage Service (Amazon S3)، وإنشاء runtime، إضافة إلى bedrock-agentcore:InvokeAgentRuntime و bedrock-agentcore:InvokeAgentRuntimeProxy على ذلك الـ runtime ونقطة نهاية الـ DEFAULT الخاصة به. للحصول على التفاصيل، راجع أذونات IAM الخاصة بـ AgentCore runtime.
• Python 3.10 أو أحدث، مع bedrock-agentcore 1.25.2 أو أحدث و boto3 1.43.122 أو أحدث.
• Gitلاستنساخ مستودع العينة، وبيئة Jupyter ، مثل JupyterLab أو Visual Studio Code مع إضافة Jupyter، لتشغيل دفتر الملاحظات.
• إمكانية الوصول إلى Claude Haiku 5.5 في Amazon Bedrock. للإطلاع على توفر النماذج حسب المنطقة، راجع التوفر الإقليمي حسب النماذج.
• Node.js الإصدار 22 أو أحدث مع npm، وهي الأداة التي يستخدمها سكربت النشر لحزم الوكيل والموقع الإلكتروني.

ينشر النموذج الوكيل كملف zip في Amazon S3 مع النشر المباشر للشيفرة لـ Node.js، لذا لا تحتاج إلى Docker أو إلى مستودع Amazon Elastic Container Registry (Amazon ECR) . تعمل نقاط نهاية الجلسة مع بيئات تشغيل microVM، ولا تعمل مع نوع الحوسبة Instances، كما أن عناوين URL لنقاط نهاية الجلسة يمكن الوصول إليها عبر HTTPS العام. لا تدعم AWS PrivateLink الاتصالات الواردة.

نشر الوكيل وموقعه الإلكتروني

أولاً، تقوم بنشر بيئة التشغيل، والإعداد الذي تختاره هنا يحدد المنافذ التي يمكن لنقطة نهاية الجلسة الوصول إليها. يجمع سكربت النشر الوكيل في ملف واحد، ويضيف الموقع الإلكتروني وتبعياته لنظام Linux على معمارية Arm64 الخاص ببيئة التشغيل، ويرفع ملف zip إلى Amazon S3، وينشئ بيئة التشغيل.

المقتطف التالي من deploy.py يوضح الإعدادين المهمين لهذه المقالة. protocolConfiguration يحدد أين يستمع الوكيل إلى InvokeAgentRuntime، و allowedPorts يسرد المنافذ التي يمكن لنقطة نهاية الجلسة الوصول إليها: 8090 للموقع الإلكتروني و8081 لمسار حالة الوكيل. المنفذ 8080 ليس في القائمة، لأن InvokeAgentRuntime يصل إلى الوكيل بدونه. للحصول على إعدادات المنفذ والمسار، راجع تكوين منفذ خدمة الوكيل ومسار الاستدعاء.

agentRuntimeArtifact={"codeConfiguration": {
    "code": {"s3": {"bucket": code_bucket(), "prefix": S3_PREFIX}},
    "runtime": "NODE_22",
    "entryPoint": ["app.js"],
}},
protocolConfiguration={"serverProtocol": "HTTP", "port": 8080, "path": "/invocations"},
allowedPorts=[{"port": 8090}, {"port": 8081}],

تجعل إعدادات Vite للموقع الإلكتروني خادم التطوير قابلاً للوصول من نقطة نهاية الجلسة. فهو يستمع على 0.0.0.0 على المنفذ 8090 ولا يقيد رأس Host (server.allowedHosts هو true)، لأن الطلبات تصل تحت اسم مضيف تعيّنه بيئة التشغيل بدلاً من localhost. تنفّذ نقطة نهاية الجلسة المصادقة على كل طلب قبل وصوله إلى الخادم، لذا لا يحتاج الخادم إلى فحص مضيف خاص به.

لنشر بيئة التشغيل:

1. استنسخ مستودع النموذج وانتقل إلى مجلد النموذج:

git clone https://github.com/awslabs/agentcore-samples.git
cd agentcore-samples/01-features/02-host-your-agent/01-runtime/03-advanced/16-session-endpoints

2. افتح session_endpoints_preview.ipynb من مجلد النموذج.

3. شغّل خلية التثبيت، التي تثبت تبعيات Python.

4. شغّل خلية %run deploy.py . يستغرق النشر بضع دقائق، معظمها في انتظار وصول بيئة التشغيل إلى حالة READY .

افتح المعاينة

بعد جاهزية بيئة التشغيل، تبدأ المعاينة. استدعاء واحد يقوم بثلاثة أشياء: يبدأ جلسة (وهذا يشغّل الموقع الإلكتروني)، ويفتح نقطة نهاية محلية للمنفذ 8090، ويقدم صفحة المعاينة على localhost:8087.

from preview_app import PreviewApp

app = PreviewApp().start()
print("Open", app.url)

من الداخل start()، تكون النداءات التي تستخدم نقاط نهاية Session قصيرة. النداء الأول InvokeAgentRuntime يُعيد عنوان URL في ترويسة استجابة، session_endpoint_url يقرأه، ويفتح عميل نقطة نهاية Session نقطة نهاية محلية للمنفذ 8090:

answer = client.invoke_agent_runtime(
    agentRuntimeArn=runtime_arn, runtimeSessionId=session_id,
    payload=json.dumps({"prompt": ""}).encode(), contentType="application/json",
)
endpoint = client.session_endpoint_client(session_endpoint_url(answer))
local = endpoint.open_local_endpoint(port=8090, local_port=8088).start()

لفتح المعاينة:

1. شغّل الخلية التي تبدأ PreviewApp.
2. افتح الرابط المطبوع، http://localhost:8087في متصفحك.

تعرض الصفحة الموقع على اليمين، مقدَّمًا من المنفذ 8090 في الجلسة، ودليلًا قصيرًا مع طلبات مقترحة على اليسار.

اطلب من الوكيل إجراء تغيير

الآن تطلب تغييرًا وتراقب وصوله. كل مطالبة تذهب إلى الوكيل عبر InvokeAgentRuntime. يقرأ الوكيل الملفات التي يحتاجها، ويكتب الملفات التي يغيّرها، ويبلّغ عن كل خطوة أثناء حدوثها. عند حفظ ملف، يدفع خادم تطوير Vite التغيير عبر WebSocket الخاص به، عبر نقطة نهاية Session ونقطة النهاية المحلية، فيتحدّث الموقع في مكانه.

لطلب تغيير:

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

يعرض الفيديو التالي صفحة المعاينة أثناء عمل الوكيل عبر عدة طلبات. اختيار طلب مقترح يرسله إلى الوكيل، وتسرد لوحة المحادثة كل ملف يقرأه الوكيل ويحفظه، وتتحدّث لوحة الموقع على اليمين دون تحديث الصفحة، من السمّة الداكنة إلى زر أخير مكتوب عليه Order ahead بلون أخضر.

الشكل 2: صفحة المعاينة أثناء عمل الوكيل

تتدفّق الخطوات لأن الوكيل يجيب بأحداث مرسَلة من الخادم عندما تطلبه ذلك. يمكنك إرسال المطالبات نفسها من Python باستخدام app.ask، الذي يقرأ التدفق بواسطة iter_events من حزمة bedrock-agentcore SDK. تتحدّث الصفحة المفتوحة بالطريقة نفسها:

for event in app.ask("Make the Order ahead button green"):
    if "step" in event:
        print("  ", event["step"])
    elif "done" in event:
        print(event["done"]["reply"])

يجب أن يشبه خرج سكربت Python هذا ما يلي:

   Looking at the site's files
   Reading src/main.js
   Reading src/style.css
   Reading index.html
   Saved src/style.css
The Order ahead button is now green instead of brown, with white text kept for contrast. You can see it in the hero section, just below the "Small batch coffee, roasted every morning" heading at the top of the page.

الوصول إلى منفذ ثانٍ في الجلسة نفسها

الموقع ليس الخادم الوحيد الذي يمكنك الوصول إليه. يقدّم الوكيل /status على المنفذ 8081، الذي يسرد كل مطالبة والملفات التي غيّرتها. نقطة نهاية Session نفسها تصل إليه، والفارق الوحيد هو وسيط المنفذ.

status = app.endpoint.request("GET", "/status", port=8081)
print("GET /status on port 8081: HTTP", status.status)
for edit in status.json()["edits"]:
    print("  ", edit["prompt"], "->", ", ".join(edit["files"]))

يجب أن يشبه خرج سكربت Python هذا ما يلي:

GET /status on port 8081: HTTP 200
   Make the Order ahead button green -> src/style.css

ما ترفضه نقطة نهاية Session

عندما يرفض وقت التشغيل طلبًا، فإنه يستجيب برمز حالة HTTP وجسم فارغ ورمز خطأ في ترويسة الاستجابة، حتى تتمكن من التمييز بين رفضه والأخطاء التي يُرجعها تطبيقك. ترسل دفتر الملاحظات طلبًا إلى منفذ خارج allowedPorts وطلبًا بدون بيانات اعتماد، ويرفض وقت التشغيل كليهما بالرمز 403 AccessDenied.

يسرد الجدول التالي حالات الرفض التي من المرجح أن تواجهها أثناء البناء باستخدام نقاط نهاية الجلسات.

كيف تتم حماية الوصول إلى جلستك

يزيل وقت التشغيل ترويسات المصادقة الخاصة به قبل إعادة توجيه الطلب، لذلك لا يستقبل الموقع الإلكتروني توقيعك. تُسجَّل الطلبات في AWS CloudTrail كما InvokeAgentRuntimeProxy الأحداث، مع مصدر الحدث bedrock-agentcore.amazonaws.com. تعمل نقطة النهاية المحلية ببيانات اعتمادك، لذا فهي تحدّ ممن يمكنه استخدامها. وهي تستمع على 127.0.0.1 يستجيب فقط للطلبات الموجهة إلى عنوانه المحلي الخاص، ويرفض اتصالات WebSocket التي تفتحها صفحات من مصادر أخرى. شغّل نقطة النهاية المحلية فقط أثناء استخدامك للمعاينة. لمزيد من المعلومات، راجع تسجيل طلبات نقطة نهاية الجلسة في CloudTrail.

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

تحل أدوات الملفات الخاصة بالوكيل (agent) كل مسار داخل مجلد الموقع وترفض المسارات الخارجة عنه، لذا لا يمكن لطلب توجيه (prompt) أن يجعل الوكيل يغيّر ملفات أخرى في الجلسة. إذا كان بإمكان أشخاص آخرين إرسال طلبات توجيه إلى وكيل البرمجة الخاص بك، ففكر في Amazon Bedrock Guardrails لتصفية طلبات التوجيه والاستجابات الضارة، وراجع تغييرات الوكيل قبل نشرها.

التنظيف

لتجنب الرسوم المستمرة، أوقف المعاينة واحذف الموارد التي أنشأها النموذج التوضيحي. الموقع الذي عدّله الوكيل موجود في الجلسة، لذا يزول مع الجلسة.

للتنظيف:

1. شغّل خلية الإيقاف، واضغط Enter عندما يطلب ذلك الدفتر. هذا يوقف صفحة المعاينة ونقطة النهاية المحلية والجلسة.

2. شغّل خلية %run cleanup.py التي تحذف بيئة التشغيل والرمز المرفوع ودور IAM.

الخاتمة

تمنحك نقاط نهاية الجلسة وصولاً مُصادقاً إلى التطبيقات في جلسة وقت تشغيل AgentCore من أدواتك الخاصة عبر HTTP/1.1 وHTTP/2 وWebSocket، على المنافذ التي تسمح بها. في هذا المقال، نشرتَ وكيل برمجة مع موقع Vite في جلسته، وفتحت الموقع الحي في متصفحك عبر نقطة نهاية محلية، وطلبت من الوكيل سمة داكنة، ورأيت التغيير يصل أثناء حفظ الوكيل للملف. كما وصلتَ إلى منفذ ثانٍ في الجلسة نفسها وأكّدتَ ما ترفضه نقطة نهاية الجلسة.

للمضي خطوة أبعد، شغّل الدفتر باستخدام موقعك الخاص في مجلد site، أو غيّر أدوات الوكيل لتتوافق مع طريقة عمل وكيل البرمجة لديك. للاطلاع على مجموعة الخيارات الكاملة، بما في ذلك نطاقات المنافذ وOAuth وHTTP/2 وgRPC، راجع الاتصال بجلسات وقت التشغيل عبر نقطة نهاية جلسة.

لتغيير المنفذ أو المسار الذي InvokeAgentRuntime يستخدمه في وكيلك الخاص، راجع تكوين منفذ الخدمة ومسار الاستدعاء لوكيلك. إذا كان وكيلك يحتاج أيضًا إلى تشغيل أوامر البناء أو الاختبار في نفس الجلسة، راجع تنفيذ أوامر الصدفة في جلسات AgentCore runtime. لنشر وكيل Node.js الخاص بك من ملف zip بالطريقة التي يتبعها هذا المثال، راجع النشر المباشر للكود لـ Node.js. وللاطلاع على كل ما يقدمه الخدمة غير ذلك، ابدأ من استضافة وكيل أو أدوات باستخدام Amazon Bedrock AgentCore runtime، واعثر على المزيد من الأمثلة في مستودع agentcore-samples على GitHub.

عن المؤلف